How To Install Wallabag on Debian 12

In this tutorial, we will show you how to install Wallabag on Debian 12. Tired of losing track of interesting articles online? Need a reliable way to save web content for later reading? Wallabag provides an excellent self-hosted solution that gives you full control over your read-it-later content. This comprehensive guide will walk you through installing Wallabag on Debian 12, from initial setup to final configuration and maintenance.

What is Wallabag?

Wallabag is an open-source, self-hosted application that allows you to save web pages for later reading. Unlike proprietary services such as Pocket or Instapaper, Wallabag gives you complete ownership of your data and reading list. When you save an article with Wallabag, the content is stored on your own server, ensuring you can access it even if the original website goes offline.

Key features of Wallabag include:

• Clean reading experience without ads or distractions
• Cross-platform availability (web, mobile, browser extensions)
• Content tagging and organization capabilities
• Full-text search functionality
• Offline reading support
• Article sharing options
• API for integrations with other services
• Import capabilities from other read-it-later services

Wallabag extracts the core content from web pages, preserving images and formatting while eliminating distracting elements. This results in a clean, focused reading experience across any device.

Prerequisites for Installing Wallabag

Before beginning the installation process, ensure you have the following prerequisites in place:

• A server running Debian 12 with at least 1GB RAM and 10GB storage
• Root access or a user with sudo privileges
• A registered domain name (if you want to access Wallabag remotely)
• Basic command-line knowledge
• SSH access to your server
• Properly configured firewall with ports 80 and 443 open

It’s recommended to start with a fresh Debian 12 installation to prevent potential conflicts with existing configurations.

Preparing Your Debian 12 System

Update System Packages

The first step is to update your system packages to ensure you have the latest versions and security patches:

sudo apt update && sudo apt upgrade

Install Essential Utilities

Install necessary utility packages that will be required throughout the installation process:

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

Set Up a Non-Root User with Sudo Privileges

If you’re logging in as root, it’s good practice to create a dedicated user for administration:

adduser username
usermod -aG sudo username

Replace “username” with your preferred username.

Installing Required Dependencies

Wallabag requires several components to function properly, including a web server, PHP with specific extensions, and a database. Let’s install these dependencies one by one.

PHP Installation

Wallabag requires PHP 8.1 or higher with several extensions. Install PHP and the required extensions with:

sudo apt install php-fpm php-mysql php-bcmath php-xml php-zip php-curl php-mbstring php-gd php-tidy php-tokenizer php-cli php-dom php-json

Verify the PHP installation by checking the version:

php -v

Choosing and Installing a Web Server

You can use either Apache or Nginx as your web server. This guide will cover both options.

Option 1: Apache Installation

sudo apt install apache2 libapache2-mod-php

Enable necessary Apache modules:

sudo a2enmod rewrite
sudo a2enmod ssl
sudo systemctl restart apache2

Option 2: Nginx Installation

sudo apt install nginx

After installing Nginx, you’ll need to configure PHP-FPM to work with it:

sudo apt install php-fpm
sudo systemctl enable php-fpm
sudo systemctl start php-fpm

Installing Composer

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

php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
php composer-setup.php --2.2
php -r "unlink('composer-setup.php');"
sudo mv composer.phar /usr/local/bin/composer

Verify the installation:

composer --version

Note that Wallabag works best with Composer 2.2 LTS, which is why we specified that version during installation.

Database Setup

Wallabag supports multiple database systems. You can choose between MySQL/MariaDB and SQLite depending on your needs.

Option 1: MySQL/MariaDB Installation

sudo apt install mysql-server

Secure the MySQL installation:

sudo mysql_secure_installation

Create a database and user for Wallabag:

sudo mysql -u root -p

At the MySQL prompt, execute:

CREATE DATABASE wallabag;
CREATE USER 'wallabag'@'localhost' IDENTIFIED BY 'your_secure_password';
GRANT ALL PRIVILEGES ON wallabag.* TO 'wallabag'@'localhost';
FLUSH PRIVILEGES;
EXIT;

Option 2: SQLite Configuration

If you prefer SQLite, which is simpler to set up but less suitable for high-traffic installations:

sudo apt install sqlite3 php-sqlite3

SQLite doesn’t require user creation or specific configuration, as it stores data in a file that Wallabag will manage.

Web Server Configuration

Apache Configuration

If you chose Apache, create a virtual host configuration file:

sudo nano /etc/apache2/sites-available/wallabag.conf

Add the following content, replacing “wallabag.example.com” with your domain:

