Skip to content
Wallpaper Server Wallpaper Server Docs

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.

Prerequisites

Section titled “Prerequisites”
  • Go 1.27.0 or newer to build from source. The module selects Go 1.27.4 for security fixes; allow automatic toolchain downloads or install that patch release.
  • 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

Section titled “Build from source”
Terminal window
git clone https://github.com/Ajaymamtora/wallpaper-server.git
cd wallpaper-server
go mod download
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:

Terminal window
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.

Terminal window
./wallpaper-server --start

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

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

Then verify it is serving images:

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

Docker

Section titled “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:

Terminal window
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:

Terminal window
docker run -d \
  --name wallpaper-server \
  -p 127.0.0.1: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, cache_dir to /app/cache, and server.host to 0.0.0.0. Binding to 127.0.0.1 inside the container prevents Docker’s host port mapping from reaching the service. The example publishes the port only on the host’s loopback interface. For persistence, mount a writable uploads directory.

The Docker image starts the server by default. The explicit --start and --config arguments in the example override the default command to select the mounted configuration file.

Systemd service

Section titled “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:

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

Manage the service with the usual systemd commands:

Terminal window
systemctl status wallpaper-server
systemctl restart wallpaper-server
systemctl stop wallpaper-server

To remove the service:

Terminal window
sudo ./wallpaper-server --uninstall-service

Upgrading

Section titled “Upgrading”

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

Terminal window
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.

Remote access and version upgrades

Section titled “Remote access and version upgrades”

Read Security and remote access before opening the listener to a LAN or placing a reverse proxy in front of it. For upgrades from 1.3.x, follow Migrating to 2.0 because remote administrative access changes.

Version 2 module installation

Section titled “Version 2 module installation”

Once a v2.0.0 release tag is published and verified, the Go install command is:

Terminal window
go install github.com/ajaymamtora/wallpaper-server/v2@v2.0.0

The /v2 suffix is required by Go semantic import versioning. For an unreleased source branch, build the repository checkout instead of assuming that the tag already exists.

Next steps

Section titled “Next steps”