Migrating to 2.0

Version 2.0.0 introduces client CLI commands and tightens administrative HTTP access. The version is a major bump because previously allowed unauthenticated remote management requests may now receive 401. The existing read-only wallpaper retrieval endpoints and their query parameters remain available.

Release status

This page describes the 2.0.0 source version. It is not a claim that a v2.0.0 tag or downloadable release has already been published. Check the Releases page before following these steps on a production instance.

Compatibility matrix

Area	Before (1.3.x)	After (2.0.0)	Action
Default bind host	0.0.0.0	127.0.0.1	Explicitly opt into LAN binding if needed.
Random image and metadata APIs	Public to reachable clients	Still public to reachable clients	No request format change.
Upload, delete, settings and refresh	Reachable without built-in credentials	Configured admin credentials required for local and remote clients; tokenless direct loopback only	Configure secure access or SSH tunnel.
Gallery and cached image read	Public when reachable	Still public when reachable	Don’t expose private images unintentionally.
/manage, /rotation, /settings and /server pages	Accessible remotely	Remote requests require an admin browser session/local access	Sign in at /login over HTTPS or use a trusted SSH tunnel.
Uploads after refresh/restart	Might disappear if uploads_dir wasn’t also indexed	Included in scans automatically	Remove any duplicate folder entry if desired.
JSON metadata path field	Exposed original filesystem path	No longer exposed	Remove any client dependency on the local path.
Random image caching	Could be cached for an hour	no-store; indexed image access is checked for current visibility	Clients/proxies should fetch new responses.
CLI	--start, systemd and version flags	Adds library curation, collections, rotation profiles, native wallpaper apply, diagnostics and scripts	See the CLI guide.

Go module import path

The module path changes to github.com/ajaymamtora/wallpaper-server/v2. Once the v2 release is tagged and available, use go install github.com/ajaymamtora/wallpaper-server/v2@v2.0.0. Go programs importing the project’s packages must update their import paths to include /v2. The old v1 module and its retractions remain separate.

Before upgrading

1. Back up your configuration, source wallpaper folders and uploads folder.
2. Record how your clients reach the service, including reverse-proxy arrangements, firewall rules and any scripts that use /api/upload, /api/refresh, /api/settings or DELETE.
3. Check that scripts consuming JSON do not depend on the internal path field.
4. Plan how administrative calls will authenticate — bearer token over TLS or a trusted SSH tunnel.
5. Verify an upgraded binary in an isolated environment before replacing the production service.

Step 1: update the network configuration

For local-only use, leave the host unset or write:

server:
  host: 127.0.0.1
  port: 8519

For LAN image access, explicitly bind to the LAN interface or all interfaces:

server:
  host: 0.0.0.0
  port: 8519

Do not expose the administrative routes directly to the internet. See the security guide.

Existing explicit bind values

An existing config with server.host: 0.0.0.0 will continue to bind to all interfaces. The new default only applies when the host is omitted. Inspect your actual YAML rather than assuming the upgrade makes the service private automatically.

Step 2: update remote administrative scripts

On the server, configure a long, random WALLPAPER_SERVER_ADMIN_TOKEN in the service’s environment.

For a CLI caller:

export WALLPAPER_SERVER_URL=https://wallpapers.example.com
export WALLPAPER_SERVER_ADMIN_TOKEN='your-long-random-secret'
wallpaper-server upload ~/Pictures/example.jpg

For an existing curl script:

curl --fail-with-body -X POST \
  -H "Authorization: Bearer $WALLPAPER_SERVER_ADMIN_TOKEN" \
  -F "file=@$HOME/Pictures/example.jpg" \
  https://wallpapers.example.com/api/upload

Do not embed credentials in the URL. For a same-host reverse proxy, configure the backend token: it is checked for loopback connections too. Without a token, the proxy must not expose administrative routes. Additional authentication at the proxy is recommended.

Step 3: verify behaviour

wallpaper-server --version
wallpaper-server config validate --path ~/.config/wallpaper-server/config.yaml
wallpaper-server status
wallpaper-server list --limit 5
wallpaper-server download --output ./smoke-test.jpg

Validate the upload path and deletion restrictions against disposable test images only. Remember that config validate can create directories as a side effect.

Step 4: restart your service

Use the same installation method you already use. For systemd:

sudo systemctl restart wallpaper-server
sudo systemctl status wallpaper-server

Updating /api/settings writes the YAML but does not dynamically switch the running listener or replace the current list of watched folders; restart when changing those settings.

Data migration and recovery

The server stores persistent metadata, tags, favourites, collections and rotation state in data_dir/library.json. The image cache is disposable; do not delete the data directory when upgrading or clearing cache. Back up library.json, the source folders and uploads_dir together.

For a consistent backup, stop the server and local rotation workers first. Copy the configuration, the entire data_dir, and uploads_dir (including private trash) together with your source images. Keep a second copy outside the machine; protect metadata backups as private data. The client offline cache is not a source-image backup.

To recover, stop the service, preserve the damaged directories for diagnosis, then restore one coherent snapshot to the same configured paths and ownership. Do not merge individual JSON fragments or replace a corrupt library with an empty file. Start against the restored configuration, check favourites, collections and trash, and only then enable automatic monitoring. If source paths must change, test an isolated restore first: identity recovery cannot guess between identical duplicate files.

The new deletion behaviour is deliberately non-destructive for source folders: DELETE /api/wallpapers/{id} hides source images. Uploaded wallpapers are placed in private trash and may be restored by an administrator; only explicit purge permanently removes a managed upload.

Delete and restore now record move intents before touching uploaded files. Startup and refresh replay interrupted transitions; a collision stops recovery rather than overwriting another image. Always restore metadata and uploads from the same backup. Historical orphan trash files without recovery metadata cannot automatically reconstruct their original paths.

On Windows, process-interruption recovery is supported, but POSIX directory-fsync power-loss durability is not promised. On POSIX, directory-sync failures remain commit failures. See storage guarantees.

Browser administration supports /login backed by an HttpOnly, SameSite=Strict session cookie. When an admin token is configured, localhost clients must authenticate too; tokenless direct-loopback use remains supported.

Known limitations

This is a single-administrator library, not a multi-user gallery: role-based access, per-user private collections and general rate limiting are not implemented. Optional local multimodal search and host-approved HTTPS import are available but require explicit setup; search is bounded rather than a persistent full-library embedding index.

Native adapters differ across macOS, Windows and Linux. A successful build or mock-command test does not verify real desktop permissions, compositor IPC, hotplugging or multi-display restoration. Validate your actual desktop before relying on unattended schedules. No release tag is implied by this source tree.