Deployment guide

wallabag

Overview

wallabag is an open-source, self-hosted read-it-later application: the private alternative to Pocket and Instapaper. Save any web page with one click, and wallabag extracts the readable content so you can read it later, distraction-free, on the web or in the official Android and iOS apps. You can tag and annotate articles, let tagging rules organise incoming content automatically, export to EPUB or PDF for offline reading, and import your existing library from Pocket, Instapaper or Readability.

This SecureAnyCloud image ships wallabag 2.6 served by nginx and PHP 8.3 FPM on a hardened Ubuntu 24.04 LTS base, patched at build time. It includes a bundled local MariaDB server, so the appliance is complete and useful on its own.

What you get:

wallabag 2.6 served by nginx and PHP 8.3 FPM, managed by systemd
A bundled MariaDB server holding the wallabag database, already installed and ready
A REST API for the official Android and iOS apps and the wallabagger browser extension
A per-VM administrator password generated on the first boot of every VM and recorded in a root-only file
No shipped default login: the default account seeded by the wallabag installer is removed before capture, the image ships with an empty users table, and the per-VM administrator is created on first boot
Public registration disabled by default, so your instance stays private
MariaDB bound to 127.0.0.1 only (the loopback interface, port 3306), never exposed to the network
A dedicated Azure data disk carrying both the MariaDB database and wallabag's saved article images
nginx.service, php8.3-fpm.service and mariadb.service as enabled systemd units
An unauthenticated /healthz endpoint for Azure Load Balancer health probes
24/7 SecureAnyCloud support

Prerequisites

You need an active Azure subscription, an SSH key pair, and a VNet with a subnet in the target region.

Standard_D2s_v3 (2 vCPU / 8 GiB RAM) is a sensible starting point for typical production use. A smaller size such as Standard_B2s works for personal reading lists.

Configure the network security group (NSG) to allow inbound 22/tcp from your management network, 80/tcp for the application, and 443/tcp if you terminate TLS on the VM. The bundled MariaDB listens on 127.0.0.1 only, so port 3306 stays off the network.

Step 1 - Deploy from the Azure Marketplace

Sign in to the Azure Portal, choose Create a resource, search the Marketplace for wallabag by SecureAnyCloud, and select Create.

On the Basics tab, pick your subscription, resource group, region and size. Under Administrator account, choose SSH public key and paste your key. Under Inbound port rules, allow SSH (22), HTTP (80) and HTTPS (443).

Review the dedicated data disk on the Disks tab, then select Review + create and Create.

Step 2 - Deploy from the Azure CLI

# Accept the Marketplace terms once per subscription (required before the first CLI deploy)
az vm image terms accept --urn sac1647283583153:wallabag-ubuntu-24-04:default:latest
az vm create \
  --resource-group <your-rg> \
  --name wallabag \
  --image sac1647283583153:wallabag-ubuntu-24-04:default:latest \
  --size Standard_D2s_v3 \
  --admin-username azureuser \
  --generate-ssh-keys \
  --public-ip-sku Standard

Open ports 80 and 443:

az vm open-port --resource-group <your-rg> --name wallabag --port 80,443

Step 3 - Confirm the services are running

SSH in as azureuser and confirm that nginx, PHP FPM, MariaDB and the first-boot service are all active. MariaDB listens only on 127.0.0.1:3306, while nginx serves wallabag on port 80.

systemctl is-active nginx php8.3-fpm mariadb wallabag-firstboot

ss -tlnp | grep -E ':80 |:3306 ' | sed 's/ */ /g'

Step 4 - Retrieve the per-VM administrator password

Each VM generates its own wallabag administrator password on first boot. The password, the login user and the application URL are written to a root-only credentials file. Read it with sudo:

sudo cat /root/wallabag-credentials.txt

Sign in to wallabag as user admin with the WALLABAG_ADMIN_PASSWORD from this file. On the VM itself, run sudo mariadb to reach the database directly over the local socket without a password.

Step 5 - Sign in

Browse to http://<vm-public-ip>/. The wallabag sign-in page opens.

Enter username admin and the password from Step 4. After you sign in, the Quickstart page walks you through configuring the application, saving your first article and migrating from an existing service.

Step 6 - Save your first article

Click the + button in the top bar, paste the address of any web page and press Enter. wallabag fetches the page and extracts the readable content. It files the article in your unread list with a preview image and an estimated reading time.

Step 7 - Read without distractions

