wallabag on Ubuntu 24.04 on Azure User Guide

Overview

wallabag is the 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. Tag and annotate your 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. The cloudimg image ships wallabag 2.6 served by nginx and PHP 8.3 FPM on a hardened, fully patched Ubuntu 24.04 LTS base, together with a bundled local MariaDB server so the appliance is complete and useful on its own. The bundled MariaDB listens only on the loopback interface (127.0.0.1:3306) and keeps its data on a dedicated Azure data disk. A unique administrator password is generated on the first boot of every VM. Backed by 24/7 cloudimg support.

What is included:

• 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 first boot 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, 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 cloudimg support

Prerequisites

An active Azure subscription, an SSH key pair, and a VNet plus 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. NSG inbound: allow 22/tcp from your management network, 80/tcp for the application and 443/tcp if you terminate TLS on the VM. The bundled MariaDB is never exposed: it 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 cloudimg, and select Create. On Basics 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 Review + create then Create.

Step 2 - Deploy from the Azure CLI

az vm create \
  --resource-group <your-rg> \
  --name wallabag \
  --image <marketplace-image-urn> \
  --size Standard_D2s_v3 \
  --admin-username azureuser \
  --generate-ssh-keys \
  --public-ip-sku Standard

Then 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 nginx, PHP FPM, MariaDB and the first boot service are all active. Note that 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

Every VM generates its own wallabag administrator password on first boot and writes it, along with the login user and the application URL, to a root only credentials file. Read it with sudo:

sudo cat /root/wallabag-credentials.txt

You sign in to wallabag as user admin with the WALLABAG_ADMIN_PASSWORD from this file. On the box itself you can also 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>/. You land on the wallabag sign in page. Enter username admin and the password from Step 4.

After signing in you land on the Quickstart page, which 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, extracts the readable content and files it in your unread list, complete with a preview image and an estimated reading time.

Step 7 - Read distraction free

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, choose API clients management, create a client and copy the Client ID and Client secret. In the wallabagger settings enter your wallabag URL plus those values together with your username and password, and every page you save lands straight in your unread list.

Step 9 - Connect the Android or iOS app

The official wallabag apps for Android and iOS give you your reading list offline. In the app choose to connect to your own wallabag instance, enter your instance URL, and supply the same API client credentials from Step 8 with 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, 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, and every newly saved article that matches is tagged for you.

Step 12 - No known or default credentials

The stock wallabag installer seeds a default account named wallabag. The cloudimg 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, which confirms 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:

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), and the images extracted from your saved articles live on the same disk, so all of your reading data is kept separate from the operating system disk and rides 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

Adding 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>

Then update the application URL so 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 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.

Backing up

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

• 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.
• The bundled MariaDB listens on 127.0.0.1 only and is never reachable from the network. Administer it through wallabag or over SSH.
• The administrator password is unique per VM and no known or blank credential authenticates. Keep /root/wallabag-credentials.txt protected. To rotate the password:

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

• Keep public registration disabled unless you intend to run a shared instance; it is off by default in this image.
• Apply operating system updates regularly with sudo apt update && sudo apt upgrade; unattended security updates are enabled by default.
• Restrict 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 cloudimg and is not affiliated with, sponsored by, or endorsed by the wallabag project.

Support

This image is maintained by cloudimg with 24/7 support. If you need help deploying or operating wallabag on Azure, contact us at cloudimg.co.uk.