Wallabag is a powerful, self-hosted read-it-later application designed to help users save, organize, and retrieve web content offline. It’s an excellent choice for privacy-conscious users who value data control, offering customization and integration options not available in commercial services like Pocket or Instapaper. In this guide, you’ll learn how to deploy Wallabag, configure it with Nginx, manage logs, implement a robust backup strategy, and leverage its unique features.
Installing Wallabag
📦 Docker/Docker Compose Setup
Docker simplifies Wallabag deployment by bundling all dependencies in a container. Below, we’ll generate a docker-compose.yml file and use it to deploy Wallabag.
Create a docker-compose.yml file:
version: '3'
services:
wallabag:
image: wallabag/wallabag
container_name: wallabag
restart: always
environment:
- 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=yourpassword
- SYMFONY__ENV__MAILER_HOST=mail
- [email protected]
- SYMFONY__ENV__MAILER_PASSWORD=your-email-password
ports:
- "8080:80"
depends_on:
- db
db:
image: mariadb:latest
container_name: wallabag_db
restart: always
environment:
- MYSQL_ROOT_PASSWORD=yourrootpassword
- MYSQL_DATABASE=wallabag
- MYSQL_USER=wallabag
- MYSQL_PASSWORD=yourpassword
volumes:
- db_data:/var/lib/mysql
volumes:
db_data:
Run the following commands to deploy Wallabag with Docker Compose:
docker-compose pull
## Start the Wallabag containers
docker-compose up -d
Access Wallabag at http://<your-server-ip>:8080.
🚀 Manual Installation
For those who prefer manual installation, Wallabag offers flexibility for self-hosting on Linux.
Install dependencies and set up PHP:
sudo apt update
sudo apt install -y php php-fpm php-mysql unzip git curl mariadb-server
Clone the Wallabag repository:
git clone https://github.com/wallabag/wallabag.git
cd wallabag
git checkout 2.5.1 # Use the latest stable release
Install Wallabag:
composer install --no-dev -o
php bin/console wallabag:install
Configure your web server (instructions below) to serve the app.
Configuring Nginx as a Reverse Proxy
🌐 Nginx Configuration
To serve Wallabag via Nginx, create a custom server block.
Edit /etc/nginx/sites-available/wallabag:
server {
listen 80;
server_name yourdomain.com;
root /path/to/wallabag/web;
index app.php;
location / {
try_files $uri /app.php$is_args$args;
}
location ~ ^/app\.php(/|$) {
fastcgi_pass unix:/var/run/php/php7.4-fpm.sock;
fastcgi_split_path_info ^(.+\.php)(/.*)$;
include fastcgi_params;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
fastcgi_param PATH_INFO $fastcgi_path_info;
}
location ~ \.php$ {
return 404;
}
location ~ /\.(?!well-known).* {
deny all;
}
}
Enable the configuration:
sudo ln -s /etc/nginx/sites-available/wallabag /etc/nginx/sites-enabled/
sudo systemctl restart nginx
🔒 SSL/TLS Setup
Secure your Wallabag instance with Let's Encrypt.
Install Certbot and configure SSL:
sudo apt install certbot python3-certbot-nginx
sudo certbot --nginx -d yourdomain.com
Automate certificate renewal:
sudo systemctl enable certbot.timer
sudo systemctl start certbot.timer
🛠️ Testing and Reloading Nginx
Test your configuration for syntax errors and reload:
sudo nginx -t
sudo systemctl reload nginx
Logging and Debugging Wallabag
🗃️ Enabling Debug Logs
Enable debug-level logging in the .env file of Wallabag:
APP_ENV=dev
APP_DEBUG=1
Restart the server:
php bin/console cache:clear
📄 Viewing Logs
For Docker deployments, view logs with:
docker logs wallabag
For manual installations, check logs in the var/log/ directory:
tail -f /path/to/wallabag/var/log/prod.log
🛠️ Troubleshooting Common Issues
-
Database connectivity errors: Verify database credentials in
.env. -
502 Bad Gateway: Confirm PHP-FPM is running and properly configured in Nginx.
📤 Exporting Logs
To forward logs to ELK Stack:
docker logs wallabag | filebeat -e -c filebeat.yml
Backup and Restore
🗂️ File-Based Backups
Backup the Wallabag directory:
tar -czf wallabag-backup.tar.gz /path/to/wallabag
🔄 Database Backups
Export your MySQL database:
mysqldump -u wallabag -p wallabag > wallabag-db.sql
Restore with:
mysql -u wallabag -p wallabag < wallabag-db.sql
📅 Automated Backup Scripts
Automate backups using a cron job:
crontab -e
## Add the following line
0 2 * * * tar -czf /backups/wallabag-$(date +\%F).tar.gz /path/to/wallabag
Updating and Upgrading Wallabag
⬆️ Updating Docker Images
Pull the latest Wallabag image and redeploy:
docker-compose pull
docker-compose up -d
🛠️ Manual Updates
For manual installations, pull updates and re-install:
cd /path/to/wallabag
git pull
composer install --no-dev -o
php bin/console cache:clear
🔍 Checking for Updates
Stay informed of new releases via the Wallabag GitHub repository.
Leveraging Wallabag’s Unique Features
🔧 Enabling APIs
Wallabag supports a robust API for integration. Enable it in your .env file:
FOS_OAUTH_SERVER_CONFIG=true
Generate a client token:
php bin/console fos:oauth-server:create-client --redirect-uri="http://yourapp.com"
Use the API with curl or scripts:
curl -X GET -H "Authorization: Bearer <access_token>" https://yourdomain.com/api/entries.json
🌟 Advanced Configurations
Customize Wallabag by editing parameters.yml, such as enabling Redis for caching:
redis:
host: localhost
port: 6379
Restart the app to apply changes:
php bin/console cache:clear
Wrapping Up
Wallabag empowers you to take full control of your saved content with its powerful features and self-hosting capabilities. By following this guide, you’ve deployed Wallabag, secured it with SSL, configured backups, and explored its advanced functionality. Start optimizing your reading workflow today with Wallabag’s flexible and customizable platform!
