Installation - sureshfizzy/CineSync GitHub Wiki
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 $(pwd)/.env:/app/.env \
-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
- ./.env:/app/.env
- ./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:
# 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
- Python 3.13: Download and install from python.org
- Node.js 22: Download and install from nodejs.org
- Go Language: Download and install from golang.org
- Git: Download and install from git-scm.com
- Enable Developer Mode: Required for symlink creation (see instructions below)
- 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:
- Open Settings (Windows + I)
- Go to Update & Security → For developers
- Enable Developer Mode
- Restart your computer when prompted
Installation Steps
-
Clone the Repository
git clone https://github.com/sureshfizzy/CineSync.git cd CineSync
-
Install Python Dependencies
pip install -r requirements.txt
-
Configure Environment
# Copy example configuration cp .env.example .env # Edit configuration file with your preferred editor nano .env # Linux/macOS notepad .env # Windows
-
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
-
Build Web Interface
# Navigate to WebDavHub scripts directory cd WebDavHub/scripts # Linux/macOS python3 build-prod.py # Windows python build-prod.py
-
Run CineSync
Web Interface (Recommended):
# Start the production server # Linux/macOS python3 start-prod.py # Windows python start-prod.py
-
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
- Web UI:
Post-Installation Setup
After installation, access the web interface and complete the setup:
-
Access Web Interface
- Open your browser and go to
http://localhost:5173
- Default login:
admin
/admin
- Open your browser and go to
-
Initial Configuration
- Verify source and destination directories
- Configure TMDb API key
- Set up content organization preferences
- Enable auto-processing if desired
-
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):
-
Install Python: Install Python from the official website: Python.org. Make sure to add Python to your system PATH during installation.
-
Install Git Bash: Install Git Bash from Git for Windows. During installation, enable the symbolic links checkbox.
Enabling symbolic links is important for certain operations, so ensure that the checkbox for symbolic links is checked during installation.
-
Edit
.bashrc
(Windows): Open Git Bash as an administrator and edit the.bashrc
file. You can use thenano
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 pressEnter
to confirm. Exit the editor by pressingCtrl + 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. -
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
Getting TMDb API Key
CineSync requires a TMDb API key for metadata lookup. Here's how to get one:
Step-by-Step Guide
-
Create TMDb Account
- Visit themoviedb.org
- Click "Join TMDb" and create a free account
- Verify your email address
-
Request API Access
- Log in to your TMDb account
- Go to Settings → API
- Click "Create" under "Request an API Key"
- Select "Developer" option
-
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
-
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
- GitHub Issues: Report bugs and feature requests
- Discord Community: Join the discussion
- Wiki Documentation: Comprehensive guides
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