wrolpi/docker
lrnselfreliance 6cd233dce6
Sync and backup: a secondary WROLPi and a backup drive copy the library (#957)
* A secondary WROLPi copies its primary's library over HTTP

A WROLPi with role "secondary" pulls from its primary: a manifest of every
FileGroup's files (/api/sync/manifest), then each missing or changed file
from the primary's Caddy /media/ (resumable, written to a hidden partial and
renamed with the primary's mtime), a refresh, then the library configs,
imported as the primary wrote them.  wrolpi.yaml contributes only its library
settings.  Files deleted on the primary are kept.

A secondary never saves the synced configs and never downloads.  Its API
answers 503 SYNCING while a sync runs, and every page warns that it is a
copy.  It syncs in a daily window or on "Sync now"; WROL Mode stops it.

On a Pi 4 (no AES instructions) the client uses TLS 1.2 ChaCha20, which
pulls ~110 MB/s from Caddy versus ~41 MB/s for rsync over ssh.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Sync has its own /admin tab; a sync's reads from the primary are bounded

The sync settings and progress move from Settings (and the component
gallery, which is for library components) to /admin/sync.

A download never writes past the size in the primary's manifest, and configs,
listings, and manifest pages are capped.  A primary address may not carry a
user name or password (it is logged and shown).  While a sync runs, the API
answers only the exact requests that show its progress or stop it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* A sync keeps the secondary's replaced configs in today's config backup

The first copy of the day is kept, like a save, so a config backup import
undoes a sync's config changes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Docker's Caddy logs every request

`docker compose logs -f web` shows each request with its status, size and
duration, e.g. a secondary's /media/ downloads during a sync.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* A sync reports its progress as it downloads, and refuses quietly

The status updated only when a page of 500 FileGroups finished, so a page of
large files looked stuck; it now updates every 2 seconds.  Requests refused
while syncing are answered by the middleware instead of raised, so the UI's
polling no longer logs an error each time.  The primary's version is stored
without its trailing newline.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* A WROLPi can back up to a second drive; sync settings live in sync.yaml

The Sync tab's Backup Drive copies the media directory to a second mounted
drive with rsync during the sync window (hourly), or on "Back Up Now".
Nothing on the backup drive is deleted.  The Tags and playlists directories
are left out (WROLPi rebuilds them from the configs), and the database is
written as an SQLite snapshot rather than copied as files, so the drive can be
mounted as the media directory and start.  A backup is written only while the
chosen drive (by UUID) is mounted where it was chosen, and is not the media or
system drive; rsync is stopped if the drive disappears.  Not in Docker, which
cannot reach other drives.

Role, primary, window and backup drive move from wrolpi.yaml to sync.yaml:
they belong to this machine, and are never copied from a primary.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* The Sync tab shows the configured backup drive

getSettings copies each setting by name and did not list the backup drive,
so the Sync tab showed "None" while one was configured.  It also dropped
`version`.  A test now fails for any setting the API sends that getSettings
drops.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* A backup can go to a folder on its drive, and remembers its last success

The Backup Drive panel takes a folder on the chosen drive.  The drive is
checked through the folder's mount point: the folder is written only when the
drive with the saved UUID is mounted there, so a folder left on the system
drive by an unplugged drive, or on another drive mounted inside the chosen
one, is refused.  A missing folder is created once the drive is checked.

When the last backup succeeded is saved in sync.yaml, so it is known after a
restart.  "Stop Backup" is disabled while the database snapshot is written (it
runs to the end), and a finished backup clears the request to stop.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* The backup drive has its own window

The sync window was shown in the Sync panel but also scheduled the backup
drive.  The Backup Drive panel now has its own window (sync.yaml
backup_window_start/end), saved with the drive; the sync window is shown,
and used, only for a secondary's sync.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Sync and the backup drive can each exclude folders

A secondary or a backup drive may be smaller than the primary's library.
Each Sync tab panel has its own excluded folders in sync.yaml, chosen in
a folder browser: a secondary browses its primary's folders (through
Caddy), the backup drive browses this WROLPi's media directory.  Excluded
folders are never copied; what was copied before is kept.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* The folder browser does not offer lost+found

Every ext4 drive has a root-only lost+found folder; a sync and a backup
never copy it, so it is not offered for exclusion.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* A sync never writes into config or tags, whatever their case

On a media drive that ignores case (exFAT, NTFS, macOS), a manifest path
like Config/wrolpi.db is the real config folder. The protected and
unlisted top-level folders are now compared case-insensitively in the
manifest, in resolve_destination, in excluded-folder validation, and in
both folder listings.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* A backup writes the database snapshot only when the database changed

Every backup rewrote the whole database snapshot (2.5 GB on a busy
WROLPi), even on the window's idle hourly runs. The snapshot is now
skipped when the live database (its size and mtime, and those of a
non-empty WAL) and the drive's copy are both unchanged since the last
snapshot. The record is in memory, so the first backup after a restart
writes it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* Remove the unused save_sync_config switch

