Skip to content

Installation

Jump to bottom
Suresh S edited this page Nov 20, 2025 · 7 revisions

CineSync Installation Guide

CineSync offers multiple installation methods to suit different environments and use cases. Choose the method that best fits your setup.

System Requirements

Minimum Requirements

  • CPU: 1 core (2+ cores recommended for large libraries)
  • RAM: 1GB (2GB+ recommended for large libraries)
  • OS: Linux, Windows, macOS, or Docker-compatible system

Software Requirements

  • Docker (recommended) or Python 3.8+
  • Git (for manual installation)
  • TMDb API Key (free registration required)

Network Requirements

  • Port 5173: Web interface (configurable)
  • Port 8082: API server and WebDAV (configurable)

Docker Installation (Recommended)

Docker provides the easiest and most reliable way to run CineSync with all dependencies included.

Quick Start with Docker

# Pull the latest CineSync image
docker pull sureshfizzy/cinesync:latest

# Copy and configure environment file
cp .env.example .env

# Run CineSync with Docker
docker run -d \
  --name cinesync \
  --restart unless-stopped \
  -p 5173:5173 \
  -p 8082:8082 \
  -v /path/to/your/media:/media \
  -v $(pwd)/db:/app/db \
  sureshfizzy/cinesync:latest

Docker Compose Installation (Recommended)

Create a docker-compose.yml file for easier management:

services:
  cinesync:
    image: sureshfizzy/cinesync:latest
    container_name: cinesync
    restart: unless-stopped
    ports:
      - "5173:5173"  # Web Interface
      - "8082:8082"  # API & WebDAV
    environment:
      - PUID=1000    # Set to your user ID
      - PGID=1000    # Set to your group ID
      - TZ=UTC       # Set your timezone
    volumes:
      # Configuration and database
      - ./db:/app/db
      - /home:/home
      - /mnt:/mnt

User Permissions Setup

Find your user and group IDs:

id $(whoami)
# Output: uid=1000(username) gid=1000(groupname) groups=...

Update the PUID and PGID values in your docker-compose.yml accordingly.

Running with Docker Compose

# Start CineSync
docker compose up -d

# View logs
docker compose logs -f cinesync

# Access the web interface
# http://localhost:5173 (Web UI)
# http://localhost:8082 (API/WebDAV)

Docker Management Commands

# Update to latest version
docker compose pull
docker compose up -d

# Stop CineSync
docker compose down

# Restart CineSync
docker compose restart

# View real-time logs
docker compose logs -f

# Check container status
docker compose ps

# Access container shell (for debugging)
docker compose exec -it cinesync /bin/bash

Environment Configuration

Create and configure your .env file:

# Create the db folder if it doesn't exist
mkdir -p db && cd db

# Copy example configuration
curl -o .env https://raw.githubusercontent.com/sureshfizzy/CineSync/main/.env.example

# Edit configuration
nano .env

Essential settings to configure:

# Required settings
SOURCE_DIR=/path/to/your/source/media
DESTINATION_DIR=/path/to/your/organized/library
TMDB_API_KEY=your-tmdb-api-key-here

# Web interface settings
CINESYNC_IP=0.0.0.0
CINESYNC_API_PORT=8082
CINESYNC_UI_PORT=5173
CINESYNC_AUTH_ENABLED=true
CINESYNC_USERNAME=admin
CINESYNC_PASSWORD=change-this-password

# Organization settings
CINESYNC_LAYOUT=true
4K_SEPARATION=true
ANIME_SEPARATION=true
AUTO_PROCESSING_ENABLED=true

Supported Architectures

CineSync Docker images support multiple architectures:

  • amd64 (x86_64) - Intel/AMD 64-bit
  • arm64 (aarch64) - ARM 64-bit (Raspberry Pi 4+, Apple Silicon)
  • armv7 - ARM 32-bit (Raspberry Pi 3+)

Manual Installation

For users who prefer to run CineSync directly on their system without Docker.

Prerequisites

Linux/macOS

# Ubuntu/Debian
sudo apt update
sudo apt install python3 python3-pip nodejs npm golang git

# CentOS/RHEL/Fedora
sudo dnf install python3 python3-pip nodejs npm golang git

# macOS (with Homebrew)
brew install python3 node go git

Note: Ensure you have Python 3.8+ (3.13+ recommended), Node.js 18+, and Go 1.19+ installed.

Windows

  1. Python 3.13: Download and install from python.org
  2. Node.js 22: Download and install from nodejs.org
  3. Go Language: Download and install from golang.org
  4. Git: Download and install from git-scm.com
  5. Enable Developer Mode: Required for symlink creation (see instructions below)
  6. Ensure all software is added to your system PATH during installation

Windows Developer Mode Setup

For Windows users, you must enable Developer Mode to allow symlink creation:

  1. Open Settings (Windows + I)
  2. Go to Update & Security → For developers
  3. Enable Developer Mode
  4. Restart your computer when prompted

Windows Developer Mode

Installation Steps

  1. Clone the Repository

    git clone https://github.com/sureshfizzy/CineSync.git
cd CineSync

  2. Install Python Dependencies

    pip install -r requirements.txt

  3. Configure Environment

    # Copy example configuration
cp .env.example db/.env

# Edit configuration file with your preferred editor
nano .env  # Linux/macOS
notepad .env  # Windows

  4. Essential Configuration Update these required settings in .env:

    SOURCE_DIR=/path/to/your/source/media