Open any saved article to read it in wallabag's clean reading view: just the content, without advertising, popups or clutter.

From the reading sidebar you can tag the article, star it, annotate passages, mark it read, share it, or export it to EPUB or PDF for offline reading.

Step 8 - Pair the wallabagger browser extension

Install the official wallabagger extension for Firefox or Chrome to save pages with one click. The extension talks to your instance through the wallabag API.

In the web UI, open the profile menu and choose API clients management. Create a client, then copy the Client ID and Client secret. In the wallabagger settings, enter your wallabag URL, those two values, and your username and password. Every page you save then lands straight in your unread list.

Step 9 - Connect the Android or iOS app

The official wallabag apps for Android and iOS give you offline access to your reading list. In the app, choose to connect to your own wallabag instance and enter your instance URL. Supply the same API client credentials from Step 8, plus your username and password.

Articles sync both ways: save on the phone, read on the web, and the read status follows you.

Step 10 - Import your existing library

wallabag imports from Pocket, Instapaper, Readability, Firefox and Chrome bookmarks, and other wallabag instances. In the web UI, open the profile menu and choose Import. Pick your source and upload the export file from your old service.

Large imports run in the background, and your articles appear in the unread list as they are processed.

Step 11 - Create tagging rules

Tagging rules organise incoming articles automatically. Under Config then Tagging rules, define a rule such as readingTime >= 20 with the tag longread, or domainName = "github.com" with the tag code. Every newly saved article that matches is then tagged for you.

Step 12 - Confirm there are no known or default credentials

The stock wallabag installer seeds a default account named wallabag. The SecureAnyCloud image removes it before the image is captured, ships with an empty users table, and creates the per-VM administrator with a unique random secret on first boot. Public registration is disabled, so no known or blank credential authenticates.

You can prove this with the built-in round-trip check. It confirms that the per-VM administrator signs in through wallabag's own login form, while a blank password, common weak guesses and the removed default login are all rejected:

sudo mariadb --protocol=socket -uroot -N -e "SELECT CONCAT(username,' (per VM super admin)') FROM wallabag.wallabag_user"

sudo bash /usr/local/sbin/wallabag-cred-roundtrip.sh

Step 13 - Verify the stack and where your data lives

Confirm the wallabag version, the health endpoint and the dedicated data disk. The MariaDB database lives on the data disk mounted at /data (bind-mounted onto /var/lib/mysql). The images extracted from your saved articles live on the same disk. All of your reading data is therefore kept separate from the operating system disk and travels with the VM:

grep -m1 'version:' /var/www/wallabag/app/config/wallabag.yml | sed 's/^ *//'

curl -sI http://127.0.0.1/healthz | head -1

findmnt -no SOURCE,TARGET,FSTYPE,SIZE /data;
findmnt -no SOURCE,TARGET /var/lib/mysql

Add your own domain and TLS

The appliance serves plain HTTP on port 80. For production, point a DNS record at your VM and obtain a certificate with Let's Encrypt:

sudo apt-get install -y certbot python3-certbot-nginx
sudo certbot --nginx -d <your-domain>

Next, update the application URL so that links in exports and shared pages use your domain, and clear the cache:

sudo sed -i "s|^\(\s*domain_name:\s*\).*|\1'https://<your-domain>'|" /var/www/wallabag/app/config/parameters.yml
sudo -u www-data php /var/www/wallabag/bin/console cache:clear --env=prod

Two-factor authentication

wallabag supports two-factor authentication with a one-time password (OTP) app. Under Config then Security, enable two-factor authentication by OTP app, scan the QR code with your authenticator and confirm the code. From then on, signing in requires both the password and a fresh code.

Back up your data

Your reading data is the wallabag database plus the extracted article images. Dump the database and archive the images directory:

sudo mysqldump --protocol=socket -uroot wallabag > /tmp/wallabag-backup.sql

sudo tar czf /tmp/wallabag-images-backup.tar.gz -C /data/wallabag images

Copy both files off the VM on your usual schedule. To restore, load the SQL dump into the wallabag database and unpack the archive back to /data/wallabag/images.

Security notes

Encrypt web traffic. wallabag serves plain HTTP on port 80 out of the box. For anything beyond a trusted network, add your own domain and TLS as above, or front the VM with Azure Application Gateway.
Keep MariaDB private. The bundled MariaDB listens on 127.0.0.1 only and is never reachable from the network. Administer it through wallabag or over SSH.
Protect the administrator password. It is unique per VM, and no known or blank credential authenticates. Keep /root/wallabag-credentials.txt protected. To rotate the password, run:

