PostgreSQL¶
SQLite remains the default. Set DATABASE_URL to an explicit postgres:// or postgresql:// connection URI to use PostgreSQL with either app runtime. Keep one app process per database.
Selecting another database does not migrate or merge data. A new database starts with an empty library; the existing SQLite file or PostgreSQL database is left separate. Recipe export/import can move configurations as paused copies, but does not preserve articles or reader links.
Run the commands below from the RSS Workshop checkout root. With RSS_IMAGE blank or unset, the default Compose installation pulls ghcr.io/ldogg123/rss-workshop:latest, which includes Chromium. Prepare the app configuration before adding PostgreSQL:
if [ ! -e .env ]; then
cp .env.example .env
fi
chmod 600 .env
# Edit .env: set ADMIN_PASSWORD to your chosen admin password.
sudo mkdir -p -m 700 ./data
sudo chown 65532:65532 ./data
sudo chmod 700 ./data
Keep an existing .env and its configured admin password or ADMIN_PASSWORD_HASH. The base app mount still requires the host directory selected by RSS_DATA_DIR, even when PostgreSQL is selected; use that path instead of ./data if customized. Add the database settings below before starting the app. For native operation, export the same authentication and database variables instead; see source setup.
Existing PostgreSQL server¶
Create a dedicated UTF-8 database and non-superuser login role. For example, an administrator can run these commands in psql; \password prompts without putting the password in the command text:
CREATE ROLE rss_workshop LOGIN;
\password rss_workshop
CREATE DATABASE rss_workshop OWNER rss_workshop TEMPLATE template0 ENCODING 'UTF8';
The app creates its tables and indexes in the selected database. Use a database reserved for RSS Workshop and a role that owns it. RSS Workshop requires server_encoding=UTF8 and forces client_encoding=UTF8, including when the URI or environment requests another client encoding. It refuses an incompatible database before initializing tables. PostgreSQL documents these database and client encodings. Set the connection URI in the private .env file for Compose, or export it for native operation:
DATABASE_URL='postgresql://rss_workshop:ENCODED_PASSWORD@db.example.net:5432/rss_workshop?sslmode=verify-full'
Replace the host, database, and password with your values. Percent-encode reserved characters in the user name and password, including @, :, /, %, ?, #, and spaces. The URI is read the way PostgreSQL's own client library reads it, which ends the credentials at the first @, so an unencoded one stops startup with percent-encode @ in the user name or password as %40. Python can encode a password without echoing it as you type; keep safe="", because the default leaves / unencoded:
python3 -c 'import getpass, urllib.parse; print(urllib.parse.quote(getpass.getpass("Password: "), safe=""))'
Query parameters follow the same rules: write each one as key=value, and percent-encode =, &, #, %, and spaces inside a value, as in sslrootcert=/run/secrets/db%20ca.pem. A + is a literal plus rather than a space, and a parameter given twice takes its last value. A malformed parameter stops startup with invalid PostgreSQL connection configuration. PostgreSQL documents connection URI encoding. Single quotes keep literal dollar signs from being expanded by Compose. A randomly generated hexadecimal password needs no URI encoding.
Use verified TLS for a remote server. If it uses a private certificate authority, mount its CA certificate read-only into the app and add the appropriate sslrootcert path to the URI. Database access uses ordinary administrator-configured networking; ALLOW_CIDRS governs scraped source pages and does not authorize database connections. Check the server's access rules and firewall separately.
Start or recreate the app. Do not include the PostgreSQL override when connecting to an existing server:
docker compose up -d --pull always --wait
New PostgreSQL container¶
The optional Compose override uses the Docker Official Image postgres:18-alpine. POSTGRES_DATA_DIR selects its host directory, defaulting to ./postgres-data, mounted at /var/lib/postgresql, the PostgreSQL 18 image's data location. The database has no published host port. The app waits for PostgreSQL's health check before starting.
For a new database, prepare the host directory before startup. Use the path configured in POSTGRES_DATA_DIR if it differs from the default:
sudo install -d -m 755 ./postgres-data
The mounted parent needs mode 0755 so the image's PostgreSQL user can traverse it. The official entrypoint manages ownership and mode 0700 on the actual database directory below it. With PostgreSQL 18, the cluster and server configuration files, including postgresql.conf and pg_hba.conf, live under POSTGRES_DATA_DIR/18/docker on the host. RSS Workshop's own connection and application settings remain in .env.
Compose refuses a missing host directory. Relative paths resolve from the directory containing compose.yaml; use an absolute path to keep storage elsewhere. Keep custom data paths outside the checkout, or exclude them from both Git and Docker builds. Existing named-volume databases need the migration procedure below.
Generate a unique password, for example:
python3 -c 'import secrets; print(secrets.token_hex(24))'
Copy the same generated value into both settings in .env:
POSTGRES_PASSWORD='YOUR_GENERATED_HEX_PASSWORD'
DATABASE_URL='postgres://rss_workshop:YOUR_GENERATED_HEX_PASSWORD@postgres:5432/rss_workshop?sslmode=disable'
Both variables are required by the override; there is no default password. DATABASE_URL is explicit so arbitrary passwords are not accidentally inserted into an invalid URI. sslmode=disable here is for this database's private Docker network, rather than a remote database connection.
docker compose -f compose.yaml -f compose.postgres.yaml up -d --pull always --wait
For the lightweight runtime, add -f compose.static.yaml immediately after the base file. With RSS_IMAGE blank or unset, that override pulls ghcr.io/ldogg123/rss-workshop:latest-static. An explicit RSS_IMAGE must match the selected browser or static runtime. Use the same overrides for later operations. For a local source build, follow build container images from source and retain the PostgreSQL override.
The official image's POSTGRES_USER=rss_workshop creates the bootstrap administrator for this dedicated container. Use the non-superuser setup above on a shared server. Initialization variables apply only to an empty data directory: changing POSTGRES_PASSWORD in .env does not change an existing database password. Rotate it in PostgreSQL and update DATABASE_URL together.
Keep the same host PostgreSQL directory on later runs. The app's RSS_DATA_DIR directory remains mounted at /data but is unused while DATABASE_URL selects PostgreSQL. To return to SQLite, clear DATABASE_URL and omit compose.postgres.yaml from the app's Compose command; keep the PostgreSQL directory for recovery. This does not copy PostgreSQL data back. Back up before changing backend or upgrading PostgreSQL. A PostgreSQL major-version upgrade needs its own supported database migration procedure; changing the image tag alone is insufficient.
Existing PostgreSQL named volumes¶
Changing POSTGRES_DATA_DIR does not copy an existing server's data. First stop RSS Workshop to prevent further writes, leaving the old PostgreSQL server running on its original volume. Keep the app stopped while creating and verifying a final logical dump using the backup procedure. Save the current image and Compose configuration, then stop PostgreSQL. Prepare a new, empty host directory and set POSTGRES_DATA_DIR to it.
Start only the database with the new bind mount, keeping the app stopped:
docker compose -f compose.yaml -f compose.postgres.yaml up -d --no-deps --wait postgres
Follow the restore procedure below to restore into a new database and verify the saved records before starting the app with that database selected. Keep the original named volume and configuration for rollback. Do not copy PostgreSQL's database files while it is running. For an existing SQLite volume, use the separate SQLite storage migration.
Backup and restore¶
Use PostgreSQL's pg_dump and pg_restore, not the SQLite backup utility or a copy of the app's /data directory. Use client tools compatible with your server, normally the same PostgreSQL major version. A logical dump captures a consistent database snapshot while the app remains running.
The dump includes saved refresh diagnostics. RSS Workshop upgrades any released schema to the current one transactionally on startup, so a v1.1.0, v1.1.1 or v1.2.0 database moves from schema 5 to schema 6 the first time this version runs, and an older one takes every step in the same transaction; retain a pre-upgrade dump to roll back, because an older release, v1.2.0 included, cannot read a newer schema. Unlike SQLite, PostgreSQL gets no automatic copy before the upgrade; the app logs a warning when it migrates, and the upgrade has a time limit of its own. See upgrade compatibility.
For the supplied Compose server, create a custom-format dump in a private backup directory. Keep any static or VPN overrides used by your deployment:
mkdir -p backups
chmod 700 backups
umask 077
docker compose -f compose.yaml -f compose.postgres.yaml exec -T postgres pg_dump \
-U rss_workshop -d rss_workshop --format=custom --no-owner --no-privileges \
> backups/postgres-before-upgrade.dump
docker compose -f compose.yaml -f compose.postgres.yaml exec -T postgres pg_restore \
--list < backups/postgres-before-upgrade.dump > /dev/null
Choose a new filename for every backup and check command exit status. Listing the archive checks its table of contents; a restore into a separate database verifies the saved data. Backups contain source URLs, articles, and working reader tokens. Keep a protected off-host copy and retain .env and deployment configuration separately.
Restore into a new, unused database while keeping the original:
docker compose -f compose.yaml -f compose.postgres.yaml exec -T postgres createdb \
-U rss_workshop -O rss_workshop -T template0 rss_workshop_restored
docker compose -f compose.yaml -f compose.postgres.yaml exec -T postgres pg_restore \
-U rss_workshop -d rss_workshop_restored --exit-on-error --single-transaction \
--no-owner --no-privileges < backups/postgres-before-upgrade.dump
docker compose -f compose.yaml -f compose.postgres.yaml exec -T postgres psql \
-U rss_workshop -d rss_workshop_restored -v ON_ERROR_STOP=1 \
-c 'SELECT version FROM schema_version;' \
-c 'SELECT count(*) AS saved_feeds FROM feeds;' \
-c 'SELECT count(*) AS saved_items FROM items;'
After those commands succeed, change the database name in DATABASE_URL to rss_workshop_restored. Keep RSS_IMAGE pinned to the saved compatible image digest during recovery, then recreate the app:
docker compose -f compose.yaml -f compose.postgres.yaml up -d --no-deps --no-build --pull never --wait rss-workshop
docker compose -f compose.yaml -f compose.postgres.yaml exec -T rss-workshop /rss-workshop -healthcheck
Sign in and verify the feed library and sample RSS/Atom output before discarding any old backup or database. Reverting the URI to the original database provides rollback while it remains available. Restored reader tokens and schedules come from the backup.
For an existing PostgreSQL server, use the same dump/restore options with that server's client tools and an administrator-created empty target database. Supply credentials through a protected password file or your database provider's tooling; avoid putting passwords directly in command arguments. Follow the provider's backup and recovery instructions when it manages the database.
Schema upgrade time¶
Startup allows 10 seconds to connect to PostgreSQL and check the schema version, or create the tables of an empty database. A schema upgrade runs in one transaction with up to 10 minutes of its own. Upgrading to schema 6 reads the whole stories table once, to start each feed's last new story at its newest saved one. A 1 GB table took under a second when cached; when neither PostgreSQL nor the host has cached it, as after a reboot, reading it takes about its size divided by the storage's read speed, such as 20 seconds at the 50 MB/s of an SD card or a slow network share. The log says PostgreSQL schema upgrade started, with the time limit, and then PostgreSQL schema upgrade finished, with how long it took.
The app answers no request until then, so its health check fails: after a little over a minute, about 70 seconds on Docker Engine 25 and newer, Docker marks the container unhealthy, and docker compose up --wait reports that. Docker does not restart a container for being unhealthy, and the upgrade goes on; follow it with docker compose logs -f rss-workshop. If a service manager limits how long a native process may take to start, allow at least 10 minutes. Stopping or restarting the app meanwhile rolls the upgrade back, and the next start begins it again.
If the upgrade has not finished after 10 minutes, or the app receives a stop signal while it runs, the app cancels it on the PostgreSQL server before exiting. The transaction rolls back, the database stays at schema 5 with every row as it was, and startup stops with cannot migrate PostgreSQL database from schema version 5 to 6: the upgrade did not finish within 10 minutes; the database is unchanged, or startup was interrupted in place of the time limit. After a timeout, Compose restarts the app, which tries again.
While an upgrade runs, a second app process started against the same database stops after 5 seconds with cannot lock PostgreSQL schema initialization: another connection is initializing or upgrading this database; run one application process per database. A start stops the same way after the app was killed outright during an upgrade, as by docker kill or a host failure rather than a stop signal: PostgreSQL then rolls the upgrade back only when the statement it was running ends, within 10 minutes.
To check the size of the table first, and on very slow storage read it into the cache just before starting this version, run these queries; replace the Compose command with your own client for an existing server:
docker compose -f compose.yaml -f compose.postgres.yaml exec -T postgres psql \
-U rss_workshop -d rss_workshop -v ON_ERROR_STOP=1 \
-c "SELECT pg_size_pretty(pg_relation_size('items')) AS stories_table;" \
-c 'SELECT max(first_seen) FROM items;'
If the upgrade keeps running out of time, for example because the table cannot be read in 10 minutes and the host's memory cannot cache it, the database is still at schema 5, and v1.2.0 opens it as it is.