Self-host wallabag on a managed VPS: your read-it-later list on your own server

When you self-host wallabag on a managed VPS, the articles you save for later stay on a machine of your own, which our teams keep up to date and monitor day and night. wallabag is a free, open source read-it-later application under the MIT license. This guide follows its official documentation and Docker image, at version 2.6.17: installing with Docker Compose, the first account and the secrets, HTTPS, apps and browser extensions, importing from Pocket and other services, email, backups and updates.

Simon Vasconcelos Lee By Published on 18 November 202614 minute read

All guides

In short

  1. The MIT license lets you use, modify and redistribute wallabag freely, at work or anywhere else, as long as you keep its copyright notice.
  2. Install it with Docker Compose: the official wallabag/wallabag image, MariaDB, Redis, and the web port published on 127.0.0.1 behind an HTTPS reverse proxy.
  3. Before the first start, set SYMFONY__ENV__SECRET and your public address in SYMFONY__ENV__DOMAIN_NAME; then change the password of the wallabag account, which is wallabag.
  4. The reverse proxy sends X-Forwarded-Proto: https: that is how wallabag knows its visitors arrive over HTTPS.
  5. Back up the database, the images volume and your compose.yaml, then update by changing the image tag and running the migrations.

What wallabag does

wallabag is a read-it-later web application: you save a page in one click and read it when you have time. Its README sums it up as click, save, read it when you want. wallabag extracts the article’s content, so you are not distracted by the pop-ups of the original page.

What the MIT license allows

wallabag is published under the MIT license, copyright Nicolas Lœuillet since 2013. It grants, free of charge, the right to use, copy, modify, merge, publish, distribute, sublicense and sell copies of the software. You can therefore run it for yourself, your team or your clients, with no license to buy.

The only condition is to keep the copyright notice and the license text in all copies or substantial portions of the software. The text provides the software “as is”, without warranty.

The resources to plan for

The wallabag documentation does not put a figure on memory or CPU. It does list what the application needs, and the Docker image sets a few values that help with sizing:

Server size therefore depends on the number of users, the volume of articles and your imports. On a managed VPS, tell us about your usage and we will recommend the right size.

Installing with Docker Compose

The wallabag/docker repository publishes the official wallabag/wallabag image on Docker Hub and GitHub Container Registry, with an example Compose file: wallabag, a MariaDB database and Redis. On a server with Docker installed, create a folder and put this compose.yaml in it, based on that example:

compose.yaml
services:
  wallabag:
    image: wallabag/wallabag:2.6.17
    restart: unless-stopped
    environment:
      - MYSQL_ROOT_PASSWORD=root-password
      - SYMFONY__ENV__DATABASE_DRIVER=pdo_mysql
      - SYMFONY__ENV__DATABASE_HOST=db
      - SYMFONY__ENV__DATABASE_PORT=3306
      - SYMFONY__ENV__DATABASE_NAME=wallabag
      - SYMFONY__ENV__DATABASE_USER=wallabag
      - SYMFONY__ENV__DATABASE_PASSWORD=database-password
      - SYMFONY__ENV__DATABASE_CHARSET=utf8mb4
      - SYMFONY__ENV__SECRET=random-secret-string
      - SYMFONY__ENV__DOMAIN_NAME=https://read.example.com
      - SYMFONY__ENV__MAILER_DSN=smtp://user:password@smtp.example.com:587
      - SYMFONY__ENV__FROM_EMAIL=read@example.com
      - SYMFONY__ENV__TWOFACTOR_SENDER=read@example.com
    ports:
      - "127.0.0.1:8080:80"
    volumes:
      - wallabag-images:/var/www/wallabag/web/assets/images
    depends_on:
      - db
      - redis
  db:
    image: mariadb
    restart: unless-stopped
    environment:
      - MYSQL_ROOT_PASSWORD=root-password
    volumes:
      - wallabag-db:/var/lib/mysql
    healthcheck:
      test: ["CMD", "/usr/local/bin/healthcheck.sh", "--innodb_initialized"]
      interval: 20s
      timeout: 3s
  redis:
    image: redis:alpine
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 20s
      timeout: 3s