sudo -u www-data php /var/www/wallabag/bin/console fos:user:change-password admin '<new-password>' --env=prod

Keep registration closed. Public registration is off by default in this image. Enable it only if you intend to run a shared instance.
Keep the VM patched. Apply operating system updates regularly with sudo apt update && sudo apt upgrade. Unattended security updates are enabled by default.
Restrict access. Limit inbound 80/tcp and 443/tcp in your NSG to the networks that need access.

Trademark

wallabag is an open-source project distributed under the MIT licence. This image is an independent packaging of the open-source wallabag software by SecureAnyCloud. It is not affiliated with, sponsored by, or endorsed by the wallabag project.

Support

This image is maintained by SecureAnyCloud with 24/7 support. For help deploying or operating wallabag on Azure, contact us at secureanycloud.com.

Deploy on Azure

Launch wallabag 2.6 on Ubuntu 24.04 LTS on Azure with 24/7 support from SecureAnyCloud.

View this image

Need Help?

Our support team is available 24/7.

sales@secureanycloud.com

Deploy on Azure

Overview

wallabag is an open-source, self-hosted read-it-later application built on the Symfony framework. It saves a clean, readable copy of any web article so you can read it later on any device, free of clutter and advertising. Your reading list stays private on infrastructure you control.

This SecureAnyCloud image runs wallabag behind nginx, with PHP FPM 8.3 and OPcache enabled. wallabag stores its data in SQLite, so the appliance is fully self-contained, with no separate database server to install, secure or back up.

What you get:

The SQLite database and saved-article uploads under /opt/wallabag/data, on a dedicated, independently resizable EBS volume, so you can grow your reading archive without touching the operating system disk
A wallabag administrator password and application secret generated on the first boot of every deployed instance, so two instances launched from the same Amazon Machine Image never share credentials
The initial administrator password written to /root/wallabag-credentials.txt with mode 0600, so only the root user can read it
Site-relative asset URLs, so the interface works on whatever public DNS name or IP address you reach the instance on
No instance metadata lookup and no value to edit on first boot, so deployments behind an Application Load Balancer, in a private subnet, or on a custom domain work without changes

Prerequisites

Before you deploy this image, make sure you have:

An Amazon Web Services account where you can launch EC2 instances
IAM permissions to launch instances, create security groups, and subscribe to AWS Marketplace products
An EC2 key pair in the target Region for SSH access to the instance
A VPC and subnet in the target Region, with a security group allowing inbound port 22 from your management network and inbound ports 80 and 443 from the networks your readers will use
The AWS CLI (version 2) installed locally, if you plan to deploy from the command line

Launch the instance from the AWS Marketplace

Sign in to the AWS Management Console, open the EC2 service, and select Launch instance. Under Application and OS Images, choose AWS Marketplace AMIs and search for wallabag. Select the SecureAnyCloud listing, choose Select, then choose Continue on the subscription summary.

Pick an instance type of m5.large or larger. Choose your EC2 key pair under Key pair (login). Under Network settings, select your VPC and subnet, then create or select a security group. It must allow inbound port 22 from your management network and inbound ports 80 and 443 from the networks your readers use. Leave the root and data volumes at their default sizes or larger.

Select Launch instance. First-boot initialisation takes approximately one minute after the instance state becomes Running and the status checks pass.

Launch the instance from the AWS CLI

Run the command below to launch an instance from the SecureAnyCloud wallabag Marketplace AMI into an existing subnet and security group. Replace the following values:

<ami-id> with the AMI ID shown on the Marketplace listing
<key-name> with your EC2 key pair name
<subnet-id> with your subnet ID
<security-group-id> with a security group that opens ports 22, 80, and 443 as described above

aws ec2 run-instances \
  --image-id <ami-id> \
  --instance-type m5.large \
  --key-name <key-name> \
  --subnet-id <subnet-id> \
  --security-group-ids <security-group-id> \
  --block-device-mappings '[{"DeviceName":"/dev/sda1","Ebs":{"VolumeSize":12,"VolumeType":"gp3"}}]' \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=wallabag-01}]'

On success, the command prints a JSON document. Note the instance ID. Once the instance is running, retrieve its public address with aws ec2 describe-instances --instance-ids <instance-id> --query "Reservations[].Instances[].PublicIpAddress" --output text.