Nothing activated it; SyncConfig saves directly.  The test server's
log_message override is called by http.server, so it goes in the
vulture baseline.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-11 10:53:45 -07:00
..
api Python packages install from hash-locked requirements; yt-dlp still floats (#913) 2026-11-01 12:00:39 -07:00
app serve, single-file and readability-extractor install from a committed lockfile (#912) 2026-10-31 10:39:08 -06:00
archive Python packages install from hash-locked requirements; yt-dlp still floats (#913) 2026-11-01 12:00:39 -07:00
controller Python packages install from hash-locked requirements; yt-dlp still floats (#913) 2026-11-01 12:00:39 -07:00
help A Zim's Search toggle is saved in zims.yaml so a rebuilt database or a newer Zim keeps it (#931) 2026-11-01 13:09:52 -07:00
samba Debian 13 (trixie) rebase: docker, debian-live-config, and pi-gen builds. 2026-07-13 15:43:08 -06:00
web Sync and backup: a secondary WROLPi and a backup drive copy the library (#957) 2026-11-11 10:53:45 -07:00
zim docker: web container reaps zombies; zim and help healthchecks can pass (#744) 2026-10-02 15:49:34 -06:00
README.md Postgres -> SQLite hard cutover: the database moves into the media directory. 2026-07-12 14:09:37 -06:00

WROLPi Docker

Development and testing environment using Docker containers.

Quick Start

git clone https://github.com/lrnselfreliance/wrolpi.git
cd wrolpi
git submodule update --init
docker-compose build --parallel
docker volume create --name=openstreetmap-data
docker volume create --name=openstreetmap-rendered-tiles
docker-compose run --rm api db upgrade
docker-compose up

Browse to https://localhost:8443

Services

Service Port(s) Description
web 8443 (HTTPS), 8084-8086 Caddy reverse proxy
api 8081 Sanic API server
app (via web) React frontend
controller 8080 System management (FastAPI)
archive 8083 SingleFile/Readability
zim (via web:8085) Kiwix
help (via web:8086) MkDocs documentation
map (via web:8084) OpenStreetMap tile server

TLS Certificates

WROLPi uses a two-tier PKI for HTTPS. A root CA is generated once and persists in the media directory. A leaf certificate is regenerated on every container start to pick up hostname and IP changes.

How it works

  1. On first start, the web container generates a root CA at /opt/media/config/ssl/.
  2. A leaf cert signed by the root CA is created at /etc/ssl/caddy/ inside the container.
  3. Caddy serves HTTPS on ports 443, 8084, 8085, and 8086 using the leaf cert.
  4. The Controller serves on port 80 with a certificate trust banner when needed.

Trusting the certificate

  1. Browse to http://<host-ip> to see the Controller. If the HTTPS certificate is not yet trusted, a banner will appear with the download link and platform-specific trust instructions.
  2. Download and install the root CA on your device.
  3. All HTTPS ports will work without browser warnings.

The root CA only needs to be trusted once. Leaf certs can be regenerated (hostname change, container rebuild) without needing to re-trust.

Name Constraints

The root CA is restricted to local/private networks only via X.509 Name Constraints. Even if the CA key were compromised, it cannot sign certificates for public domains.

Permitted:

  • DNS: *.local, localhost
  • IPv4: 127.0.0.0/8, 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16
  • IPv6: ::1, fc00::/7 (unique local), fe80::/10 (link-local)

EXTRA_SANS

The Docker container cannot discover the host's real LAN IP. Set EXTRA_SANS in a .env file so the leaf certificate includes your host's IP and hostname:

# .env
EXTRA_SANS=IP:10.0.0.5,DNS:myhost.local

Each entry must have a type prefix (IP: or DNS:). Multiple entries are comma-separated. After changing EXTRA_SANS, restart the web container:

docker compose up -d --build web

Regenerating the root CA

If you need to regenerate the root CA (e.g. after updating the certificate generation script), delete the old CA files and rebuild:

rm test/config/ssl/ca.crt test/config/ssl/ca.key
docker compose up -d --build web

All devices will need to re-download and re-trust the new CA from http://<host-ip>/ca.crt.

Volumes

The test/ directory is mounted to /opt/media inside containers, serving as the media directory for development. Certificate files, configs, and downloaded content are stored here.

Two external volumes are required for the map service:

docker volume create --name=openstreetmap-data
docker volume create --name=openstreetmap-rendered-tiles

Environment Variables

Variable Default Description
MEDIA_DIRECTORY /opt/media Media directory inside containers
EXTRA_SANS (empty) Additional SANs for the TLS leaf certificate
WEB_HOST 0.0.0.0 Host bind address for the web service
WEB_HTTPS_PORT 8443 HTTPS port
REACT_APP_API 0.0.0.0:8081 API bind address
UID 1000 User ID for api/app containers
GID 1000 Group ID for api/app containers

Upgrading

See UPGRADE.md for upgrade instructions.