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.
By Simon Vasconcelos Lee
Published on 18 November 202614 minute read
wallabag/wallabag image, MariaDB, Redis, and the web port published on 127.0.0.1 behind an HTTPS reverse proxy.SYMFONY__ENV__SECRET and your public address in SYMFONY__ENV__DOMAIN_NAME; then change the password of the wallabag account, which is wallabag.X-Forwarded-Proto: https: that is how wallabag knows its visitors arrive over HTTPS.compose.yaml, then update by changing the image tag and running the migrations.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.
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 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:
memory_limit to 256 MB by default since its version 2.6.16, and the PHP_MEMORY_LIMIT variable changes it.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.
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:
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:
openssl rand -hex 32
docker compose up -d
docker compose logs -f wallabag
127.0.0.1: the repository’s example publishes the container’s port 80 without an address, and Docker then opens it on every address of the server. Published locally, it is reachable only through the reverse proxy.MYSQL_ROOT_PASSWORD, the image creates the database and its user, then runs wallabag:install, which creates the tables and the wallabag account. The wallabag is ready! line in the log marks the end.wallabag service; the db service keeps it.wallabag-db holds the database, wallabag-images the article images. The example in the installation documentation uses named volumes too.redis.2.6.17, 2.6, 2 and latest. A full version lets you choose when each update happens.To check that the application responds, query the route the image’s health check uses:
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.
/var/www/wallabag/data/db/wallabag.sqlite; mount a volume on /var/www/wallabag/data in that case.SYMFONY__ENV__DATABASE_DRIVER=pdo_pgsql, port 5432, and POSTGRES_USER and POSTGRES_PASSWORD so the image creates the database. Version 2.6.15 of the image fixes database ownership with PostgreSQL 15 and later.POPULATE_DATABASE=False, then initialize it once with docker compose exec --user nobody wallabag php bin/console wallabag:install --env=prod -n. The README asks you to run this command as nobody, so that no files end up owned by root.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:
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.
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.
ssh -L 8080:127.0.0.1:8080 user@read.example.com
wallabag and wallabag.| Variable | Default value | What it does |
|---|---|---|
SYMFONY__ENV__SECRET | A public string, the same for every instance | Adds entropy to security operations: the documentation wants it unique to your instance |
SYMFONY__ENV__DOMAIN_NAME | https://your-wallabag-instance.wallabag.org | The full address of your instance, without a trailing slash |
SYMFONY__ENV__FOSUSER_REGISTRATION | false in the Docker image | Opens or closes public registration |
SYMFONY__ENV__FOSUSER_CONFIRMATION | true | Sends a confirmation email for each registration |
SYMFONY__ENV__LOCALE | en | The default language of the instance, such as fr |
SYMFONY__ENV__SERVER_NAME | Your wallabag instance | The 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.
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.
X-Forwarded-Proto header: the proxy must send it with the value https.Host header: your domain name, so the application’s redirects point to it.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:
read.example.com {
reverse_proxy 127.0.0.1:8080
}
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:
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;
}
}
sudo nginx -t
sudo certbot --nginx
Then check that SYMFONY__ENV__DOMAIN_NAME holds the https:// address, the same as your proxy’s.
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.
| Tool | What it does | What it needs |
|---|---|---|
| Android app | Syncs your article lists and shows them on your phone | The instance address, your username and your password; the app fetches its feed credentials by itself |
| iOS app | Shows your articles on iPhone and iPad | The address, an API client ID and secret, your username and your password |
| wallabagger extension, for Firefox and Chrome | Saves the open page, with its tags, starred or archived | The address, an API client ID and secret, your username and your password |
| “bag it!” bookmarklet | Saves the open page from the bookmarks bar | Nothing: you drag it from the “Howto” page |
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:
| Service | The file to provide |
|---|---|
| Pocket, CSV export | Pocket’s export ZIP, once extracted: a CSV file named like part_000000.csv |
| Pocket, HTML export | The HTML file of Pocket’s older export, like ril_export.html |
| Instapaper | The CSV from Instapaper’s settings page |
| Omnivore | The metadata_x_to_y.json files from the extracted export, one at a time |
| Pinboard, Delicious | Their JSON export |
| Shaarli | Its HTML export |
| Firefox, Chrome | Firefox’s JSON bookmark backup, or Chrome’s Bookmarks file |
| Readability, elCurator | Their export |
| wallabag 1.x or 2.x | The 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.
So that a large import does not hold up the page, wallabag hands it to Redis, which the compose.yaml above already provides:
1.pocket_csv; it works through the queue, then keeps listening until you stop it.docker compose run --rm wallabag import pocket_csv
The other types are pocket, readability, instapaper, wallabag_v1, wallabag_v2, firefox and chrome.
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:
- 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
@ becomes %40. If an encoded character stops the startup, the documentation suggests doubling the percent sign: %%40.FROM_EMAIL is the sender of all wallabag email, TWOFACTOR_SENDER the sender of two-factor codes. Use an address on your domain that your SMTP server accepts to send from.:465 at the end of the line.Then recreate the container with docker compose up -d, and test with a “Forgot your password?” link from the login page.
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:
| Item | Where it lives | How to copy it |
|---|---|---|
| The settings | Your compose.yaml: the image builds parameters.yml from it at every start | A copy of the file, kept safe, since it holds your secrets |
| The database | The wallabag-db volume | An export with mariadb-dump |
| The images | The wallabag-images volume, mounted on web/assets/images | An archive of the 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.
On a new installation, start the stack with the same compose.yaml, then load the database and the images back:
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.
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:
docker compose pull
docker compose up -d
docker compose exec --user nobody wallabag php bin/console doctrine:migrations:migrate --env=prod --no-interaction
var/import, and its release notes ask you to empty the old web/uploads/import folder. In this compose.yaml, that folder lives inside the container: the one created from the new image starts without it.make update, which picked, on instances running 2.6.15 or older, an alpha release published that morning. For a Git installation left stuck, its release notes give the repair: git checkout 2.6.17 --force, then make update.make update, which also runs the migrations and clears the cache.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.
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.
| Topic | Our teams | You |
|---|---|---|
| The server | System and security updates, server interventions included | The timing that suits your business |
| Monitoring | Server monitored 24/7, with intervention without waiting for your call | Reading your instance’s logs |
| wallabag | Proactive monitoring: errors, slowdowns, database and disk space spotted, fix recommended | Its installation, updates and settings, which you apply, yourself or through your AI assistant |
| Accounts and articles | The server that carries them, monitored and backed up | Users, registration, API clients and imports |
| Backups | Every night, encrypted and kept off the machine; restores included | wallabag’s own exports, and the restore request, when you need one |
| Migration | Your current server migrated, free of charge | The 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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
Simafri
Let's talk about your project
Tell us what you need in a few words: we will get back to you quickly.
Thank you! Your request has been sent. We'll get back to you shortly.
Prefer email? Write to us at support@simafri.com.