Installation Guide

Complete guide for installing and configuring DesterLib.

Just want to get started quickly?

See the Quick Start Guide for a 5-minute setup!

System Requirements

Server

• CPU: 2 cores minimum
• RAM: 2GB minimum
• Storage: Your media collection size + 10GB
• OS: Linux, macOS, or Windows
• Docker: Version 20.10 or higher

Client Devices

• Android 5.0+, iOS 12+, macOS 10.15+, Windows 10+, or Linux

Server Installation

Option 1: Quick Setup (Recommended)

Perfect for: End users who want it working fast

macOS/Linux:

curl -fsSL https://raw.githubusercontent.com/DesterLib/desterlib/main/scripts/setup/unix.sh | bash

Windows (PowerShell):

iwr -useb https://raw.githubusercontent.com/DesterLib/desterlib/main/scripts/setup/windows.ps1 | iex

The setup script will:

1. Check Docker installation
2. Clone the repository
3. Prompt for configuration (media path, port, database)
4. Set up and start DesterLib

Your server will be installed in ~/.desterlib/ (or a custom location you choose) and started automatically.

Verify it’s working:

curl http://localhost:3001/health
# Should return: {"status":"ok",...}

Option 2: Manual Setup (For Developers)

Perfect for: Contributors and advanced users

# 1. Clone the repository
git clone https://github.com/DesterLib/desterlib.git
cd desterlib

# 2. Start with Docker Compose
docker compose up -d
# Note: If you have older Docker, use: docker-compose up -d

# 3. Access at http://localhost:3001

Optional: Customize with .env file in apps/api/:

DATABASE_URL=postgresql://postgres:postgres@postgres:5432/desterlib
NODE_ENV=production
PORT=3001

Client Installation

Pre-built Apps

📥 Download from Releases

Alpha Software

DesterLib is in alpha. Expect bugs and frequent updates!

Available platforms:

Platform	File
Android Phone/Tablet	Dester-*-Android.apk
macOS	Dester-*-macOS.zip
Windows	Dester-*-Windows.zip
Linux	Dester-*-Linux.tar.gz
iOS	Dester-*-iOS.ipa

After installing:

1. Open the app
2. Enter: http://YOUR_SERVER_IP:3001
3. Scan Library from Settings
4. Start watching!

Build from Source

For iOS or if you prefer building yourself:

Android

1. Clone the Flutter app repository:

   git clone https://github.com/DesterLib/desterlib-flutter.git
   cd desterlib-flutter

2. Install Flutter dependencies:

   flutter pub get

3. Build and install APK:

   build/app/outputs/flutter-apk/app-release.apk

   # Build APK
   flutter build apk --release
   
   # Transfer to your Android device and install
   
   # Or install directly if device is connected:
   flutter install

iOS

1. Prerequisites:

   • macOS with Xcode installed
   • Apple Developer account (for device deployment)

2. Clone and setup:

   git clone https://github.com/DesterLib/Dester-Flutter.git
   cd Dester-Flutter
   flutter pub get

3. Install CocoaPods dependencies:

   cd ios
   pod install
   cd ..

4. Open in Xcode:

   open ios/Runner.xcworkspace

5. Build and run:

   • Select your device or simulator in Xcode
   • Click Run (▶️) button
   • Or use: flutter run

Desktop Platforms

macOS:

git clone https://github.com/DesterLib/desterlib-flutter.git
cd desterlib-flutter
flutter pub get
flutter build macos --release

# App will be at: build/macos/Build/Products/Release/Dester.app

Linux:

# Install dependencies first
sudo apt-get install clang cmake ninja-build pkg-config libgtk-3-dev liblzma-dev libmpv-dev mpv

git clone https://github.com/DesterLib/Dester-Flutter.git
cd Dester-Flutter
flutter pub get
flutter build linux --release

# Binary will be at: build/linux/x64/release/bundle/

Windows:

git clone https://github.com/DesterLib/desterlib-flutter.git
cd desterlib-flutter
flutter pub get
flutter build windows --release

# App will be at: build/windows/x64/runner/Release/

Managing Your Server

Commands depend on your installation method:

If installed via setup script:

cd ~/.desterlib  # or your custom installation directory

docker compose ps       # View status
docker compose logs -f  # View logs
docker compose restart  # Restart
docker compose down     # Stop
docker compose pull && docker compose up -d  # Update

Docker Compose Command

Modern Docker uses docker compose (space). Older installations may use docker-compose (hyphen). Both work the same way.

If installed via Git:

cd desterlib

docker ps               # View status
docker compose logs -f  # View logs
docker compose restart  # Restart
docker compose down     # Stop
git pull && docker compose up -d --build  # Update

Development Setup

For contributors who want to modify the code:

# 1. Clone and install
git clone https://github.com/DesterLib/desterlib.git
cd desterlib
pnpm install

# 2. Start test database
docker compose -f docker-compose.test.yml up -d

# 3. Configure .env in apps/api/
DATABASE_URL=postgresql://postgres:postgres@localhost:5433/desterlib_test
NODE_ENV=development
PORT=3001

# 4. Run the API
cd apps/api
pnpm db:generate
pnpm db:push
pnpm dev

See Contributing Guide for more details.

Remote Access

To access from outside your network:

Option 1: Port Forwarding

• Forward port 3001 on your router
• Use dynamic DNS (e.g., DuckDNS, No-IP)

Option 2: Tunneling (Easier)

• Tailscale (recommended)
• ngrok: ngrok http 3001
• Cloudflare Tunnel

Security

If exposing to internet, use HTTPS and enable authentication!

Maintenance

Database Backup

docker exec -t desterlib-postgres pg_dump -U desterlib desterlib > backup.sql

Database Restore

cat backup.sql | docker exec -i desterlib-postgres psql -U desterlib desterlib

Uninstall

Setup script installation:

cd ~/.desterlib && docker compose down -v
rm -rf ~/.desterlib

Git installation:

cd desterlib && docker compose down -v
cd .. && rm -rf desterlib

Troubleshooting

Server Won’t Start

Port already in use:

# Find and kill process using port 3001
lsof -ti:3001 | xargs kill -9  # Mac/Linux
netstat -ano | findstr :3001   # Windows

Check logs:

cd ~/.desterlib  # or your install directory
docker compose logs -f

Full reset:

cd ~/.desterlib
docker compose down -v
docker compose up -d

Can’t Connect from Client

Checklist:

1. Server running? → docker ps | grep desterlib
2. Test connection → curl http://SERVER_IP:3001/health
3. Find server IP:
   • macOS/Linux: ifconfig | grep "inet "
   • Windows: ipconfig
4. Check firewall → Allow port 3001
5. Use IP not hostname → 192.168.1.100:3001 not my-computer:3001

Movies Not Showing

Steps:

1. Scan library → Settings → Library Management → Scan Library
2. Check media mounted → Verify path in ~/.desterlib/docker-compose.yml
3. File naming → Use Movie Name (2023).mp4 format
4. Check logs → docker compose logs -f api for errors
5. Verify TMDB key → Set in app Settings if not already configured

Build Issues (Development)

# API
pnpm clean && rm -rf node_modules && pnpm install

# Flutter
flutter clean && flutter pub get

Need Help?

• 📖 Quick Start - 5-minute setup guide
• 🔧 API Documentation - Full API reference
• 💬 GitHub Discussions - Ask questions
• 🐛 Report Issues - Bug reports