Connect and retrieve the initial credentials

Connect over SSH with the key pair you selected and the public IP address from Step 2. The SSH login user depends on the operating system of the AMI variant you launched:

AMI variant SSH login user

wallabag 2.6 on Ubuntu 24.04 ubuntu

For the Ubuntu 24.04 variant, connect with ssh -i <path-to-key.pem> ubuntu@<instance-public-ip>.

The administrator credentials generated on first boot are stored in a root-only file. This command prints the wallabag administrator user name and password for this specific instance:

sudo cat /root/wallabag-credentials.txt

The file lists the administrator user name (wallabag) and the generated password. Store the password in your password manager, and treat the file as sensitive.

Verify the wallabag service

The web stack is two systemd services: nginx and PHP FPM. Confirm that both are active:

systemctl is-active nginx php8.3-fpm

Both lines should read active. Confirm that nginx is listening on port 80:

ss -tlnp 2>/dev/null | grep ':80 ' || sudo ss -tlnp | grep ':80 '

Confirm that the dedicated data volume holding the SQLite database and uploads is mounted:

df -h /opt/wallabag | tail -1

Confirm that the wallabag sign-in page is served locally:

curl -s -o /dev/null -w 'wallabag login HTTP %{http_code}\n' http://127.0.0.1/login

An HTTP 200 response confirms the application is up.

Sign in through the web interface

Open a web browser and browse to http://<instance-public-ip>/. You are redirected to the wallabag sign-in page.

Save and read articles

After you sign in, your reading list opens. Click the + button in the top bar and paste the article's URL. wallabag fetches the page, extracts the readable content, and adds it to your Unread list. You can star, archive, tag and export articles.

Open any article to read it in the clean, distraction-free reading view. The reading view strips navigation, advertising and clutter and presents just the article text. Controls let you star, archive, tag and annotate the article and adjust the display.

Connect browser extensions and mobile apps

wallabag provides official browser extensions and mobile apps that save articles to your instance over the wallabag REST API. In the web interface, open the account menu, go to API clients management and create a client. Then enter your instance URL and the generated client credentials in the extension or app.

Because this is your own self-hosted instance, your reading list and saved content never leave infrastructure you control.

Configure outbound email (optional)

This image disables outbound email out of the box, so no mail server is required for normal reading and saving. If you want wallabag to send mail, for example for password resets when you add more users, edit the mailer setting in /opt/wallabag/app/config/parameters.yml. Set mailer_dsn to your SMTP server, for example smtp://user:pass@smtp.example.com:587. Then clear the cache and restart PHP FPM:

sudo -u www-data env HOME=/tmp /opt/wallabag/bin/console cache:clear --env=prod sudo systemctl restart php8.3-fpm

Enable HTTPS with Let's Encrypt (optional)

To serve wallabag over HTTPS, point a DNS name at the instance's public IP address and make sure inbound ports 80 and 443 are open. Then install Certbot and obtain a certificate. Replace your-domain.example.com with your DNS name and run the following on the instance:

sudo apt-get update && sudo apt-get install -y certbot python3-certbot-nginx

Next, request and install the certificate with sudo certbot --nginx. Follow the interactive prompts to enter your domain and email address. Certbot updates the nginx site configuration to serve HTTPS and sets up automatic renewal.

Back up and maintain

All of your wallabag data, the SQLite database and the saved-article uploads, lives under /opt/wallabag/data on the dedicated data volume. Back it up by taking an EBS snapshot of that volume, or by copying the database file. To copy the database while the service is running:

sudo cp /opt/wallabag/data/db/wallabag.sqlite /tmp/wallabag-backup.sqlite

Keep the operating system patched with sudo apt-get update && sudo apt-get -y upgrade. To upgrade wallabag itself, follow the upstream upgrade documentation at the wallabag project site. Because the database is on its own volume, application upgrades do not put your reading archive at risk.

Support

This image is published and supported by SecureAnyCloud. Technical support is available 24/7 by email and chat. It covers wallabag deployment, upgrades, performance tuning, import and export, and storage administration.

All product and company names are trademarks or registered trademarks of their respective holders.

Deploy on AWS

Launch wallabag on AWS with 24/7 support from SecureAnyCloud.

View on Marketplace

Need Help?

Our support team is available 24/7.

sales@secureanycloud.com

Deploy on AWS