Wallabag

Overview

Wallabag saves readable copies of articles for later. Tags, favourites, reading progress, and annotations help turn a reading queue into a useful reference library. Official Android and iOS clients connect to a self-hosted server; browser extensions are available, while a standalone desktop application is not included.

For a shared bookmark library, compare collection and archiving features with Linkwarden and Karakeep. Wallabag focuses on the reading experience. A saved URL does not guarantee extraction from a paywall, a login-only page, a JavaScript-only site, or every publisher’s layout.

This recipe runs Wallabag 2.6.15 with SQLite and separate volumes for the database/data and cached images. A short-lived initializer configures the database, applies migrations, and sets the administrator password before the web server can start. Registration remains disabled. Plan for one core, 512 MB RAM minimum (1 GB recommended), and 2 GB disk plus saved content; these are planning estimates, not a load benchmark.

The free self-hosted build supports password login and native two-factor authentication. TOTP, email delivery, mobile clients, and external reverse proxies are not configured or tested here. The application exposes an OAuth2 API; that does not provide OIDC or SAML login. A trusted-header login is not configured.

The application and deployment recipe are MIT licensed. This entry remains experimental pending wider deployment evidence. The reliable deployment level is unsupported: this single-server SQLite setup does not include a separate database, monitoring, or resource limits.

Security assessment

The reviewed configuration rejects placeholder credentials, replaces the upstream default password before accepting HTTP requests, closes registration, and binds the web port to loopback. The deployment owns the wallabag administrator password from .env; a password change in the interface is replaced during initialization. Limit article submission to trusted users and restrict outbound traffic. Stored data and backups are not end-to-end encrypted. This configuration review is not a security audit.

Sources: project and clients, official documentation, Docker image and initialization, 2.6.15 release, OAuth API, license.

Step-by-step guide

Prepare the server

Use Ubuntu 22.04+ or Debian 12+, Docker Engine, and Compose v2.24+. Plan for one CPU core, at least 512 MB RAM (1 GB recommended), and 2 GB disk plus articles and images. ARM64 and ARMv7 images exist but were not tested in this check.

mkdir -p ~/services/wallabag
cd ~/services/wallabag
# Copy all recipe files, including proxy/ and the scripts, here.
cp .env.example .env
chmod 600 .env
openssl rand -hex 32
openssl rand -hex 24

Put the first generated value in WALLABAG_SECRET and the second in WALLABAG_ADMIN_PASSWORD. Use different values. The initializer refuses the example password, the upstream default password, and passwords shorter than 16 characters. It also refuses the example application secret. The scripts source .env as trusted shell configuration; the recommended hexadecimal values need no escaping.

The data named volume holds SQLite under /var/www/wallabag/data/db, plus other application data. images holds cached images under /var/www/wallabag/web/assets/images. Both are scoped to the Compose project; keep the project name stable. Container configuration and cache are regenerated from the pinned image and .env.

Start and sign in

docker compose config --quiet
docker compose pull
docker compose up -d --wait --wait-timeout 600
curl --fail http://127.0.0.1:8087/api/info

The initialize service must finish successfully before wallabag can start. It uses the official migration command, then replaces the default administrator password. There is no interval in which the published web service accepts the upstream default credentials. Registration stays disabled.

From another computer run ssh -L 8087:127.0.0.1:8087 user@server, open http://localhost:8087, and sign in as wallabag with the password from .env. Update the administrator email in account settings. Do not delete or rename this deployment-owned account. An interface password change is replaced on the next initialization; rotate it in .env instead. Additional users can be created with the official administrator/console tools.

No SMTP, Redis, RabbitMQ, SSO provider, or mobile client is configured. Native TOTP/email two-factor authentication needs its own setup; verify recovery access before enabling it. Email delivery is unavailable until SMTP is configured.

VPS

Set WALLABAG_URL=https://read.example.com, configure DNS and an HTTPS proxy, then recreate the stack. Permit only SSH, HTTP, and HTTPS through the firewall. Leave port 8087 on loopback. Encrypt backups and keep a copy off-server.

Trusted local network

Use the SSH tunnel or an HTTPS proxy available to your trusted LAN/VPN. If you deliberately bind a private interface, restrict it with a firewall and set WALLABAG_URL to the exact address people open. Do not expose an HTTP password login to an untrusted network.

Domain and HTTPS

Choose a host-proxy example from proxy/. Caddy obtains certificates; Nginx needs your certificate paths; Traefik needs the websecure entry point and letsencrypt resolver. All examples forward to 127.0.0.1:8087. A containerized proxy needs a shared network and wallabag:80, not its own loopback.

Replace the sample hostname, set the matching HTTPS WALLABAG_URL, and run docker compose up -d --wait --wait-timeout 600. Forward Host and X-Forwarded-Proto correctly. The Nginx example permits 50 MB requests. Verify login and article capture through the final origin; external proxy and certificate issuance were not exercised in the native smoke.

