Installation

Wallpaper Server ships as a single Go binary. There are three supported ways to run it: building from source, running in Docker, or installing a systemd service. Building from source is the recommended path.

Note

There are currently no prebuilt binaries to download. Every method below compiles the server from source or in a container.

Prerequisites

• Go 1.25.0 or newer to build from source.
• Docker if you prefer to run it in a container.
• At least one folder of images to serve. The server refuses to start with no wallpaper folders configured.

Build from source

git clone https://github.com/Ajaymamtora/wallpaper-server.git
cd wallpaper-server
go mod tidy
go build -o wallpaper-server .

This produces a wallpaper-server binary in the current directory.

Before you can start it you need a configuration file that lists at least one wallpaper folder. See Configuration for the full format, or copy the bundled example.config.yaml:

mkdir -p ~/.config/wallpaper-server
cp example.config.yaml ~/.config/wallpaper-server/config.yaml

Edit the file so wallpaper_folders points at a real directory, then start the server. The --start flag is required — without it the binary only prints a hint and exits.

./wallpaper-server --start

By default the server loads its configuration from ~/.config/wallpaper-server/config.yaml. Use --config to point at another file:

./wallpaper-server --start --config /path/to/config.yaml

Then verify it is serving images:

curl "http://localhost:8519/api/wallpapers/random/image" --output wallpaper.jpg

Docker

The repository includes a multi-stage Dockerfile that builds a small Alpine image running as a non-root user. There is no published image to pull, so build it yourself:

git clone https://github.com/Ajaymamtora/wallpaper-server.git
cd wallpaper-server
docker build -t wallpaper-server .

Run it, mounting your wallpapers and a configuration file into the container. The image exposes port 8519:

docker run -d \
  --name wallpaper-server \
  -p 8519:8519 \
  -v /path/to/your/wallpapers:/app/wallpapers:ro \
  -v /path/to/config.yaml:/app/config.yaml:ro \
  wallpaper-server --start --config /app/config.yaml

Inside the container, set wallpaper_folders to /app/wallpapers and cache_dir to a writable path such as /app/cache.

Caution

Mount host folders that the container user (UID 1001) can read. If the gallery is empty, a permission or path mismatch on the mount is the most common cause.

Systemd service

On Linux you can install Wallpaper Server as a systemd service that starts on boot and runs as your current user. This requires sudo, which the binary uses to write the unit file to /etc/systemd/system/wallpaper-server.service:

sudo ./wallpaper-server --autostart --config ~/.config/wallpaper-server/config.yaml

Manage the service with the usual systemd commands:

systemctl status wallpaper-server
systemctl restart wallpaper-server
systemctl stop wallpaper-server

To remove the service:

sudo ./wallpaper-server --uninstall-service

Upgrading

To upgrade a source or Docker install, pull the latest code and rebuild:

git pull
go build -o wallpaper-server .

Your configuration file, cache and uploads are stored outside the build output, so rebuilding does not touch them.

Next steps

• Quick start — from zero to one returned wallpaper.
• Configuration — every field and default.