<VirtualHost *:80>
    ServerAdmin admin@example.com
    ServerName wallabag.example.com
    DocumentRoot /var/www/html/wallabag/web

    <Directory /var/www/html/wallabag/web>
        AllowOverride All
        Require all granted
    </Directory>

    ErrorLog ${APACHE_LOG_DIR}/wallabag_error.log
    CustomLog ${APACHE_LOG_DIR}/wallabag_access.log combined

    RewriteEngine on
    RewriteCond %{SERVER_NAME} =wallabag.example.com
    RewriteRule ^ https://%{SERVER_NAME}%{REQUEST_URI} [END,NE,R=permanent]
</VirtualHost>

Enable the site and disable the default site:

sudo a2dissite 000-default.conf
sudo a2ensite wallabag.conf
sudo systemctl restart apache2

Nginx Configuration

If you chose Nginx, create a server block configuration:

sudo mkdir -p /var/www/wallabag.example.com/{public_html,logs}
sudo nano /etc/nginx/sites-available/wallabag

Add the following content, replacing “wallabag.example.com” with your domain:

server {
    server_name wallabag.example.com;
    root /var/www/html/wallabag/web;

    access_log /var/log/nginx/wallabag_access.log;
    error_log /var/log/nginx/wallabag_error.log;

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

    location ~ ^/app\.php(/|$) {
        fastcgi_pass unix:/run/php/php8.2-fpm.sock;
        fastcgi_split_path_info ^(.+\.php)(/.*)$;
        include fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
        fastcgi_param DOCUMENT_ROOT $realpath_root;
        internal;
    }
}

Enable the site:

sudo ln -s /etc/nginx/sites-available/wallabag /etc/nginx/sites-enabled/
sudo systemctl restart nginx

SSL/TLS Certificate Setup

Secure your Wallabag installation with HTTPS by obtaining a free SSL certificate from Let’s Encrypt:

Installing Certbot

sudo apt install certbot

For Apache:

sudo apt install python3-certbot-apache
sudo certbot --apache -d wallabag.example.com

For Nginx:

sudo apt install python3-certbot-nginx
sudo certbot --nginx -d wallabag.example.com

Follow the prompts to complete the SSL configuration process. Certbot will automatically configure your web server to use HTTPS and set up certificate auto-renewal.

Downloading and Installing Wallabag

There are two methods to obtain Wallabag: direct download or Git repository cloning.

Method 1: Direct Download

