Deploying Wallabag

Introduction

Wallabag is a self-hosted read-it-later application that saves web articles for offline reading. Similar to Pocket or Instapaper but fully open-source and privacy-respecting, Wallabag extracts article content, removes clutter, and provides a clean reading experience across all your devices.

Key highlights of Wallabag:

Article Extraction: Automatically extracts readable content from web pages
Offline Reading: Save articles for reading without internet connection
Browser Extensions: One-click saving from Chrome, Firefox, and other browsers
Mobile Apps: Native Android and iOS apps for on-the-go reading
Tagging: Organize articles with custom tags
Annotations: Highlight text and add notes to articles
Export Options: Export to EPUB, PDF, or plain text
RSS Feeds: Generate feeds of your reading list
Full-Text Search: Search across all saved articles
Multi-User: Support for multiple users on one instance
API: REST API for third-party integrations

This guide walks through deploying Wallabag on Klutch.sh using Docker, configuring the application, and setting up your personal reading list.

Why Deploy Wallabag on Klutch.sh

Deploying Wallabag on Klutch.sh provides several advantages for read-it-later functionality:

Simplified Deployment: Klutch.sh automatically detects your Dockerfile and builds Wallabag without complex orchestration. Push to GitHub, and your reading list deploys automatically.

Persistent Storage: Attach persistent volumes for your database and article cache. Your reading list survives container restarts.

HTTPS by Default: Klutch.sh provides automatic SSL certificates for secure access and browser extension compatibility.

GitHub Integration: Connect your configuration repository directly from GitHub. Updates trigger automatic redeployments.

Always Available: Access your reading list from any device, anywhere.

Prerequisites

Before deploying Wallabag on Klutch.sh, ensure you have:

A Klutch.sh account
A GitHub account with a repository for your configuration
Basic familiarity with Docker and containerization concepts
A PostgreSQL or MySQL database (recommended for production)

Preparing Your Repository

Create a GitHub repository containing your Dockerfile for Wallabag deployment.

Repository Structure

wallabag-deploy/
├── Dockerfile
└── .dockerignore

Creating the Dockerfile

FROM wallabag/wallabag:latest

# Set environment variables
ENV SYMFONY__ENV__DATABASE_DRIVER=${DATABASE_DRIVER:-pdo_pgsql}
ENV SYMFONY__ENV__DATABASE_HOST=${DATABASE_HOST}
ENV SYMFONY__ENV__DATABASE_PORT=${DATABASE_PORT:-5432}
ENV SYMFONY__ENV__DATABASE_NAME=${DATABASE_NAME:-wallabag}
ENV SYMFONY__ENV__DATABASE_USER=${DATABASE_USER}
ENV SYMFONY__ENV__DATABASE_PASSWORD=${DATABASE_PASSWORD}
ENV SYMFONY__ENV__DATABASE_CHARSET=utf8

ENV SYMFONY__ENV__DOMAIN_NAME=${DOMAIN_NAME}
ENV SYMFONY__ENV__SERVER_NAME=${SERVER_NAME:-"Wallabag"}

