How to use Lorem.space for generating random image placeholders with your local images
Tags: design, webdev, go
Published: 2021-11-15 18:02:39

Lorem.space is an online API to generate categorized random image placeholders with custom sizes for your design layout.

## What the hell is that?
Consider that you want to design a movie website or app, instead of downloading a bunch of movie covers, resizing them, and using them statically, you only set an URL (like https://api.lorem.space/image/movie?w=150&h=220) and each time a random movie cover will return.

To use API you can simply send a request to `https://api.lorem.space/image/movie?w=150&h=220`. This will return a random movie cover image in 150x220px dimensions. Some other categories like the game cover, music cover, store items, … are available and you can check https://lorem.space for more information.

---

## How to run Lorem.space on your local machine
Lorem.space is an open-sourced program, you can download and run both frontend and backend apps on your local machine.

### Run the server from binaries
* Download the latest binary for your operating system: https://github.com/manasky/lorem-server/releases
* Extract the downloaded file
* Open Terminal (for macOS or Linux) and CMD (for windows) and navigate to the extracted folder.
* Make sure the file is executable (grant permissions if needed)
* Run the server with these commands:

```
# For macOS or Linux:
./lorem-server -host "127.0.0.1:8080" - dir "~/Pictures"
# This will run the server on port 8080 and serves images from ~/Pictures directory

# For Windows:
lorem-server.exe -host "127.0.0.1:8080" -dir "C:\Users\USER\Pictures"
# This will run the server on port 8080 and serves images from `C:\Users\USER\Pictures` directory
```

### Run the server from source code
Lorem.space server is written in Golang and you can access the source code from here: https://github.com/manasky/lorem-server
To run the server from codes, follow these steps:

* Install Go: https://golang.org/dl/
* Clone the repository: `git clone https://github.com/manasky/lorem-server.git`
* Go to the directory of source code, create a new directory named `images` and put your images (.JPEG format) here. Each directory in `images` is considered as a category. for example, you can create a directory named `car` and put all cars’ images there.
* Open Terminal (for macOS and Linux) or CMD (for Windows), then `cd` to the directory of source codes and run: `go run main.go`
* Now the server is running on `127.0.0.1:8080`. Open `http://127.0.0.1:8080/image` in your browser and a random image from the `images` directory is returned.

### Options
Some arguments are available to run the server:
* `host`: The IP and port of the server host
* `dir`: The address of the images directory
* `cache`: Enables file caching to prevent resizing the image in the same request
* `cdn`: CDN domain
* `min-width`: minimum supported width size in px
* `max-width`: maximum supported width size in px
* `min-height`: minimum supported height size in px
* `max-height`: maximum supported height size in px

### Run the server with Docker
A built docker image of the Lorem server is available. You can pull the image by this command:
`docker pull ghcr.io/manasky/lorem-server:latest`
To run the docker image, you need to create a `.env` file containing the server configs:
```
HOST=0.0.0.0:8080
DIR=/app/images
MIN_WIDTH=20
```

Then in the directory of `.env` run this command in terminal:
```
docker run - env-file=./.env -p 8080:8090 -v ~/Pictures:/app/images ghcr.io/manasky/lorem-server:latest
```

* ` — env-file` sets the application environment variables path. Here `.env` file exists in the current path.
* `-p 8080:8080` sets up a port forward. the application container will listen to the `8080` port (set in the .env file as HOST). This flag maps the container’s port `8080` to port `8080` on the host (here, your localhost).
* `~/Pictures:/app/images` sets up a bind-mount volume that links the directory `/app/images` from inside the app container to the directory `~/Pictures` on the host machine (here, your system). The app image directory is set in the `.env` file as `/app/images`, so here the `~/Pictures` is mounted to that.

After container running, the app will scan `/app/images` which is mounted to the directory `~/Pictures` of your system & serves the HTTP server on 127.0.0.1:8080. Visit `127.0.0.1:8080/image` for start.

## Contribute
Feels free to contribute to the repository or file an issue for feedback or bug reporting in Github.