DESTINATION_DIR=/path/to/your/organized/library
TMDB_API_KEY=your-tmdb-api-key-here

  5. Build Web Interface

    # Navigate to WebDavHub scripts directory
cd WebDavHub/scripts

# Linux/macOS
python3 build-prod.py

# Windows
python build-prod.py

  6. Run CineSync

    Web Interface (Recommended):

    # Start the production server
# Linux/macOS
python3 start-prod.py

# Windows
python start-prod.py

  7. Access CineSync

    Once the web interface is running, access CineSync at:

    • Web UI: http://localhost:5173
    • API/WebDAV: http://localhost:8082
    • Default Login: admin / admin

Post-Installation Setup

After installation, access the web interface and complete the setup:

  1. Access Web Interface

    • Open your browser and go to http://localhost:5173
    • Default login: admin / admin

  2. Initial Configuration

    • Verify source and destination directories
    • Configure TMDb API key
    • Set up content organization preferences
    • Enable auto-processing if desired

  3. Test Installation

    • Run a test scan on a small directory
    • Verify symlink creation works correctly
    • Check web interface functionality
    • Test WebDAV access if needed

For Windows (Optional: Only if running through Git Bash):

  1. Install Python: Install Python from the official website: Python.org. Make sure to add Python to your system PATH during installation.

  2. Install Git Bash: Install Git Bash from Git for Windows. During installation, enable the symbolic links checkbox.

Git Bash

Enabling symbolic links is important for certain operations, so ensure that the checkbox for symbolic links is checked during installation.

  1. Edit .bashrc (Windows): Open Git Bash as an administrator and edit the .bashrc file. You can use the nano editor to open the file by running the following command:

    nano /etc/bash.bashrc

    Add the following line at the bottom of the file:

    export MSYS=winsymlinks:nativestrict

    Save the changes by pressing Ctrl + O, then press Enter to confirm. Exit the editor by pressing Ctrl + X.

    Important: Ensure that the export MSYS=winsymlinks:nativestrict line is added to the .bashrc file. This configuration is essential to ensure that symbolic links are handled correctly on Windows when using Git Bash. Without this setting, CineSync may copy files instead of creating symbolic links, leading to undesired behavior.

  2. Enable Windows Developer Mode:

    Enabling Developer Mode grants your system additional privileges necessary for certain operations, helping to prevent permission-related errors during development.

    To avoid "Operation not permitted" errors during symlink process, it's essential to enable Windows Developer Mode. Follow these steps:

    • Open Settings.
    • Go to Update & Security.
    • Click on For developers.
    • Enable the Developer mode option.
    • Restart the PC

    Developer Mode

Getting TMDb API Key

CineSync requires a TMDb API key for metadata lookup. Here's how to get one:

Step-by-Step Guide

  1. Create TMDb Account

    • Visit themoviedb.org
    • Click "Join TMDb" and create a free account
    • Verify your email address

  2. Request API Access

    • Log in to your TMDb account
    • Go to Settings → API
    • Click "Create" under "Request an API Key"
    • Select "Developer" option

  3. Fill Application Details

    • Application Name: CineSync (or your preferred name)
    • Application URL: http://localhost:5173 (or your domain)
    • Application Summary: Personal media library organization
    • Accept the terms of use

  4. Get Your API Key

    • Once approved, copy your API key (v3 auth)
    • Add it to your .env file: TMDB_API_KEY=your-key-here

API Key Security

  • Keep your API key private and secure
  • Don't share it publicly or commit it to version control
  • Use environment variables for production deployments

Troubleshooting

Common Installation Issues

Docker Issues

# Permission denied
sudo usermod -aG docker $USER
# Log out and back in

# Port already in use
docker compose down
sudo netstat -tulpn | grep :5173

# Container won't start
docker compose logs cinesync

Python Installation Issues

# Module not found
pip3 install --upgrade pip
pip3 install -r requirements.txt

# Permission errors (Linux/macOS)
pip3 install --user -r requirements.txt

# Python version issues
python3 --version  # Should be 3.8+

Configuration Issues

  • Invalid paths: Ensure source and destination directories exist and are accessible
  • TMDb API errors: Verify your API key is correct and active
  • Permission errors: Check file/directory permissions for read/write access

Web Interface Issues

  • Can't access web interface: Check if ports 5173 and 8082 are available
  • Authentication problems: Verify username/password in .env file
  • API connection errors: Ensure API server is running on correct port

Getting Help

Log Files

# Docker logs
docker compose logs -f cinesync

# Manual installation logs
tail -f logs/cinesync.log

Debug Mode

# Enable debug logging
LOG_LEVEL=DEBUG

Support Resources

Performance Optimization

System Optimization

# For large libraries
MAX_PROCESSES=15
DB_THROTTLE_RATE=50.0
DB_BATCH_SIZE=2000
DB_MAX_WORKERS=30

# For small systems
MAX_PROCESSES=10
DB_THROTTLE_RATE=10.0
DB_BATCH_SIZE=500
DB_MAX_WORKERS=20

## Next Steps

1. [Configuration Guide](Configuration) - Detailed configuration options
2. [Web Interface](Web-Interface) - Using the web dashboard
3. [Docker Volumes](Volumes) - Docker configuration for media servers

Clone this wiki locally
⚡