How to Self-Host Wallabag in 2026: Imports, Database and Background Jobs

The shortest Wallabag demo proves that a process listens on port 80. Production needs stronger evidence. It must pass this scenario even after the container has been replaced: save a normal article and a difficult page, run background retrieval, sync a mobile client and search archived content.

Wallabag is being deployed for a clear purpose: read-it-later archive that removes page clutter. Its most common deployment trap is that assets or login redirects use HTTP because the domain variable is wrong, so public URL handling and durable state receive the same attention as image startup.

Turn the local command into an inspectable service

The following command makes the container boundary visible without pretending to provision every external service.

docker run -d \
  --name wallabag \
  --restart unless-stopped \
  -p 127.0.0.1:80:80 \
  -v wallabag-data:/var/www/wallabag/data \
  -e SYMFONY__ENV__DOMAIN_NAME=https://app.example.com \
  wallabag/wallabag:latest

Before opening ingress, inspect the resolved environment, mounts and listener. Add the reviewed connection settings for Postgres or MariaDB, Redis and scheduled import workers; use private names for private services. A successful launch ends when you can save a normal article and a difficult page, run background retrieval, sync a mobile client and search archived content, not when docker ps prints Up.

What Wallabag depends on

Draw three boundaries around Wallabag: ingress to port 80, durable state and supporting requirements. The container is replaceable, but the other two need explicit owners. The network contract for Wallabag is Postgres or MariaDB, Redis and scheduled import workers. Keep private endpoints on internal DNS, permit only required outbound calls and give Wallabag a scoped service credential.

The diagram is complete when a clean client can save a normal article and a difficult page, run background retrieval, sync a mobile client and search archived content. Capture timing and resource data for page fetching, parser work, image downloads, queues and database growth. If the transaction fails, the first boundary that does not behave as documented identifies whether to investigate routing, local capacity or a supporting service.

Lock down Wallabag after bootstrap

Do not inherit security assumptions from a local tutorial. Wallabag's specific concern is keeping default credentials or skipping trusted proxy configuration. Production should therefore remove default credentials, protect import tokens and configure trusted proxies before exposing the reader.

SYMFONY__ENV__DOMAIN_NAME is configuration rather than a secret; keep its value explicit while protecting the separate credentials used by Wallabag. Scope filesystem and network access, protect setup endpoints and define upload, request or execution limits around page fetching, parser work, image downloads, queues and database growth.

Make the public origin unambiguous

Expose one HTTPS hostname for Wallabag; keep raw port 80 private. Set the domain name to the final HTTPS URL. This prevents browsers and API clients from learning two competing addresses.

From a clean client, run the known-good transaction and inspect the first failing request. Use the custom-domain guide when DNS or TLS is wrong. Treat “assets or login redirects use HTTP because the domain variable is wrong” as a separate application diagnosis once the route is proven.

Separate replaceable containers from lasting data

The durable recovery set is database, images, imported content and configuration. Mount /var/www/wallabag/data before bootstrap, write harmless sample data and replace the container to prove that path is actually persistent. A volume protects data from container replacement, but not from host loss, accidental deletion or application-level corruption.

Take backups that understand the data source: use logical dumps for live databases when required and copy files only from a consistent state. Keep one encrypted copy away from the Wallabag host. The acceptance criterion for a restore is specific — articles, tags, annotations, users and API tokens return and the mobile client synchronizes. The restore-tested backup guide explains why job success alone is insufficient.

Evidence to collect before Wallabag goes live

For Wallabag, define a known-good transaction before launch: save a normal article and a difficult page, run background retrieval, sync a mobile client and search archived content. Put its prerequisites, expected response and cleanup steps in version control without secret values. Pin the image used to establish that reference.

Use the transaction to validate a replacement and an independent restore. The restored service is acceptable only when articles, tags, annotations, users and API tokens return and the mobile client synchronizes. At the same time, observe page fetching, parser work, image downloads, queues and database growth and turn the slowest or most constrained part into a service-level alert.

The gate also needs a negative case: temporarily deny the test identity access to Postgres or MariaDB, Redis and scheduled import workers. Confirm that Wallabag produces an actionable error while preserving data, restore the valid condition and repeat the known-good transaction. Keeping both results prevents a superficial health endpoint from becoming the only production evidence.

Operate Wallabag around its real bottleneck

Build dashboards around page fetching, parser work, image downloads, queues and database growth. A CPU graph without that workload context cannot explain why Wallabag is slow. Add a synthetic or scheduled check that tries to save a normal article and a difficult page, run background retrieval, sync a mobile client and search archived content using harmless test data.

Before upgrading, account for this application-specific hazard: Wallabag migrations, parser behavior and worker configuration should be tested against representative saved pages. Restore a recent backup into an isolated deployment, run migrations there and compare behavior. If assets or login redirects use HTTP because the domain variable is wrong, inspect the boundary involved — public origin, storage or dependency — before touching unrelated settings.

Use Dockup for the platform layer

For Wallabag, Dockup can create the route and TLS certificate, preserve mounts, deliver secrets and place Postgres or MariaDB, Redis and scheduled import workers on private networking while deploying to either Dockup or attached servers.

The release gate is still the concrete Wallabag transaction: save a normal article and a difficult page, run background retrieval, sync a mobile client and search archived content. Also verify the restore condition — articles, tags, annotations, users and API tokens return and the mobile client synchronizes. Those two checks show whether the deployment works and whether it can be recovered.

Frequently asked questions

What does Wallabag need for a production deployment?

Route the Wallabag container on port 80 through one HTTPS origin. The supporting network requirement is Postgres or MariaDB, Redis and scheduled import workers. Do not call Wallabag ready until you can save a normal article and a difficult page, run background retrieval, sync a mobile client and search archived content.

Which Wallabag data belongs in a backup?

Persist /var/www/wallabag/data and include database, images, imported content and configuration in the same recovery manifest. A clean Wallabag restore passes only when articles, tags, annotations, users and API tokens return and the mobile client synchronizes.

Does Wallabag require HTTPS behind a reverse proxy?

Use HTTPS for the public Wallabag origin and keep port 80 on the internal route. Apply the Wallabag setting correctly: set the domain name to the final HTTPS URL. For Wallabag, HTTPS protects credentials or user content in transit and keeps origin-sensitive client behavior consistent.

How should a Wallabag upgrade be tested?

Restore current Wallabag state into an isolated deployment, apply the candidate version and repeat its acceptance transaction. Pay particular attention because Wallabag migrations, parser behavior and worker configuration should be tested against representative saved pages. Keep the previous Wallabag image until its data-migration and rollback boundary are understood.