Wallabag Read-It-Later Installation

Wallabag is a self-hosted read-it-later application that saves web articles to your server for offline reading, functioning as an open-source Pocket or Instapaper alternative. With browser extensions, mobile apps, RSS feeds, and annotation support, Wallabag lets you build a personal article archive on your Linux server without tracking or subscription fees.

Prerequisites

  • Ubuntu 20.04+, Debian 11+, or CentOS/Rocky 8+
  • Docker and Docker Compose installed
  • Root or sudo access
  • A domain name for external access and HTTPS

Installing Wallabag with Docker

# Create Wallabag directory
sudo mkdir -p /opt/wallabag/data

# Create docker-compose.yml
sudo tee /opt/wallabag/docker-compose.yml <<'EOF'
version: '3.8'

services:
  wallabag:
    image: wallabag/wallabag
    restart: unless-stopped
    ports:
      - "8080:80"
    environment:
      - MYSQL_ROOT_PASSWORD=rootpassword      # Change this!
      - 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=dbpassword  # Change this!
      - SYMFONY__ENV__MAILER_HOST=smtp.example.com
      - [email protected]
      - SYMFONY__ENV__MAILER_PASSWORD=smtp-password
      - [email protected]
      - SYMFONY__ENV__DOMAIN_NAME=https://wallabag.example.com
      - SYMFONY__ENV__SERVER_NAME="My Wallabag"
      - POPULATE_DATABASE=true
    volumes:
      - /opt/wallabag/data:/var/www/wallabag/data
      - /opt/wallabag/images:/var/www/wallabag/web/assets/images
    depends_on:
      - db
    healthcheck:
      test: ["CMD", "wget" ,"--no-verbose", "--tries=1", "--spider", "http://localhost"]
      interval: 1m
      timeout: 3s

  db:
    image: mariadb:11
    restart: unless-stopped
    environment:
      MYSQL_ROOT_PASSWORD: rootpassword       # Change this!
      MYSQL_DATABASE: wallabag
      MYSQL_USER: wallabag
      MYSQL_PASSWORD: dbpassword              # Change this!
    volumes:
      - /opt/wallabag/db:/var/lib/mysql

  redis:
    image: redis:7-alpine
    restart: unless-stopped
EOF

cd /opt/wallabag
sudo docker compose up -d

# First startup takes a few minutes (database initialization)
sudo docker compose logs -f wallabag

Access at http://your-server:8080. Default credentials: wallabag / wallabag.

Initial Setup

Change admin credentials immediately:

  1. Log in with wallabag / wallabag
  2. Go to wallabag (username, top right) > Edit my profile
  3. Change username, email, and password

Create additional users (admin only):

# Via CLI in Docker
sudo docker compose exec wallabag \
  php /var/www/wallabag/bin/console \
  fos:user:create \
  --env=prod \
  newuser [email protected] "UserPassword123!"

# Grant admin role to a user
sudo docker compose exec wallabag \
  php /var/www/wallabag/bin/console \
  fos:user:promote \
  --env=prod \
  newuser ROLE_ADMIN

Configure Nginx reverse proxy:

