random-image-server

A simple http server that returns a random image from a pre-configured directory.

The server exposes the following endpoints:

• GET /health: Returns a 200 OK response to indicate the server is running.
• GET /random: Returns a random image from the configured sources.
• GET /sequential: Returns the next image in sequence from the configured sources.

Features

• Random image serving: Returns a random image from among the configured sources.
• Sequential image serving: Enumerates images sequentially from the configured sources.
• In-memory caching: Caches images at startup for fast access.
• File system caching: Caches images on disk for reduced memory usage.
  • if cached images are modified externally, the server will detect this and invalidate the entry in the cache.
    • TODO: instead, the server should reload the image from the source and update the cache.
• Can serve png, jpg, and webp images, as well as animated gifs.
• Supports both local file paths and URLs as image sources.
• Configurable via a config.toml file.
• Graceful shutdown on termination signals.
• Logging, with configurable log levels.

Configuration

The server can be configured using a config.toml file. The configuration file should be placed in the same directory as the binary. The configuration file should have the following structure:

[server]
port = 8080 # The port the server will listen on
host = "0.0.0.0" # The host the server will bind to
log_level = "info" # The log level for the server, can be "error", "warn", "info", "debug", or "trace"
sources = [
    "/path/to/image.jpg", 
    "/path/to/another/image.png",
    "/path/to/image/directory", 
    "http://example.com/images"
]

[cache]
# Configuration for the cache backend
backend = "file_system" # The type of cache backend to use, can be "in_memory" or "file_system"

You can also override the configuration using environment variables. The environment variables should be prefixed with RANDOM_IMAGE_SERVER_, and the keys should be in uppercase with underscores instead of dots. For example, to set the port, you can use the environment variable RANDOM_IMAGE_SERVER_PORT.

Installation

follow instructions in the Release page for the latest release, which involves curling a script and piping it to sh, or install from crates.io:

cargo install random-image-server

Usage

As a Docker Container

I don't know how to publish the docker image to a registry without having to pay for it, so you will have to build the image yourself. So, you'll need to clone the repository and build the image yourself.

You can build and run the server as a docker container using the provided Dockerfile and docker-compose file.

1. Make sure to update the config.toml file with your desired configuration, and update the compose.yml file to mount the configuration file and any image directories you want to serve.
2. Build the docker image with docker compose build:
3. Run the docker container with docker compose up:

This will start the server and expose it on port 8080. You can access the server at http://localhost:8080.

As a Systemd Service

After downloading the binary:

1. put the binary in /usr/local/bin/random-image-server
2. download the random-image-server.service file from the repo and place it in /etc/systemd/system/
3. place your config.toml file in /etc/random-image-server/config.toml, and edit it to your liking.
4. run the following commands to enable and start the service:

sudo systemctl enable random-image-server.service
sudo systemctl start random-image-server.service

You can check the status of the service with:

sudo systemctl status random-image-server.service

and view the logs with:

sudo journalctl -u random-image-server.service