volumes:
  wallabag-images:
  wallabag-db:

Replace the three secret values before the first start. Hexadecimal strings work everywhere, including in the SQL commands the image writes to create the database:

Terminal
openssl rand -hex 32
docker compose up -d
docker compose logs -f wallabag

To check that the application responds, query the route the image’s health check uses:

Terminal
curl http://127.0.0.1:8080/api/info

The image reads the SYMFONY__ENV__* variables again at every container start and clears the cache. After you change the compose.yaml, a docker compose up -d recreates the container and applies the new settings.

With SQLite or PostgreSQL

Without Docker

The way the documentation recommends on a dedicated server is the Git repository and its Makefile, with Composer, the make tool and the PHP extensions on the requirements page:

Terminal
git clone https://github.com/wallabag/wallabag.git
cd wallabag && make install

The web server then serves the web folder, with app.php as its entry point: the virtual hosts page gives Nginx, Apache, Caddy and lighttpd configurations. Its examples serve wallabag at the root of a domain or subdomain, the setup the maintainers support.

The first account, the secrets and sign-ups

Installation creates an administrator account whose username and password are both wallabag, with the address wallabag@wallabag.io. Change them before opening the instance to the public. An SSH tunnel brings the server’s port 8080 to your computer, at http://localhost:8080; add -p and the SSH port shown in your client area.

Terminal, on your computer
ssh -L 8080:127.0.0.1:8080 user@read.example.com
  1. Sign in with wallabag and wallabag.
  2. In “Config”, “Password” tab, choose a new password of at least 8 characters.
  3. In the “User information” tab, replace the email address with yours: it receives the password reset links.
  4. In the same tab, turn on two-factor authentication. The documentation recommends a one-time code app, such as FreeOTP, over the code sent by email; wallabag also offers backup codes.
VariableDefault valueWhat it does
SYMFONY__ENV__SECRETA public string, the same for every instanceAdds entropy to security operations: the documentation wants it unique to your instance
SYMFONY__ENV__DOMAIN_NAMEhttps://your-wallabag-instance.wallabag.orgThe full address of your instance, without a trailing slash
SYMFONY__ENV__FOSUSER_REGISTRATIONfalse in the Docker imageOpens or closes public registration
SYMFONY__ENV__FOSUSER_CONFIRMATIONtrueSends a confirmation email for each registration
SYMFONY__ENV__LOCALEenThe default language of the instance, such as fr
SYMFONY__ENV__SERVER_NAMEYour wallabag instanceThe instance name shown in your two-factor app

Public registration is therefore closed with the Docker image. To open the instance to your team, create the accounts yourself from “Users management”, or open registration while people sign up, with email confirmation.

The more sensitive settings are under “Internal Settings”, reserved for the instance administrator: public sharing of articles, export formats, sign-in to paywalled sites, local image downloads and background imports.

HTTPS: the reverse proxy

The container serves wallabag over HTTP, on its port 80, through an internal Nginx. HTTPS is handled by the reverse proxy in front of it. That internal Nginx reads the X-Forwarded-Proto header: when it is https, it tells PHP the request is encrypted, and wallabag builds its links and cookies accordingly.

With Caddy

Caddy obtains the Let’s Encrypt certificate itself and renews it. Its reverse_proxy directive keeps the Host header and adds X-Forwarded-For, X-Forwarded-Proto and X-Forwarded-Host by default:

Caddyfile
read.example.com {
  reverse_proxy 127.0.0.1:8080
}

With Nginx

This block uses the headers from the Nginx example in the Docker image’s README, adds the Host header and the image’s upload limit, and listens on port 80 so Certbot can set up HTTPS:

Nginx block
server {
    listen 80;
    listen [::]:80;
    server_name read.example.com;
    client_max_body_size 100M;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Host $server_name;
        proxy_set_header X-Forwarded-Proto https;
        proxy_set_header X-Forwarded-For $remote_addr;
    }
}
Terminal
sudo nginx -t
sudo certbot --nginx

Then check that SYMFONY__ENV__DOMAIN_NAME holds the https:// address, the same as your proxy’s.

Apps, browser extensions and RSS feeds

