How to Self-Host Wallabag with Docker Compose

What Is Wallabag?

Wallabag is a self-hosted read-later application. Save articles from the web, strip away the clutter, and read them later in a clean, distraction-free format — on any device. It’s a direct replacement for Pocket and Instapaper. Wallabag extracts article content, stores it locally, provides full-text search, supports tagging, and has native mobile apps for Android and iOS. It also integrates with e-readers, RSS readers, and browser extensions.

Prerequisites

A Linux server (Ubuntu 22.04+ recommended)
Docker and Docker Compose installed (guide)
512 MB of free RAM
1 GB of free disk space
A domain name (optional, for remote access)

Docker Compose Configuration

Create a docker-compose.yml file:

services:
  wallabag:
    image: wallabag/wallabag:2.6.14
    container_name: wallabag
    restart: unless-stopped
    ports:
      - "8080:80"
    environment:
      MYSQL_ROOT_PASSWORD: "change_this_root_password"        # CHANGE THIS
      SYMFONY__ENV__DATABASE_DRIVER: "pdo_pgsql"
      SYMFONY__ENV__DATABASE_HOST: "wallabag_db"
      SYMFONY__ENV__DATABASE_PORT: "5432"
      SYMFONY__ENV__DATABASE_NAME: "wallabag"
      SYMFONY__ENV__DATABASE_USER: "wallabag"
      SYMFONY__ENV__DATABASE_PASSWORD: "change_this_strong_password"  # Must match PostgreSQL
      SYMFONY__ENV__DATABASE_CHARSET: "utf8"
      SYMFONY__ENV__DOMAIN_NAME: "http://localhost:8080"      # Set to your public URL
      SYMFONY__ENV__SERVER_NAME: "Wallabag"
      SYMFONY__ENV__SECRET: "change_this_to_random_string"    # CHANGE THIS — generate with: openssl rand -hex 32
      SYMFONY__ENV__FOSUSER_REGISTRATION: "false"             # Disable public registration
      SYMFONY__ENV__FOSUSER_CONFIRMATION: "false"
    volumes:
      - wallabag_images:/var/www/wallabag/web/assets/images
      - wallabag_data:/var/www/wallabag/data
    depends_on:
      wallabag_db:
        condition: service_healthy
      wallabag_redis:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost"]
      interval: 30s
      timeout: 10s
      retries: 5
      start_period: 30s

  wallabag_db:
    image: postgres:16-alpine
    container_name: wallabag_db
    restart: unless-stopped
    environment:
      POSTGRES_USER: wallabag
      POSTGRES_PASSWORD: change_this_strong_password          # Must match SYMFONY__ENV__DATABASE_PASSWORD
      POSTGRES_DB: wallabag
    volumes:
      - wallabag_pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U wallabag"]
      interval: 10s
      timeout: 5s
      retries: 5

  wallabag_redis:
    image: redis:7-alpine
    container_name: wallabag_redis
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5

volumes:
  wallabag_images:
  wallabag_data:
  wallabag_pgdata:

Start the stack:

docker compose up -d

Initial Setup

Wait 30-60 seconds for database migrations to complete on first start
Open http://your-server-ip:8080 in your browser
Default credentials: wallabag / wallabag
Change your password immediately under Config → User Information
Install the browser extension for one-click saving

Configuration

Browser Extensions

Firefox: Wallabagger
Chrome: Wallabagger

Configure with your Wallabag URL and generate an API client ID/secret under API clients management in Wallabag settings.

Mobile Apps

Android: Wallabag (official)
iOS: Wallabag (official)

Both apps support offline reading and sync.

Import from Pocket/Instapaper

Wallabag has built-in importers:

Go to Config → Import
Select your source (Pocket, Instapaper, Pinboard, Firefox, Chrome, and more)
Follow the instructions to authorize and import

Tagging Rules

Automatically tag articles based on content:

Go to Config → Tagging Rules
Add rules like: title matches "Docker" → tag: docker
Rules apply to new articles as they’re saved

SMTP for Email Features

environment:
  SYMFONY__ENV__MAILER_DSN: "smtp://user:password@smtp.example.com:587"
  SYMFONY__ENV__FROM_EMAIL: "wallabag@example.com"

Advanced Configuration (Optional)

RSS Feeds

Wallabag generates RSS feeds for your saved articles — useful for syncing with RSS readers like FreshRSS or Miniflux:

Go to Config → RSS
Generate a token
Use the feed URLs provided

E-Reader Integration

Send articles to your Kindle or Kobo:

environment:
  SYMFONY__ENV__MAILER_DSN: "smtp://user:password@smtp.example.com:587"