ENV SYMFONY__ENV__MAILER_DSN=${MAILER_DSN:-null://null}

ENV SYMFONY__ENV__FROM_EMAIL=${FROM_EMAIL:-wallabag@example.com}

ENV SYMFONY__ENV__SECRET=${SECRET}

# Create data directories
RUN mkdir -p /var/www/wallabag/data/db /var/www/wallabag/data/assets

# Expose the web interface port
EXPOSE 80

# Volumes for persistent data
VOLUME ["/var/www/wallabag/data", "/var/www/wallabag/var"]

Environment Variables Reference

Variable	Required	Default	Description
`DATABASE_DRIVER`	No	`pdo_pgsql`	Database driver (pdo_pgsql, pdo_mysql, pdo_sqlite)
`DATABASE_HOST`	Yes	-	Database hostname
`DATABASE_PORT`	No	`5432`	Database port
`DATABASE_NAME`	No	`wallabag`	Database name
`DATABASE_USER`	Yes	-	Database username
`DATABASE_PASSWORD`	Yes	-	Database password
`DOMAIN_NAME`	Yes	-	Full URL of your Wallabag instance
`SECRET`	Yes	-	Symfony secret for CSRF protection
`FROM_EMAIL`	No	`wallabag@example.com`	Email sender address

Deploying Wallabag on Klutch.sh

Set Up PostgreSQL Database

Deploy a PostgreSQL instance on Klutch.sh or use an external database service. Create a database for Wallabag.

Generate a Secret

Generate a secure secret for Symfony:

openssl rand -hex 32

Push Your Repository to GitHub

Initialize your repository and push to GitHub with your Dockerfile.

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project. Give it a descriptive name like “wallabag” or “reading-list”.

Create a New App

Within your project, create a new app. Connect your GitHub account if you haven’t already, then select the repository containing your Wallabag Dockerfile.

Configure HTTP Traffic

In the deployment settings:

Select HTTP as the traffic type
Set the internal port to 80

Set Environment Variables

Add the following environment variables:

Variable	Value
`DATABASE_HOST`	Your PostgreSQL hostname
`DATABASE_NAME`	`wallabag`
`DATABASE_USER`	Your database username
`DATABASE_PASSWORD`	Your database password
`DOMAIN_NAME`	`https://your-app-name.klutch.sh`
`SECRET`	Your generated secret

Attach Persistent Volumes

Add the following volumes:

Mount Path	Recommended Size	Purpose
`/var/www/wallabag/data`	10 GB	Article cache and assets
`/var/www/wallabag/var`	2 GB	Logs and cache

Deploy Your Application

Click Deploy to start the build process. Klutch.sh will build the container, attach volumes, and provision an HTTPS certificate.

Access Wallabag

Once deployment completes, access your Wallabag instance at https://your-app-name.klutch.sh. Default credentials are:

Username: wallabag
Password: wallabag

Change the default password immediately after first login.

Saving Articles

Browser Extensions

Install browser extensions for one-click saving:

Configure extensions with your Wallabag URL and API credentials.

Bookmarklet

Add the bookmarklet from Settings > Import for browsers without extensions.

Email Import

Configure email-to-article import:

Navigate to Settings > Import
Set up the email import address
Forward newsletters and articles to your Wallabag email

RSS Feeds

Import articles from RSS feeds:

Go to Settings > Import
Enter RSS feed URLs
Articles are automatically saved

Reading Experience

Interface Customization

Adjust the reading experience:

Theme: Choose light or dark mode
Font: Select your preferred reading font
Size: Adjust text size for comfort
Width: Set the maximum content width

Article Management

Organize your reading list:

Archive: Mark articles as read
Favorites: Star important articles
Tags: Categorize with custom tags
Filters: View by status, tag, or reading time

Annotations

Highlight and annotate:

Select text in an article
Choose highlight color
Add notes to selections
Export annotations with the article

Mobile Apps

Android

Download from Google Play or F-Droid.

iOS

Download from the App Store.

Configuration

Open the app
Enter your Wallabag URL
Log in with your credentials
Enable offline sync for articles

Exporting Content

Single Article Export

Open an article
Click the export button
Choose format: EPUB, PDF, or text

Bulk Export

Navigate to Settings > Export
Select export format
Download your entire archive

Multi-User Setup

Creating Users

Go to Settings > Users
Click Create a new user
Enter username, email, and password
Set user role (admin or regular user)

User Permissions

Admin: Full access to all settings
User: Can only manage their own articles

Troubleshooting

Articles Not Extracting Properly

Some sites block content extraction
Try using the browser extension instead of URL import
Report problematic sites to the Wallabag community

Check database connectivity
Verify SECRET hasn’t changed
Clear browser cookies

Images Not Loading

Check DOMAIN_NAME is set correctly
Verify assets volume is mounted
Clear the application cache

Slow Performance

Ensure database indexes are optimized
Increase PHP memory limit
Consider using Redis for caching

Additional Resources

Conclusion

Deploying Wallabag on Klutch.sh gives you a powerful, privacy-respecting read-it-later service with full control over your data. The combination of Wallabag’s rich feature set and Klutch.sh’s deployment simplicity means you can quickly build your personal reading archive, accessible from any device without relying on third-party services.