wallabag works in the browser, and the project also publishes apps and an extension, which connect to your instance by its address, without a trailing slash.

ToolWhat it doesWhat it needs
Android appSyncs your article lists and shows them on your phoneThe instance address, your username and your password; the app fetches its feed credentials by itself
iOS appShows your articles on iPhone and iPadThe address, an API client ID and secret, your username and your password
wallabagger extension, for Firefox and ChromeSaves the open page, with its tags, starred or archivedThe address, an API client ID and secret, your username and your password
“bag it!” bookmarkletSaves the open page from the bookmarks barNothing: you drag it from the “Howto” page

Importing your articles from Pocket and elsewhere

The “Import” menu brings in your articles from another service. wallabag fetches the content of each article again, which takes time on a large export. The importers in version 2.6.17:

ServiceThe file to provide
Pocket, CSV exportPocket’s export ZIP, once extracted: a CSV file named like part_000000.csv
Pocket, HTML exportThe HTML file of Pocket’s older export, like ril_export.html
InstapaperThe CSV from Instapaper’s settings page
OmnivoreThe metadata_x_to_y.json files from the extracted export, one at a time
Pinboard, DeliciousTheir JSON export
ShaarliIts HTML export
Firefox, ChromeFirefox’s JSON bookmark backup, or Chrome’s Bookmarks file
Readability, elCuratorTheir export
wallabag 1.x or 2.xThe JSON export of another instance

Version 2.6.17 also brings a fix to the Pocket CSV import. Import through the Pocket API exists too, with a developer key the administrator sets in the configuration.

Large imports in the background

So that a large import does not hold up the page, wallabag hands it to Redis, which the compose.yaml above already provides:

  1. In “Internal Settings”, “Import” section, enable Redis with the value 1.
  2. Start the import from the “Import” menu: wallabag puts the articles in a queue.
  3. Start the worker for the chosen import type, for example pocket_csv; it works through the queue, then keeps listening until you stop it.
Terminal, in the compose.yaml folder
docker compose run --rm wallabag import pocket_csv

The other types are pocket, readability, instapaper, wallabag_v1, wallabag_v2, firefox and chrome.

Email: the SMTP configuration

wallabag sends email for registration confirmation, password resets and two-factor codes by email. It sends them through the server described by SYMFONY__ENV__MAILER_DSN, which defaults to smtp://127.0.0.1.

On a Simafri VPS, configure an authenticated SMTP server, on port 587 or 465: your domain’s mail service, or a sending service. The documentation gives the one-line format, with user, password, server and port:

compose.yaml, wallabag service
      - SYMFONY__ENV__MAILER_DSN=smtp://read%40example.com:password@smtp.example.com:587
      - SYMFONY__ENV__FROM_EMAIL=read@example.com
      - SYMFONY__ENV__TWOFACTOR_SENDER=read@example.com

Then recreate the container with docker compose up -d, and test with a “Forgot your password?” link from the login page.

Backups

The documentation’s backup page names three items: the settings, the database and the pictures. With the Docker image, here is where each one lives:

ItemWhere it livesHow to copy it
The settingsYour compose.yaml: the image builds parameters.yml from it at every startA copy of the file, kept safe, since it holds your secrets
The databaseThe wallabag-db volumeAn export with mariadb-dump
The imagesThe wallabag-images volume, mounted on web/assets/imagesAn archive of the folder
Terminal, in the compose.yaml folder
docker compose exec -T db sh -c 'exec mariadb-dump -uroot -p"$MYSQL_ROOT_PASSWORD" wallabag' > wallabag-$(date +%F).sql
docker compose exec -T wallabag tar -czf - -C /var/www/wallabag/web/assets images > wallabag-images-$(date +%F).tar.gz
cp compose.yaml compose-$(date +%F).yaml

Schedule these copies and send them off the server. Stored on its disk, these archives are also included in its nightly backups. With SQLite, the documentation asks you to copy the data/db folder.

Restoring

On a new installation, start the stack with the same compose.yaml, then load the database and the images back:

