homelab-optimized/hosts/vms/seattle/wallabag/README.md

Wallabag - Read-Later Service

📋 Overview

Wallabag is a self-hosted read-later application that allows you to save articles, web pages, and other content to read later. It's similar to Pocket or Instapaper but completely self-hosted.

🔧 Service Details

Property	Value
Container Name	wallabag
Image	wallabag/wallabag:latest
Internal Port	80
Host Port	127.0.0.1:8880
Domain	wb.vish.gg
Database	SQLite (embedded)

🌐 Network Access

• Public URL: https://wb.vish.gg
• Local Access: http://127.0.0.1:8880
• Reverse Proxy: Nginx configuration in /etc/nginx/sites-enabled/wallabag

📁 Directory Structure

/opt/wallabag/
├── docker-compose.yml    # Service configuration
├── data/                # Application data
│   ├── db/             # SQLite database
│   └── assets/         # User uploads
└── images/             # Article images

🚀 Management Commands

Docker Operations

# Navigate to service directory
cd /opt/wallabag/

# Start service
docker-compose up -d

# Stop service
docker-compose down

# Restart service
docker-compose restart

# View logs
docker-compose logs -f

# Update service
docker-compose pull
docker-compose up -d

Container Management

# Check container status
docker ps | grep wallabag

# Execute commands in container
docker exec -it wallabag bash

# View container logs
docker logs wallabag -f

# Check container health
docker inspect wallabag | grep -A 10 Health

⚙️ Configuration

Environment Variables

• Database: SQLite (no external database required)
• Domain: https://wb.vish.gg
• Registration: Disabled (FOSUSER_REGISTRATION=false)
• Email Confirmation: Disabled (FOSUSER_CONFIRMATION=false)

Volume Mounts

• Data: /opt/wallabag/data → /var/www/wallabag/data
• Images: /opt/wallabag/images → /var/www/wallabag/web/assets/images

Health Check

• Endpoint: http://localhost:80
• Interval: 30 seconds
• Timeout: 10 seconds
• Retries: 3

🔒 Security Features

• Local Binding: Only accessible via localhost (127.0.0.1:8880)
• Nginx Proxy: SSL termination and security headers
• Registration Disabled: Prevents unauthorized account creation
• Data Isolation: Runs in isolated Docker container

📱 Usage

Web Interface

1. Access via https://wb.vish.gg
2. Log in with configured credentials
3. Use browser extension or bookmarklet to save articles
4. Organize with tags and categories
5. Export/import data as needed

Browser Extensions

• Available for Chrome, Firefox, and other browsers
• Allows one-click saving of web pages
• Automatic tagging and categorization

🔧 Maintenance

Backup

# Backup data directory
tar -czf wallabag-backup-$(date +%Y%m%d).tar.gz /opt/wallabag/data/

# Backup database only
cp /opt/wallabag/data/db/wallabag.sqlite /backup/location/

Updates

cd /opt/wallabag/
docker-compose pull
docker-compose up -d

Database Maintenance

# Access SQLite database
docker exec -it wallabag sqlite3 /var/www/wallabag/data/db/wallabag.sqlite

# Check database size
du -sh /opt/wallabag/data/db/wallabag.sqlite

🐛 Troubleshooting

Common Issues

# Container won't start
docker-compose logs wallabag

# Permission issues
sudo chown -R 33:33 /opt/wallabag/data/
sudo chmod -R 755 /opt/wallabag/data/

# Database corruption
# Restore from backup or recreate container

# Nginx proxy issues
sudo nginx -t
sudo systemctl reload nginx

Health Check

# Test local endpoint
curl -I http://127.0.0.1:8880

# Test public endpoint
curl -I https://wb.vish.gg

# Check container health
docker inspect wallabag | grep -A 5 '"Health"'

🔗 Related Services

• Nginx: Reverse proxy with SSL termination
• Let's Encrypt: SSL certificate management
• Docker: Container runtime

📚 External Resources

• Wallabag Documentation
• Docker Hub
• GitHub Repository
• Browser Extensions