Backup

./backup.sh

Wait for initialization to finish first. The script stops the web application, archives both complete volumes with active .env and Compose, and restarts it only if it was running. The private archive is backups/wallabag-<timestamp>.tar. Copy SQLite and its WAL together while writers are stopped; a personal article export does not contain every account, OAuth client, and setting.

Encrypt the archive and copy it off-server. It contains private articles, cached images, accounts, tokens, and the deployment-owned administrator password.

Restore

Restore replaces both volumes. Use a trusted archive and the matching application version. On a new host, copy the recipe and compare archived configuration.env and compose.yaml with your active configuration first. Archived configuration is not activated automatically; the active .env administrator password is enforced during initialization.

docker compose up -d --wait --wait-timeout 600
./restore.sh ./backups/wallabag-TIMESTAMP.tar
curl --fail http://127.0.0.1:8087/api/info

The script validates the payload, creates a safety backup, replaces the complete data/image volumes, and waits for health. A replacement failure leaves the app stopped. Sign in, open a private article, check its tags, and verify cached images or a mobile client’s API access. The amd64 smoke removes both original volumes before restoration and verifies an OAuth client, article, tags, anonymous access rejection, and a marker in the image volume.

Update

Read the release notes, create an off-server backup, and change WALLABAG_VERSION to the reviewed exact tag. Then:

docker compose pull
docker compose up -d --wait --wait-timeout 600
docker compose logs --tail=100 initialize wallabag

Initialization applies migrations before the web app starts and re-enforces the active administrator password. Verify login, a saved article, tags, and an API client after updating. Keep the pre-update archive. Never use latest or assume an older image can read a migrated database.

Rollback

1. Keep the pre-update archive and matching recipe/configuration.
2. Stop writers: docker compose stop wallabag.
3. Set the old exact image version in .env and restore any matching Compose changes. Pull the old image.
4. Run docker compose create without starting the old initializer or app on the migrated database.
5. Run ./restore.sh ./backups/wallabag-BEFORE-UPDATE.tar. Only after replacement will initialization and the app start. Check login, private articles, tags, images, and API access.

The safety backup reads the stopped volumes without starting an older app on new data. Restoring data does not automatically restore the archived administrator password: compare active .env explicitly.

Stop and remove

docker compose down removes containers and keeps the volumes. After verifying an encrypted off-server backup, docker compose down --volumes permanently removes accounts, articles, settings, OAuth clients, and cached images. Deleting the recipe directory also removes local backups and configuration. Avoid global Docker pruning.

Sources: official Docker image, documentation, console commands, OAuth API.

Report a recipe problem

Tell us how it went on your server

Opens a prefilled GitHub issue. A GitHub account is required; submitting the issue makes it public.

Troubleshooting

Initialization failed and the web app never started

Run docker compose ps --all and docker compose logs --tail=200 initialize wallabag. Replace both template secrets, use an administrator password of at least 16 characters, and keep the administrator named wallabag. Do not bypass the initializer: it removes the known upstream credentials before HTTP starts. After correcting .env, run docker compose up -d --wait --wait-timeout 600.

For a migration error, check disk with df -h, RAM with free -m, and the exact image version. Do not delete the database to fix startup. Keep a full backup before investigating.

A password change did not survive restart

The initializer enforces WALLABAG_ADMIN_PASSWORD for the deployment-owned administrator. Change that value in .env and recreate the stack to rotate it. A UI-only password change is overwritten on initialization. Deleting or renaming that administrator prevents initialization; use the matching backup or official console tools to recover it.

Login redirects to the wrong address

Check that WALLABAG_URL matches the browser origin and that the proxy forwards Host and X-Forwarded-Proto. Use http://localhost:8087 through the SSH tunnel for initial setup. Do not post the full output of docker compose config: it includes secrets.

An article is missing or unreadable

Paywalls, authentication, JavaScript-only pages, publisher changes, and unsupported layouts can prevent extraction. Confirm the source is reachable, review application logs, and try a public article. Restrict access to trusted users rather than opening the server’s internal network to every submitted URL. Check disk usage if cached images stop appearing.

A client or second factor does not work

Create an OAuth client in API/developer settings and use the documented OAuth2 flow; this is not OIDC single sign-on. Tokens and client secrets are sensitive. Mobile clients, TOTP, and SMTP are outside the verified scenario; an email-based second factor cannot deliver messages until SMTP works. Keep a verified recovery path before enabling it.

Backup or restore failed

Wait for initialization to complete. Use created containers and a trusted archive from this recipe. Confirm matching image versions and active secrets before recovery; the archived .env is not activated automatically. A failed replacement must not be treated as successful restoration. Keep both the source and safety archives until login, private articles, tags, images, and API access are checked.

Sources: documentation, Docker image, console commands, OAuth.