Installation Guide

October 13, 2025 · View on GitHub

This guide provides detailed installation instructions for ListSync, covering both Docker and manual installation methods.

📋 Table of Contents

  1. Prerequisites
  2. Docker Installation (Recommended)
  3. Manual Installation
  4. Post-Installation Setup
  5. Verification
  6. Updating
  7. Troubleshooting

🔧 Prerequisites

For Docker Installation

  • Docker: Version 20.10 or higher
  • Docker Compose: Version 2.0 or higher
  • System Requirements:
    • 2GB RAM minimum (4GB recommended)
    • 1GB free disk space
    • Internet connection for fetching lists

For Manual Installation

  • Python: Version 3.8 or higher
  • Node.js: Version 18 or higher (for web interface)
  • System Requirements:
    • 4GB RAM minimum
    • 2GB free disk space
    • Chrome/Chromium browser (for Selenium)
    • Internet connection

Common Requirements

  • Overseerr Instance: Running and accessible
  • Network Access: To IMDb, Trakt, Letterboxd, MDBList, and other list providers

Docker installation provides the easiest setup with all dependencies pre-configured.

Quick Start

  1. Clone the repository:

    git clone https://github.com/Woahai321/list-sync.git
cd list-sync

  2. Create environment file:

    cp env.example .env

  3. Configure your settings:

    nano .env  # or use your preferred editor

    Minimum required configuration:

    OVERSEERR_URL=https://your-overseerr-url.com
OVERSEERR_API_KEY=your_api_key_here
IMDB_LISTS=top  # Start with just one list

  4. Deploy:

    docker-compose up -d

  5. Access the application:

Deployment Decision Guide

