How to Install Wallabag on Ubuntu 22.04

Wallabag is a read-it-later kind of service. It allows you to save webpages to read later at your leisure pace. There are lots of services that allow you to do it like Pocket, Instapaper, etc but having a service installed on a server you own is much better. For one, it won't go out of business and take the links down with it.

This tutorial will cover installing and setting up Wallabag on a server running Ubuntu 22.04. It will also cover how to set up Nginx, MySQL, Composer, and PHP which are all required by Wallabag to run.


  • A server running Ubuntu 22.04.

  • A non-root user with sudo privileges.

  • A fully qualified domain name (FQDN) like

  • Make sure everything is updated.

    $ sudo apt update
    $ sudo apt upgrade
  • Few packages that your system needs.

    $ sudo apt install wget curl nano software-properties-common dirmngr apt-transport-https gnupg2 ca-certificates lsb-release ubuntu-keyring unzip -y

    Some of these packages may already be installed on your system.

Step 1 - Configure Firewall

The first step is to configure the firewall. Ubuntu comes with ufw (Uncomplicated Firewall) by default.

Check if the firewall is running.

$ sudo ufw status

You should get the following output.

Status: inactive

Allow SSH port so the firewall doesn't break the current connection on enabling it.

$ sudo ufw allow OpenSSH

Allow HTTP and HTTPS ports as well.

$ sudo ufw allow http
$ sudo ufw allow https

Enable the Firewall

$ sudo ufw enable
Command may disrupt existing ssh connections. Proceed with operation (y|n)? y
Firewall is active and enabled on system startup

Check the status of the firewall again.

$ sudo ufw status

You should see a similar output.

Status: active

To                         Action      From
--                         ------      ----
OpenSSH                    ALLOW       Anywhere
80/tcp                     ALLOW       Anywhere
443                        ALLOW       Anywhere
OpenSSH (v6)               ALLOW       Anywhere (v6)
80/tcp (v6)                ALLOW       Anywhere (v6)
443 (v6)                   ALLOW       Anywhere (v6)

Step 2 - Install PHP and its extensions

Ubuntu 22.04 ships with PHP 8.1.2 version which is a bit outdated. We will install the latest PHP 8.1 version using Ondrej's PHP repository.

$ sudo add-apt-repository ppa:ondrej/php

Next, install PHP and its extensions required by Wallabag.

$ sudo apt install php8.1-fpm php8.1-mysql php8.1-bcmath php8.1-xml php8.1-zip php8.1-curl php8.1-mbstring php8.1-gd php8.1-tidy php8.1-intl php8.1-cli 

Verify the installation.

$ php --version
PHP 8.1.16 (cli) (built: Feb 14 2023 18:35:37) (NTS)
Copyright (c) The PHP Group
Zend Engine v4.1.16, Copyright (c) Zend Technologies
    with Zend OPcache v8.1.16, Copyright (c), by Zend Technologies

Step 3 - Install Composer

Composer is a dependency management tool for PHP and is required for Wallabag installation.

Run the following commands to download the Composer binary. Wallabag only works with Composer 2.2 LTS so we have modified the command accordingly.

$ php -r "copy('', 'composer-setup.php');"
$ php composer-setup.php --2.2
$ php -r "unlink('composer-setup.php');"

Install Composer by moving the binary to the /usr/local/bin directory.

$ sudo mv composer.phar /usr/local/bin/composer

Verify the installation by checking its version.

$ composer --version
Composer version 2.2.21 2023-02-15 13:07:40

Step 4 - Install MySQL

Ubuntu 22.04 ships with the latest version of MySQL. You can install it with a single command.

$ sudo apt install mysql-server

Check the version of MySQL.

$ mysql --version
mysql  Ver 8.0.32-0ubuntu0.22.04.2 for Linux on x86_64 ((Ubuntu))

This step is necessary for MySQL versions 8.0.28 and above. Enter the MySQL Shell.

$ sudo mysql

Run the following command to set the password for your root user. Make sure it has a mix of numbers, uppercase, lowercase, and special characters.

mysql> ALTER USER 'root'@'localhost' IDENTIFIED WITH mysql_native_password BY 'YourPassword12!';