sudo mkdir -p /var/www/html/wallabag
cd /var/www/html
sudo wget https://wllbg.org/latest-v2-package -O wallabag.zip
sudo unzip wallabag.zip -d /var/www/html/
sudo mv wallabag-*/* /var/www/html/wallabag/
sudo mkdir -p /var/www/html/wallabag/data/assets

Method 2: Git Repository Cloning

sudo git clone https://github.com/wallabag/wallabag.git /var/www/html/wallabag

Setting Proper Permissions

Change the ownership of the Wallabag directory to the web server user:

sudo chown -R www-data:www-data /var/www/html/wallabag

For development or easier management, you might want to set your current user as the owner:

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

Configuring Wallabag

Creating the Parameters File

Create the configuration file by copying the template:

cd /var/www/html/wallabag
cp app/config/parameters.yml.dist app/config/parameters.yml
nano app/config/parameters.yml

Generating a Secret Key

Generate a secure secret key:

openssl rand -base64 32

Configuring Parameters

Edit the parameters.yml file with your specific configuration. Here’s a sample configuration for SQLite:

parameters:
    database_driver: pdo_sqlite
    database_host: 127.0.0.1
    database_port: ~
    database_name: wallabag
    database_user: ~
    database_password: ~
    database_path: '%kernel.project_dir%/data/db/wallabag.sqlite'
    database_table_prefix: wallabag_
    database_socket: ~
    database_charset: utf8mb4

    mailer_transport: smtp
    mailer_host: 127.0.0.1
    mailer_user: ~
    mailer_password: ~
    
    locale: en
    secret: YOUR_GENERATED_SECRET
    
    # Domain name used in emails sent by Wallabag
    domain_name: 'https://wallabag.example.com'
    
    # Two-factor authentication
    twofactor_auth: false
    twofactor_sender: no-reply@wallabag.org
    
    # User registration settings
    fosuser_registration: true
    fosuser_confirmation: true
    
    # RSS settings
    rss_limit: 50
    
    # Optional Redis configuration
    redis_scheme: tcp
    redis_host: localhost
    redis_port: 6379
    redis_path: ~
    redis_password: ~

Replace ‘YOUR_GENERATED_SECRET’ with the secret key you generated earlier, and adjust other parameters as needed.

Running the Installation Process

Now that you’ve configured Wallabag, you can run the installation process:

Using Make (Recommended)

If you have Make installed:

cd /var/www/html/wallabag
sudo -u www-data make install

The installer will check your system requirements, set up the database, and guide you through creating an admin user.

Alternative Installation Method

If you don’t have Make installed, you can run these commands:

cd /var/www/html/wallabag
sudo -u www-data composer install --no-dev -o
sudo -u www-data php bin/console wallabag:install

During the installation process, you’ll be prompted to:
1. Confirm your database configuration
2. Reset the database if it already exists
3. Create an admin user (username, password, and email)

Post-Installation Configuration

Setting Up Cron Jobs for Background Tasks

For optimal performance, set up a cron job to process background tasks:

sudo crontab -e

Add the following line to run import tasks every hour:

0 * * * * /usr/bin/php /var/www/html/wallabag/bin/console wallabag:import:redis-worker --env=prod >> /var/log/wallabag-import.log 2>&1

Configuring Cache Management

For better performance, consider setting up Redis for caching:

sudo apt install redis-server php-redis
sudo systemctl enable redis-server
sudo systemctl start redis-server

Then update your parameters.yml file to include the Redis configuration.

Testing Your Wallabag Installation

You can now access your Wallabag instance by navigating to your domain in a web browser:

https://wallabag.example.com

The first time you access the site, you’ll be prompted to log in with the admin account you created during installation.

Verifying Functionality

Try saving an article by:
1. Clicking “New entry” in the top navigation bar
2. Entering a URL in the field provided
3. Clicking “Save”

The article should be retrieved, parsed, and saved to your Wallabag instance.

Setting Up Browser Extensions

To make the most of Wallabag, install browser extensions that facilitate saving articles:
– Firefox: Wallabagger for Firefox
– Chrome: Wallabagger for Chrome

Configuring Mobile Apps

Wallabag offers mobile apps for both Android and iOS. To configure them:
1. Download the app from your device’s app store
2. Enter your Wallabag URL
3. Provide your login credentials
4. For API access, generate a client ID and secret in your Wallabag account settings

Security Considerations

Keeping Wallabag Updated

Regularly check for updates and upgrade your Wallabag installation:

cd /var/www/html/wallabag
git pull
sudo -u www-data make update

Web Server Security Hardening

For Apache:

sudo a2enmod headers
sudo systemctl restart apache2

For Nginx, ensure your server block includes security headers:

add_header X-Frame-Options "SAMEORIGIN";
add_header X-XSS-Protection "1; mode=block";
add_header X-Content-Type-Options "nosniff";

Firewall Configuration

Set up a firewall to protect your server:

sudo apt install ufw
sudo ufw allow ssh
sudo ufw allow http
sudo ufw allow https
sudo ufw enable

Maintenance and Updates

Backup Strategy

Regularly back up your Wallabag data:

# For SQLite
cp /var/www/html/wallabag/data/db/wallabag.sqlite /backup/wallabag_$(date +%Y%m%d).sqlite

# For MySQL
mysqldump -u root -p wallabag > /backup/wallabag_$(date +%Y%m%d).sql

Log Management

Monitor Wallabag logs for issues:

tail -f /var/log/apache2/wallabag_error.log
# or for Nginx
tail -f /var/log/nginx/wallabag_error.log

Performance Monitoring

Check PHP-FPM status:

systemctl status php8.2-fpm

Monitor system resources:

htop

Troubleshooting Common Issues

Permission Problems

If you encounter permission issues, ensure proper ownership:

sudo chown -R www-data:www-data /var/www/html/wallabag
sudo chmod -R 755 /var/www/html/wallabag

Database Connection Issues

For MySQL connection problems:
1. Verify database credentials in parameters.yml
2. Check that the MySQL service is running: systemctl status mysql
3. Test database connection: mysql -u wallabag -p wallabag

PHP Extension Errors

If the installer reports missing PHP extensions:

sudo apt install php-mbstring php-gd php-xml php-curl php-zip php-tidy
sudo systemctl restart php8.2-fpm

For Apache with mod_php:

sudo systemctl restart apache2

Web Server Configuration Errors

For Apache errors, check:

sudo apachectl configtest

For Nginx errors, check:

sudo nginx -t

Congratulations! You have successfully installed Wallabag. Thanks for using this tutorial for installing Wallabag on Debian 12 “Bookworm” system. For additional help or useful information, we recommend you check the Wallabag website.