flowchart TD
    Start[Choose Deployment] --> UseCase{What's your goal?}
    
    UseCase -->|Production use| Prod[Production Setup]
    UseCase -->|Development| Dev[Development Setup]
    UseCase -->|Just testing| Test[Quick Test]
    
    Prod --> NeedDashboard{Need web<br/>dashboard?}
    NeedDashboard -->|Yes| FullDocker[Full Stack<br/>docker-compose.yml<br/>✓ Dashboard :3222<br/>✓ API :4222<br/>✓ Core Sync]
    NeedDashboard -->|No| CoreDocker[Core Only<br/>docker-compose.core.yml<br/>✓ API :4222<br/>✓ Core Sync]
    
    Dev --> LocalOrDocker{Docker or<br/>native?}
    LocalOrDocker -->|Docker| DevDocker[Local Build<br/>docker-compose.local.yml<br/>Build from source]
    LocalOrDocker -->|Native| ManualSetup[Manual Installation<br/>Python + Node.js<br/>Full control]
    
    Test --> QuickDocker[Core Deployment<br/>Fastest setup<br/>API access only]
    
    FullDocker --> DeployFull[docker-compose up -d]
    CoreDocker --> DeployCore[docker-compose -f<br/>docker-compose.core.yml up -d]
    DevDocker --> DeployDev[docker-compose -f<br/>docker-compose.local.yml up -d]
    QuickDocker --> DeployCore
    ManualSetup --> ManualSteps[Follow manual<br/>installation steps]
    
    DeployFull --> Success[✓ Deployment complete]
    DeployCore --> Success
    DeployDev --> Success
    ManualSteps --> Success
    
    Success --> Access{Can access?}
    Access -->|Yes| TestIt[Test sync operation]
    Access -->|No| TroubleshootInstall[See Troubleshooting]
    TestIt --> Working{Works?}
    Working -->|Yes| Done[Ready to use!]
    Working -->|No| TroubleshootInstall
    
    style Start fill:#4CAF50
    style Done fill:#4CAF50
    style FullDocker fill:#2196F3
    style CoreDocker fill:#2196F3
    style TroubleshootInstall fill:#FF9800

Docker Deployment Options

Production Deployment

Uses the pre-built image from GitHub Container Registry:

# Use the main docker-compose.yml file
docker-compose up -d

Local Development

Builds the image locally for development:

# Use the local development compose file
docker-compose -f docker-compose.local.yml up -d

Component-Specific Deployment

Deploy only specific components:

# Core sync functionality only (no web UI)
docker-compose -f docker-compose.core.yml up -d

# Full application (recommended)
docker-compose up -d

Note: With Nuxt 3's CORS-free architecture, you only need the standard docker-compose.yml for production deployments. The frontend's built-in Nitro proxy eliminates the need for complex CORS configurations.

Docker Configuration

Environment Variables

All configuration is done through environment variables in your .env file. See our Configuration Guide for complete details.

Volume Mapping

The default Docker setup includes these volume mappings:

volumes:
  - ./data:/usr/src/app/data          # Data persistence
  - ./.env:/usr/src/app/.env          # Configuration
  - ./logs:/var/log/supervisor        # Logs (optional)

Port Configuration

Default ports:

  • 3222: Web Dashboard (Nuxt 3 frontend)
  • 4222: API Backend (FastAPI)

To change ports, modify the docker-compose.yml:

services:
  listsync-full:
    ports:
      - "8080:3222"  # Web dashboard on port 8080
      - "8081:4222"  # API on port 8081

💻 Manual Installation

For advanced users who prefer manual installation or need custom configurations.

System Preparation

Ubuntu/Debian

# Update package list
sudo apt update

# Install Python and dependencies
sudo apt install python3 python3-pip python3-venv git

# Install Node.js (for web interface)
curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
sudo apt install nodejs

# Install Chrome (for Selenium)
wget -q -O - https://dl.google.com/linux/linux_signing_key.pub | sudo apt-key add -
sudo sh -c 'echo "deb [arch=amd64] http://dl.google.com/linux/chrome/deb/ stable main" >> /etc/apt/sources.list.d/google-chrome.list'
sudo apt update
sudo apt install google-chrome-stable

CentOS/RHEL/Fedora

# Install Python and dependencies
sudo dnf install python3 python3-pip git nodejs npm

# Install Chrome
sudo dnf install google-chrome-stable

macOS

# Install Homebrew if not installed
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install dependencies
brew install python3 node git
brew install --cask google-chrome

Backend Installation

  1. Clone and setup:

    git clone https://github.com/Woahai321/list-sync.git
cd list-sync

  2. Create Python virtual environment:

    python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

  3. Install Python dependencies:

    pip install -r requirements.txt

  4. Configure environment:

    cp envsample.txt .env
# Edit .env with your configuration

  5. Initialize database:

    python -m list_sync.database

Frontend Installation

  1. Navigate to frontend directory:

    cd listsync-nuxt

  2. Install Node.js dependencies:

    npm install

  3. Configure environment:

    # Nuxt 3 uses runtime config, main configuration is in .env at root
# API URL is configured via nuxt.config.ts proxy settings

  4. Build frontend:

    npm run build

Manual Service Setup

Using Systemd (Linux)

Create service files for automatic startup:

Backend Service (/etc/systemd/system/listsync-backend.service):

[Unit]
Description=ListSync Backend Service
After=network.target

[Service]
Type=simple
User=your-username
WorkingDirectory=/path/to/list-sync
Environment=PATH=/path/to/list-sync/venv/bin
ExecStart=/path/to/list-sync/venv/bin/python -m list_sync
Restart=always

[Install]
WantedBy=multi-user.target

Frontend Service (/etc/systemd/system/listsync-frontend.service):

[Unit]
Description=ListSync Frontend Service
After=network.target

[Service]
Type=simple
User=your-username
WorkingDirectory=/path/to/list-sync/listsync-nuxt
ExecStart=/usr/bin/npm start
Restart=always
Environment=NODE_ENV=production

[Install]
WantedBy=multi-user.target

Enable and start services:

sudo systemctl enable listsync-backend listsync-frontend
sudo systemctl start listsync-backend listsync-frontend

Using PM2 (Node.js Process Manager)

# Install PM2
npm install -g pm2

# Start backend
pm2 start "python -m list_sync" --name listsync-backend --cwd /path/to/list-sync

# Start frontend
pm2 start npm --name listsync-frontend --cwd /path/to/list-sync/listsync-nuxt -- start

# Save PM2 configuration
pm2 save
pm2 startup

🔧 Post-Installation Setup

Initial Configuration

  1. Test Overseerr connection:

    # Using curl
curl -H "X-Api-Key: your-api-key" http://your-overseerr-url/api/v1/status

  2. Add your first list:

  3. Configure sync interval:

    # Set in .env file
SYNC_INTERVAL=24  # Sync once per day

Optional Setup

Discord Notifications

  1. Create a Discord webhook in your server
  2. Add to your .env file: 
    DISCORD_WEBHOOK_URL=https://discord.com/api/webhooks/your-webhook-url

Reverse Proxy Setup

Example Nginx configuration:

server {
    listen 80;
    server_name your-domain.com;

    # Frontend
    location / {
        proxy_pass http://localhost:3222;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }

    # API
    location /api/ {
        proxy_pass http://localhost:4222;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

✅ Verification

Post-Installation Verification Workflow

flowchart TD
    Start[Installation Complete] --> Step1[Check container status]
    
    Step1 --> Docker{Using Docker?}
    Docker -->|Yes| CheckPS[docker-compose ps<br/>All services Up?]
    Docker -->|No| CheckProc[Check processes<br/>ps aux grep listsync]
    
    CheckPS --> AllUp{All up?}
    AllUp -->|No| StartServices[docker-compose up -d]
    AllUp -->|Yes| TestAPI[Test API Health]
    CheckProc --> TestAPI
    StartServices --> TestAPI
    
    TestAPI --> CURL1[curl localhost:4222/api/system/health]
    CURL1 --> APIWorks{API responds?}
    APIWorks -->|No| CheckAPIPort[Check port 4222<br/>Check firewall]
    APIWorks -->|Yes| TestDB[Test Database]
    
    TestDB --> CURL2[curl localhost:4222/api/lists]
    CURL2 --> DBWorks{Database OK?}
    DBWorks -->|No| CheckDBFile[Check ./data/list_sync.db<br/>exists & writable]
    DBWorks -->|Yes| TestDashboard[Test Dashboard]
    
    TestDashboard --> OpenBrowser[Open localhost:3222<br/>in browser]
    OpenBrowser --> DashWorks{Dashboard loads?}
    DashWorks -->|No| CheckFrontend[Check port 3222<br/>Check frontend logs]
    DashWorks -->|Yes| TestOverseerr[Test Overseerr Connection]
    
    TestOverseerr --> ConfigOverseerr[Check .env:<br/>OVERSEERR_URL<br/>OVERSEERR_API_KEY]
    ConfigOverseerr --> ConnTest{Connection OK<br/>in dashboard?}
    ConnTest -->|No| FixCreds[Update credentials<br/>Restart: docker-compose restart]
    ConnTest -->|Yes| AddList[Add Test List]
    
    AddList --> AddIMDB[Add IMDb Top list<br/>via dashboard or .env]
    AddIMDB --> TriggerSync[Trigger manual sync]
    TriggerSync --> SyncWorks{Sync completes<br/>successfully?}
    
    SyncWorks -->|No| CheckLogs[Check logs:<br/>docker-compose logs]
    SyncWorks -->|Yes| VerifyResults[Verify results<br/>in dashboard]
    
    VerifyResults --> ItemsReq{Items<br/>requested?}
    ItemsReq -->|Yes| AllGood[✓ Installation verified!<br/>Ready for production]
    ItemsReq -->|No| CheckWhy[Check why:<br/>- Already available?<br/>- Matching issues?]
    
    CheckAPIPort --> FixPort[Fix and retry]
    CheckDBFile --> FixDB[Fix and retry]
    CheckFrontend --> FixFrontend[Fix and retry]
    FixCreds --> TestOverseerr
    CheckLogs --> FixIssues[Fix issues]
    CheckWhy --> ReviewConfig[Review configuration]
    FixPort --> TestAPI
    FixDB --> TestDB
    FixFrontend --> TestDashboard
    FixIssues --> TriggerSync
    ReviewConfig --> Docs[Check documentation]
    
    style Start fill:#4CAF50
    style AllGood fill:#4CAF50
    style CheckAPIPort fill:#FF9800
    style CheckDBFile fill:#FF9800
    style CheckFrontend fill:#FF9800
    style CheckLogs fill:#FF9800

Health Checks

  1. Check system health:

    curl http://localhost:4222/api/system/health

  2. Verify database:

    curl http://localhost:4222/api/lists

  3. Test web interface: Open http://localhost:3222 in your browser

Manual Sync Test

  1. Trigger a manual sync:

    curl -X POST http://localhost:4222/api/sync/trigger

  2. Check sync results:

    curl http://localhost:4222/api/processed?limit=10

Log Verification

Check logs for any errors:

# Docker
docker-compose logs -f listsync-full

# Manual installation
tail -f data/list_sync.log

🔄 Updating

Docker Update

# Pull latest image
docker-compose pull

# Restart with new image
docker-compose up -d

Manual Update

# Backup your configuration
cp .env .env.backup

# Pull latest code
git pull origin main

# Update Python dependencies
source venv/bin/activate
pip install -r requirements.txt --upgrade

# Update frontend dependencies
cd listsync-nuxt
npm install
npm run build
cd ..

# Restart services
sudo systemctl restart listsync-backend listsync-frontend

🔧 Troubleshooting

Common Installation Issues

Docker Issues

Port already in use:

# Check what's using the port
sudo netstat -tlnp | grep :3222

# Change port in docker-compose.yml
ports:
  - "8080:3222"

Permission denied:

# Add user to docker group
sudo usermod -aG docker $USER
# Log out and back in

Container won't start:

# Check logs
docker-compose logs listsync-full

# Check container status
docker-compose ps

Manual Installation Issues

Python version too old:

# Check Python version
python3 --version

# Install newer Python (Ubuntu)
sudo apt install python3.9

Chrome/Selenium issues:

# Install Chrome dependencies
sudo apt install libxss1 libappindicator1 libindicator7

# Test Chrome headless
google-chrome --headless --no-sandbox --disable-gpu --dump-dom https://google.com

Node.js build failures:

# Clear npm cache
npm cache clean --force

# Delete node_modules and reinstall
rm -rf node_modules package-lock.json
npm install

Performance Issues

High memory usage:

  • Reduce TRAKT_SPECIAL_ITEMS_LIMIT
  • Increase SYNC_INTERVAL
  • Use fewer concurrent lists

Slow list fetching:

  • Check network connectivity
  • Verify list URLs are accessible
  • Enable debug logging to identify bottlenecks

Network Issues

Cannot connect to Overseerr:

# Test connectivity
curl -v http://your-overseerr-url/api/v1/status

# Check Docker networking
docker network ls
docker network inspect list-sync_default

CORS errors in web interface:

  • Verify CORS_ALLOWED_ORIGINS includes your domain
  • Check NEXT_PUBLIC_API_URL is correct

Getting Help

If you encounter issues not covered here:

  1. Check logs for detailed error messages
  2. Search existing issues on GitHub
  3. Create a new issue with:
    • Installation method (Docker/manual)
    • Operating system
    • Error messages
    • Configuration (sanitized)

For more troubleshooting help, see our Troubleshooting Guide.