Then configure under Config → Send to Kindle/Kobo with your device email.

API Usage

Wallabag exposes a REST API for automation:

# Get an OAuth token
curl -X POST "http://localhost:8080/oauth/v2/token" \
  -d "grant_type=password&client_id=YOUR_CLIENT_ID&client_secret=YOUR_SECRET&username=wallabag&password=yourpass"

# Save a URL
curl -X POST "http://localhost:8080/api/entries.json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d "url=https://example.com/article"

Reverse Proxy

Set SYMFONY__ENV__DOMAIN_NAME to your public URL:

SYMFONY__ENV__DOMAIN_NAME: "https://read.example.com"

Nginx Proxy Manager config:

Scheme: http
Forward Hostname: wallabag
Forward Port: 80

See Reverse Proxy Setup for full configuration.

Backup

# Database
docker compose exec wallabag_db pg_dump -U wallabag wallabag > wallabag-backup-$(date +%Y%m%d).sql

# Article images
docker run --rm -v wallabag_images:/data -v $(pwd):/backup alpine \
  tar czf /backup/wallabag-images-$(date +%Y%m%d).tar.gz /data

See Backup Strategy for a complete backup approach.

Troubleshooting

”Internal Server Error” on First Access

Symptom: 500 error when accessing Wallabag for the first time. Fix: Database migrations may not have completed. Check the logs:

docker compose logs wallabag | grep -i error

Wait 60 seconds and try again. If persistent, restart the container. Wallabag runs migrations automatically on startup.

Articles Not Being Parsed Correctly

Symptom: Saved articles show only the URL or raw HTML instead of clean content. Fix: Wallabag uses PHP libraries for content extraction. Some sites block server-side fetching. Try updating the site config rules:

docker compose exec wallabag bin/console wallabag:install --env=prod

Mobile App Can’t Connect

Symptom: Android/iOS app reports connection errors. Fix: Create an API client under Config → API clients management in the web UI. Use the generated Client ID and Client Secret in the app. Ensure your URL is accessible from your phone’s network.

Slow Performance with Many Articles

Symptom: Page loads slow after saving thousands of articles. Fix: Ensure PostgreSQL (not SQLite) is configured. Add Redis for caching (already included in the Compose above). If still slow, increase PHP memory:

environment:
  PHP_MEMORY_LIMIT: "256M"

Frequently Asked Questions

Can I import my Pocket or Instapaper library into Wallabag?

Yes. Wallabag has built-in importers for Pocket, Instapaper, Pinboard, Firefox bookmarks, Chrome bookmarks, and Wallabag v1/v2 exports. Go to Config → Import in the web UI. For Pocket, you will need to generate an API consumer key from Pocket’s developer portal. Wallabag imports articles with tags, starred status, and archived status preserved.

Does Wallabag have mobile apps?

Yes. Wallabag has official apps for Android (Play Store and F-Droid) and iOS. Both apps support offline reading — articles are downloaded to your device for reading without an internet connection. You can also use share intents to save articles from any app directly to Wallabag. Configure the app by creating an API client in Wallabag’s web UI under Config → API clients management.

Is Wallabag a bookmark manager?

No. Wallabag is a read-later app — it saves the full content of articles for clean, distraction-free reading. It does not organize arbitrary URLs into collections or take page screenshots like Linkwarden. If you need bookmark management with tags, collections, and page archiving, look at Linkwarden or Linkding. If you want to save articles to read later (like Pocket or Instapaper), Wallabag is the right tool.

Yes. Wallabag can generate public links for individual articles, allowing anyone with the link to read the article without a Wallabag account. Enable this in the article’s options. For RSS-based sharing, Wallabag generates per-user RSS feeds for unread, starred, and archived articles that can be shared or consumed by feed readers.

How do I set up the browser extension?

Install the Wallabag browser extension for Chrome or Firefox. In the extension settings, enter your Wallabag URL, create an API client under Config → API clients management, and enter the Client ID and Client Secret. After authenticating, clicking the extension icon saves the current page to Wallabag instantly.

Resource Requirements

RAM: ~150 MB idle, ~300 MB during article processing
CPU: Low — content parsing is lightweight
Disk: ~200 MB for the application, plus storage for article images and content

Verdict

Wallabag is the best self-hosted read-later app. It does one thing well: save articles for clean, distraction-free reading later. The mobile apps work offline, the browser extensions make saving effortless, and the Pocket/Instapaper import makes migration painless. It’s not a bookmark manager — if you need collections, team sharing, and page archiving, use Linkwarden. But for personal read-later use, Wallabag is exactly right.