Exit the shell.

mysql> exit

Run the MySQL secure install script.

$ sudo mysql_secure_installation

First, you will be asked for your root password. Enter it. Next, you will be asked to install the Validate Password Component. It checks the strength of passwords used in MySQL. Press Y to install it. Next, you will be asked to set the level of the password validation policy. Choose 2 as it is the strongest one.

Securing the MySQL server deployment.

Enter password for user root:

VALIDATE PASSWORD COMPONENT can be used to test passwords
and improve security. It checks the strength of password
and allows the users to set only those passwords which are
secure enough. Would you like to setup VALIDATE PASSWORD component?

Press y|Y for Yes, any other key for No: Y

There are three levels of password validation policy:

LOW    Length >= 8
MEDIUM Length >= 8, numeric, mixed case, and special characters
STRONG Length >= 8, numeric, mixed case, special characters and dictionary                  file

Please enter 0 = LOW, 1 = MEDIUM and 2 = STRONG: 2
Using existing password for root.

Estimated strength of the password: 100

Next, enter N to refuse to change your root password. Also, enter Y to remove anonymous users, disallow remote root logins, remove the test database, and reload the privilege tables.

Change the password for root ? ((Press y|Y for Yes, any other key for No) : N

 ... skipping.
By default, a MySQL installation has an anonymous user,
allowing anyone to log into MySQL without having to have
a user account created for them. This is intended only for
testing, and to make the installation go a bit smoother.
You should remove them before moving into a production

Remove anonymous users? (Press y|Y for Yes, any other key for No) : Y

Normally, root should only be allowed to connect from
'localhost'. This ensures that someone cannot guess at
the root password from the network.

Disallow root login remotely? (Press y|Y for Yes, any other key for No) : Y

By default, MySQL comes with a database named 'test' that
anyone can access. This is also intended only for testing,
and should be removed before moving into a production

Remove test database and access to it? (Press y|Y for Yes, any other key for No) : Y
 - Dropping test database...

 - Removing privileges on test database...

Reloading the privilege tables will ensure that all changes
made so far will take effect immediately.

Reload privilege tables now? (Press y|Y for Yes, any other key for No) : Y

All done!

Step 5 - Configure MySQL

Log in to the MySQL shell. Enter your root password when prompted.

$ sudo mysql -u root -p

Create a sample database.

mysql> CREATE DATABASE wallabag;

Create an SQL user account.

mysql> CREATE USER 'wallabaguser'@'localhost' IDENTIFIED BY 'Your_password2';

Grant all privileges on the database to the user.

mysql> GRANT ALL PRIVILEGES ON wallabag.* TO 'wallabaguser'@'localhost';

Flush user privileges.


Exit the shell.

mysql> exit

Step 6 - Install Nginx

Ubuntu 22.04 ships with an older version of Nginx. You need to download the official Nginx repository to install the latest version.

Import Nginx's signing key.

$ curl | gpg --dearmor \
| sudo tee /usr/share/keyrings/nginx-archive-keyring.gpg >/dev/null

Add the repository for Nginx's stable version.

$ echo "deb [signed-by=/usr/share/keyrings/nginx-archive-keyring.gpg arch=amd64] \ `lsb_release -cs` nginx" \
| sudo tee /etc/apt/sources.list.d/nginx.list

Update the system repositories.

$ sudo apt update

Install Nginx.

$ sudo apt install nginx

Verify the installation.

$ nginx -v
nginx version: nginx/1.22.1

Start the Nginx server.

$ sudo systemctl start nginx

Step 7 - Install SSL

We need to install Certbot to generate the SSL certificate. You can either install Certbot using Ubuntu's repository or grab the latest version using the Snapd tool. We will be using the Snapd version.

Ubuntu 22.04 comes with Snapd installed by default. Run the following commands to ensure that your version of Snapd is up to date.

$ sudo snap install core && sudo snap refresh core

Install Certbot.

$ sudo snap install --classic certbot

Use the following command to ensure that the Certbot command can be run by creating a symbolic link to the /usr/bin directory.

$ sudo ln -s /snap/bin/certbot /usr/bin/certbot

Run the following command to generate an SSL Certificate.

$ sudo certbot certonly --nginx --agree-tos --no-eff-email --staple-ocsp --preferred-challenges http -m [email protected] -d

The above command will download a certificate to the /etc/letsencrypt/live/ directory on your server.

Generate a Diffie-Hellman group certificate.

$ sudo openssl dhparam -dsaparam -out /etc/ssl/certs/dhparam.pem 4096

Check the Certbot renewal scheduler service.

$ sudo systemctl list-timers

You will find snap.certbot.renew.service as one of the services scheduled to run.

NEXT                        LEFT          LAST                        PASSED        UNIT                      ACTIVATES
Sun 2023-02-26 06:32:00 UTC 9h left       Sat 2023-02-25 18:04:05 UTC 2h 59min ago  snap.certbot.renew.timer  snap.certbot.renew.service
Sun 2023-02-26 06:43:20 UTC 9h left       Sat 2023-02-25 10:49:23 UTC 10h ago       apt-daily-upgrade.timer   apt-daily-upgrade.service
Sun 2023-02-26 09:00:06 UTC 11h left      Sat 2023-02-25 20:58:06 UTC 5min ago      apt-daily.timer           apt-daily.service

Do a dry run of the process to check whether the SSL renewal is working fine.

$ sudo certbot renew --dry-run

If you see no errors, you are all set. Your certificate will renew automatically.

Step 8 - Install Wallabag

Create the /var/www/wallabag/html directory.

$ sudo mkdir /var/www/html/wallabag -p

Download the latest version of Wallabag.

$ wget

Extract the archive.

$ tar xzf latest-v2-package

Move the files from the extracted directory to the directory created earlier. You can check the latest version of the Wallabag from the GitHub releases page. The latest version at the time of writing this tutorial is 2.5.4.

$ sudo mv wallabag-2.5.4/* /var/www/html/wallabag

Create the asset directory.

$ sudo mkdir /var/www/html/wallabag/data/assets

Change the permissions of the /var/www/html/wallabag directory to the currently logged-in user.

$ sudo chown -R $USER:$USER /var/www/html/wallabag

Switch to the directory.

$ cd /var/www/html/wallabag

Create the parameters.yml file by copying the example file.

$ cp app/config/parameters.yml.dist app/config/parameters.yml

Before we start configuring Wallabag, generate a secret key. Note down the key to be used later.

$ openssl rand -base64 32

Open the parameters file for editing.

$ nano app/config/parameters.yml

Find the following section and fill in the database credentials. The database port is 3306 for MySQL.

    database_driver: pdo_mysql
    database_port: 3306
    database_name: wallabag
    database_user: wallabaguser
    database_password: Your_password2

Fill in the server description and domain name.

    server_name: "Howtoforge Wallabag"

Fill in your SMTP details. In our case, we are using Amazon SES service.

    mailer_transport:  smtp
    mailer_user:       YOUR_AES_USERNAME
    mailer_password:   YOUR_AES_PASSWORD
    mailer_port:       587
    mailer_encryption: tls

Fill in the secret key generated before. If you want to keep two-factor authentication, then make sure the following settings are applied. If you want to turn off user registration, set the value of fouser_registration to false. The fouser_confirmation variable is set to true which means every user registration will need to be confirmed via email. Change the value of the from_email variable to the email id of your choice.

    # A secret key that's used to generate certain security-related tokens
    secret: QLV/GpZwDobQbyQZQ15FkM1Hvt+ZFJZXw8GW9F4KR3o=

    # two factor stuff
    twofactor_auth: true
    twofactor_sender: [email protected]

    # fosuser stuff
    fosuser_registration: true
    fosuser_confirmation: true
    from_email: [email protected]

There are more sentries related to Redis, RabbitMQ, and Sentry settings. You can configure them as per your needs after installing the said packages.

Save the file by pressing Ctrl + X and entering Y when prompted.

Use Composer to download and install the dependencies required by Wallabag.

$ SYMFONY_ENV=prod composer install --no-dev -o --prefer-dist

Finish the installation using Wallabag command-line tool.

$ php bin/console wallabag:install --env=prod

You will be prompted if you want to reset the database and its schema. Enter no as the response both times. Next, you will be asked if you want to create an administrator account. Type yes to proceed and enter the username, password, and email id for the account.

wallabag installer

Step 1 of 4: Checking system requirements.

 ------------------------ -------- ---------------- 
  Checked                  Status   Recommendation  
 ------------------------ -------- ---------------- 
  PDO Driver (pdo_mysql)   OK!                      
  Database connection      OK!                      
  Database version         OK!                      
  curl_exec                OK!                      
  curl_multi_init          OK!                      
 ------------------------ -------- ---------------- 

 [OK] Success! Your system can run wallabag properly.                                                                   

Step 2 of 4: Setting up database.

 It appears that your database already exists. Would you like to reset it? (yes/no) [no]:
 > no

 Seems like your database contains schema. Do you want to reset it? (yes/no) [no]:
 > no

 Clearing the cache...

 Database successfully setup.

Step 3 of 4: Administration setup.

 Would you like to create a new admin user (recommended)? (yes/no) [yes]:
 > yes

 Username [wallabag]:
 > navjot

 Password [wallabag]:

 Email [[email protected]]:
 > [email protected]

 Administration successfully setup.

Step 4 of 4: Config setup.

 Config successfully setup.
 [OK] wallabag has been successfully installed.                                                                         
 [OK] You can now configure your web server, see

Switch back the directory permission to Nginx.

$ sudo chown -R nginx:nginx /var/www/html/wallabag

Step 9 - Configure Nginx and PHP

Configure PHP-FPM

Open the file /etc/php/8.1/fpm/pool.d/www.conf.

$ sudo nano /etc/php/8.1/fpm/pool.d/www.conf

We need to set the Unix user/group of PHP processes to nginx. Find the user=www-data and group=www-data lines in the file and change them to nginx.

; Unix user/group of processes
; Note: The user is mandatory. If the group is not set, the default user's group
;       will be used.
; RPM: apache user chosen to provide access to the same directories as httpd
user = nginx
; RPM: Keep a group allowed to write in log dir.
group = nginx

Find the listen.owner = www-data and = www-data lines in the file and change them to nginx.

; Set permissions for unix socket, if one is used. In Linux, read/write
; permissions must be set in order to allow connections from a web server. Many
; BSD-derived systems allow connections regardless of permissions. The owner
; and group can be specified either by name or by their numeric IDs.
; Default Values: user and group are set as the running user
;                 mode is set to 0660
listen.owner = nginx = nginx

Save the file by pressing Ctrl + X and entering Y when prompted.

Increase the execution time for PHP-FPM and PHP-CLI to 60 seconds.

$ sudo sed -i 's/max_execution_time = 30/max_execution_time = 60/' /etc/php/8.1/fpm/php.ini
$ sudo sed -i 's/max_execution_time = 30/max_execution_time = 60/' /etc/php/8.1/cli/php.ini

Increase the memory limit for PHP-FPM from 128MB to 256MB.

$ sudo sed -i 's/memory_limit = 128M/memory_limit = 256M/' /etc/php/8.1/fpm/php.ini

Restart the PHP-FPM service.

$ sudo systemctl restart php8.1-fpm

Change the group of the PHP sessions directory to Nginx.

$ sudo chgrp -R nginx /var/lib/php/sessions

Configure Nginx

Create and open the file /etc/nginx/conf.d/wallabag.conf for editing.

$ sudo nano /etc/nginx/conf.d/wallabag.conf

Paste the following code in it.

server {
    listen       443 ssl http2;
    listen       [::]:443 ssl http2;

    access_log  /var/log/nginx/wallabag.access.log;
    error_log   /var/log/nginx/wallabag.error.log;

	# SSL
    ssl_certificate      /etc/letsencrypt/live/;
    ssl_certificate_key  /etc/letsencrypt/live/;
    ssl_trusted_certificate /etc/letsencrypt/live/;
    ssl_session_timeout  5m;
    ssl_session_cache shared:MozSSL:10m;
    ssl_session_tickets off;
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_prefer_server_ciphers on;
    ssl_ecdh_curve X25519:prime256v1:secp384r1:secp521r1;
    ssl_stapling on;
    ssl_stapling_verify on;
    ssl_dhparam /etc/ssl/certs/dhparam.pem;

    root /var/www/html/wallabag/web;

    location / {
        try_files $uri /app.php$is_args$args;

    # Pass PHP Scripts To FastCGI Server
    location ~ ^/app\.php(/|$) {
        fastcgi_split_path_info ^(.+\.php)(/.*)$;
        fastcgi_pass unix:/run/php/php8.1-fpm.sock; # Depends On The PHP Version
        fastcgi_param SCRIPT_FILENAME  $realpath_root$fastcgi_script_name;
        fastcgi_param DOCUMENT_ROOT $realpath_root;
        include fastcgi_params;

    location ~ \.php$ {
        return 404;

# enforce HTTPS
server {
    listen       80;
    listen       [::]:80;
    return 301   https://$host$request_uri;

Notice the root directory to be used in the Nginx configuration is /var/www/html/wallabag/public/.

Save the file by pressing Ctrl + X and entering Y when prompted once finished.

Open the file /etc/nginx/nginx.conf for editing.

$ sudo nano /etc/nginx/nginx.conf

Add the following line before the line include /etc/nginx/conf.d/*.conf;.

server_names_hash_bucket_size  64;

Save the file by pressing Ctrl + X and entering Y when prompted.

Verify the Nginx configuration file syntax.

$ sudo nginx -t
nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

Restart the Nginx service.

$ sudo systemctl restart nginx

Step 10 - Access Wallabag

Open the URL in your browser and you will get the following login screen.

Wallabag Login Screen

Enter your credentials created during installation and press the LOG IN button to proceed. You will be greeted with the Wallabag dashboard.

Wallabag Dashboard

Wallabag provides you with a multitude of apps for every browser, mobile, or Ebook reader using which you can add links. And if nothing else fancies you, you can even use a Bookmarklet, the details of which you can access from the How to section by clicking the user icon on the top right of the dashboard.

Wallabag User dropdown menu

You will be given links to the browser extensions, mobile apps, and the Wallabag bookmarklet.

Wallabag Howto Page

That's it. You can start using Wallabag to save articles for reading later.


This concludes our tutorial on installing Wallabag on a Ubuntu 22.04 server. If you have any questions, post them in the comments below.

Share this page:

Suggested articles

1 Comment(s)

Add comment


By: Wallace at: 2023-03-06 19:27:06

I love wallabag for many reasons.  Can't imagine getting along without it.  Love that I can download articles for full offline reading on a tablet when stuck in waiting rooms without any internet.  Literally migrated from an older release to 2.5.4 last week.

Wallabag happily runs with sqlite instead of a heavy DBMS.  For a household, SQLite would be fine.

Wallabag happily runs inside a linux container, so that stack dependencies don't cause conflicts with other systems. If you use LXD as the containiner manager for LXC, then creating complete backups (full tgz images) is a single command.

    `sudo snap save lxd`

will create a tgz file with all lxd managed containers at  /var/lib/snapd/snapshots/ .  `snap saved` will show the list of saved snapshots. These aren't versioned backups, but if weekly or monthly "snap save" commands are used and daily versioned backups taken inside the LXC container, a workable disaster recovery plan is possible.

A system isn't up and ready to be used until there is a backup taken.  As far as complete backups for wallabag data, just 2 files seem to be required./var/www/wallabag/html/data/db/data.sqlite3/var/www/wallabag/html/app/config/parameters.ymlThe sqlite3 DB file being located under the WB html directory is a security issue, so admins probably want to move that to /var/www/wallabag/data.sqlite3 and update the location in the parameters.yml file.

Wallabag happily can be accessed using a reverse proxy that does the SSL termination for it and other self-hosted websites. Pulling the SSL management away from lots of self-hosted webapps makes TLS certificate management easier and it makes for any VPN access to your self-hosted webapps less dynamic, since the reverse-proxy wouldn't change very often, while providing the ability to block unwanted requests in a more centralized way.