# /etc/nginx/sites-available/wallabag
server {
    listen 80;
    server_name wallabag.example.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl;
    server_name wallabag.example.com;

    ssl_certificate /etc/letsencrypt/live/wallabag.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/wallabag.example.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

sudo ln -s /etc/nginx/sites-available/wallabag /etc/nginx/sites-enabled/
sudo certbot --nginx -d wallabag.example.com
sudo systemctl reload nginx

Browser Extension Configuration

Wallabag has official browser extensions for one-click saving:

Install the extension:

Configure the extension:

  1. Click the extension icon → Options
  2. Set Wallabag URL: https://wallabag.example.com
  3. Set Client ID and Client Secret (from API settings)
  4. Enter your username and password
  5. Click Test connection

Create API credentials:

  1. In Wallabag, go to API clients management (in the developer menu)
  2. Click Create a new client
  3. Name the client (e.g., "Firefox extension")
  4. Copy the Client ID and Client Secret

Mobile App Setup

Android: wallabag for Android (available on F-Droid and Google Play)

iOS: Readder, Carrots, or the official wallabag iOS app

Configure the mobile app:

Server URL: https://wallabag.example.com
Username:   your-username
Password:   your-password
Client ID:  (from API settings)
Client Secret: (from API settings)

Test API access:

# Get an OAuth token
TOKEN=$(curl -s -X POST "https://wallabag.example.com/oauth/v2/token" \
  -d "grant_type=password" \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "username=wallabag" \
  -d "password=wallabag" | jq -r '.access_token')

# Save an article via API
curl -X POST "https://wallabag.example.com/api/entries.json" \
  -H "Authorization: Bearer $TOKEN" \
  -d "url=https://example.com/article"

Tagging and Annotations

Create and assign tags:

  1. Open an article in Wallabag
  2. Click the tag icon in the article toolbar
  3. Type a tag name and press Enter
  4. Tags can be used to filter and organize articles

Apply tagging rules automatically:

  1. Go to Settings > Tagging rules
  2. Click Add a rule
  3. Set condition: e.g., domainName matches "nytimes.com"
  4. Set tag to apply: news
# Example tagging rules:
# domainName matches "github.com"    → tag: coding
# content matches "kubernetes"       → tag: devops
# isUnread = true                    → (use as filter, not rule)

Annotate articles:

  1. Select any text while reading an article
  2. A popup appears — click Annotate
  3. Add your annotation text
  4. Annotations are stored with the article and searchable

RSS Feeds

Wallabag generates RSS feeds for your article collections:

Access your RSS feeds:

  1. Go to Settings > RSS (under your user settings)
  2. Copy the RSS token shown
  3. Use these feed URLs in any RSS reader:
All articles:   https://wallabag.example.com/feed/username/TOKEN/
Unread:         https://wallabag.example.com/feed/username/TOKEN/unread
Starred:        https://wallabag.example.com/feed/username/TOKEN/starred
Archived:       https://wallabag.example.com/feed/username/TOKEN/archive
Tagged:         https://wallabag.example.com/feed/username/TOKEN/tags/tagname

Data Import and Export

Import from Pocket:

  1. Export your Pocket data at getpocket.com/export
  2. In Wallabag → Import → Pocket
  3. Upload the exported HTML file
  4. All bookmarks are imported with their tags

Import from other services:

# Wallabag supports importing from:
# - Pocket (HTML export)
# - Instapaper (CSV export)
# - Readability (JSON export)
# - Pinboard (JSON export)
# - Delicious (XML export)
# - Firefox/Chrome bookmarks (HTML)

Export your library:

  1. Go to Export in the article list
  2. Select format: EPUB, PDF, CSV, JSON, or HTML
  3. Choose which articles (all, unread, starred, etc.)
  4. Download the exported file

Full database export via CLI:

# Export all articles as JSON
sudo docker compose exec wallabag \
  php /var/www/wallabag/bin/console \
  wallabag:export \
  --env=prod \
  --username=admin \
  --filepath=/var/www/wallabag/data/export/all.json

Troubleshooting

Article content not fetching (empty or partial articles):

# Wallabag uses Graby for content extraction
# Check logs
sudo docker compose logs wallabag | grep -i "fetch\|error"

# Some sites block server-side fetching
# Try setting a custom user agent in settings:
# Admin > Internal Settings > Misc > Custom user-agent

# Force re-fetch an article via the UI:
# Open article → ... → Re-fetch content

Cannot save articles from browser extension:

# Test API connectivity
curl -v "https://wallabag.example.com/api/version"

# Verify OAuth credentials are correct
# Settings > API clients management — regenerate if needed

# Check CORS headers if using extension with HTTPS site
sudo nginx -t

High memory usage:

# Check container memory usage
sudo docker stats

# Clear Wallabag cache
sudo docker compose exec wallabag \
  php /var/www/wallabag/bin/console \
  cache:clear --env=prod

# Optimize database
sudo docker compose exec db \
  mysql -u wallabag -pdbpassword wallabag -e "OPTIMIZE TABLE entry;"

Conclusion

Wallabag provides a complete self-hosted read-it-later solution with browser extensions, mobile apps, RSS feed generation, and migration tools from popular services like Pocket and Instapaper, all running on your own infrastructure without usage tracking or data collection. The combination of automatic tagging rules, annotations, and multi-format export makes it a durable long-term article archive that remains accessible even without an internet connection through offline-capable mobile apps.