Terminal
docker compose exec -T db sh -c 'exec mariadb -uroot -p"$MYSQL_ROOT_PASSWORD" wallabag' < wallabag-2026-11-18.sql
docker compose exec -T wallabag tar -xzf - -C /var/www/wallabag/web/assets < wallabag-images-2026-11-18.tar.gz

Each user can also export their articles as JSON, from the “All entries” list, and import them again into another instance with the wallabag 2.x importer. For administrators, the wallabag:export command exports a user’s articles to a file.

Updates

With Docker, change the image tag in the compose.yaml, take a backup, then pull the new image and recreate the container. The README then asks you to run the database migrations when a release brings some:

Terminal, in the compose.yaml folder
docker compose pull
docker compose up -d
docker compose exec --user nobody wallabag php bin/console doctrine:migrations:migrate --env=prod --no-interaction

Read the release notes of each version before updating: they flag the steps specific to that version, such as the folder to empty in 2.6.16.

Who does what on a managed VPS

Self-hosting means running the server on top of the application. On a managed VPS, our teams take charge of the server and proactively monitor your instance; wallabag remains your software, with its settings and your articles.

TopicOur teamsYou
The serverSystem and security updates, server interventions includedThe timing that suits your business
MonitoringServer monitored 24/7, with intervention without waiting for your callReading your instance’s logs
wallabagProactive monitoring: errors, slowdowns, database and disk space spotted, fix recommendedIts installation, updates and settings, which you apply, yourself or through your AI assistant
Accounts and articlesThe server that carries them, monitored and backed upUsers, registration, API clients and imports
BackupsEvery night, encrypted and kept off the machine; restores includedwallabag’s own exports, and the restore request, when you need one
MigrationYour current server migrated, free of chargeThe timing of the switch

If you would rather have our teams work inside the application itself, that service is billed by the hour or at a fixed rate, with an estimate shared before the work starts.

wallabag, on a server run for you

With a Simafri Managed VPS, our teams keep your wallabag instance’s server up to date, monitor it day and night and step in without waiting for your call; they also proactively monitor your instance and recommend useful fixes, which you apply, yourself or through your AI assistant. Backups are encrypted every night and kept off the machine, restores are included, and migrating your current server is free.

Explore Managed VPS

Frequently asked questions

Is wallabag free?

Yes. wallabag is under the MIT license: you can use, modify and redistribute it, at work or anywhere else, with no license to buy, as long as you keep its copyright notice. What remains is the cost of the server that runs it.

How do I install wallabag with Docker Compose?

Start from the example compose.yaml of the wallabag/wallabag image, with MariaDB and Redis. Set SYMFONY__ENV__SECRET, the passwords and your address in SYMFONY__ENV__DOMAIN_NAME, publish the port on 127.0.0.1, then run docker compose up -d and put an HTTPS reverse proxy in front.

What are the default wallabag credentials?

Installation creates an administrator whose username and password are both wallabag. Change the password in Config, Password tab, and the email address in User information, before opening the instance to the public.

How do I import my Pocket articles into wallabag?

Extract the Pocket export ZIP: it contains a CSV file such as part_000000.csv. In the Import menu, choose Pocket CSV and upload that file. wallabag then fetches the content of each article; for a large export, enable Redis in the internal settings.

Which apps work with wallabag?

The project publishes Android and iOS apps and the wallabagger extension for Firefox and Chrome, which connect to your instance by its address, without a trailing slash. iOS and wallabagger need an API client, created in API clients management.

Why do wallabag links stay on http behind a proxy?

The image reads the X-Forwarded-Proto header to know the request is over HTTPS. Have your proxy send it with the value https, along with the Host header of your domain, and put the https:// address in SYMFONY__ENV__DOMAIN_NAME.

How do I back up wallabag?

Copy three items: the database, with mariadb-dump for MariaDB, the images volume mounted on web/assets/images, and your compose.yaml, which holds the settings and secrets. Send these copies off the server.

Does a managed VPS cover wallabag?

A managed VPS covers the server: system, security, monitoring and backups. Our teams also proactively monitor your instance and recommend useful fixes, which you apply. Work inside the application is billed by the hour or at a fixed rate.

Sources and official documentation

Contact us