# SolTube Installation Guide

This guide covers two installation methods: local development server and Docker production deployment.

## Table of Contents

- [System Requirements](#system-requirements)
- [Development Server Setup](#development-server-setup)
- [Docker Deployment](#docker-deployment)
- [Environment Configuration](#environment-configuration)
- [Troubleshooting](#troubleshooting)

---

## System Requirements

### For Development Server

- **Node.js**: >= 20.x
- **pnpm**: >= 10.9
- **PostgreSQL**: >= 10.x
- **Redis**: >= 6.x
- **FFmpeg**: >= 4.3
- **Python**: >= 3.8
- **Operating System**: Linux, macOS, or WSL2 on Windows

### For Docker Deployment

- **Docker**: >= 20.10
- **Docker Compose**: >= 1.29
- **Disk Space**: >= 50GB (for video storage)
- **RAM**: >= 4GB recommended

---

## Development Server Setup

### 1. Prerequisites Installation

#### On Ubuntu/Debian:

```bash
# Install Node.js (if not already installed)
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# Install pnpm
npm install -g pnpm

# Docker
sudo apt-get install -y docker.io docker-compose-plugin
sudo systemctl enable docker
sudo systemctl start docker

# Install FFmpeg
sudo apt-get install -y ffmpeg

# Install build tools
sudo apt-get install -y build-essential python3 python3-pip
```

#### On macOS (using Homebrew):

```bash
# Install Node.js
brew install node

# Install pnpm
npm install -g pnpm

# Install FFmpeg
brew install ffmpeg

# Install Python
brew install python3

# Install Docker Desktop
# https://www.docker.com/products/docker-desktop/
```

#### On Windows:


Download and install Node.js (v20):

[https://nodejs.org/en/download](https://nodejs.org/en/download)

```bash
# Install pnpm
npm install -g pnpm

#Install Chocolatey (admin PowerShell):
Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))

#Then:
choco install ffmpeg -y
```

Download:
[https://www.python.org/downloads/windows/](https://www.python.org/downloads/windows/)

IMPORTANT:
✔ Check **Add Python to PATH**

---

### 2. Start PostgreSQL + Redis using Docker

Create a directory for local containers:
```bash
mkdir -p dev-services
cd dev-services
```

---
Create docker-compose.yml
```yaml
version: "3.9"

services:

  postgres:
    image: postgres:17-alpine
    container_name: soltube-postgres
    restart: unless-stopped
    environment:
      POSTGRES_USER: peertube
      POSTGRES_PASSWORD: peertube
      POSTGRES_DB: peertube_dev
    ports:
      - "5432:5432"
    volumes:
      - soltube_pgdata:/var/lib/postgresql/data

  redis:
    image: redis:8-alpine
    container_name: soltube-redis
    restart: unless-stopped
    ports:
      - "6379:6379"
    volumes:
      - soltube_redisdata:/data

volumes:
  soltube_pgdata:
  soltube_redisdata:
```

------
Start services
```bash
docker compose up -d
```

Verify:
```bash
docker ps

# You should see:
# peertube-postgres
# peertube-redis
```

### 3. Initialize PostgreSQL extensions

Run:
```bash
docker exec -it peertube-postgres psql -U peertube -d peertube_dev
```

Inside psql:
```bash
CREATE EXTENSION pg_trgm;
CREATE EXTENSION unaccent;
\dx
\q
```

### 4. Clone and Install Dependencies

```bash
# Clone the repository
git clone https://gitea.hamlyn.app/Solace/soltube-peertube.git
cd soltube-peertube

# Install dependencies
pnpm install --frozen-lockfile

# Build the server
pnpm run build:server
```

### 5. Configure Environment

```bash
# Generate a secret key
openssl rand -hex 32
# Copy the output for later use

# Create development config
cp config/default.yaml config/dev.yaml

# Edit the dev config
nano config/dev.yaml
```

Add or update the following in `config/dev.yaml`:

```yaml
listen:
  hostname: '127.0.0.1'
  port: 9000

webserver:
  https: false
  hostname: 'localhost'
  port: 9000

secrets:
  peertube: '<YOUR_GENERATED_SECRET_HERE>'

database:
  hostname: 'localhost'
  port: 5432
  username: 'peertube'
  password: '<YOUR_DATABASE_PASSWORD>'
  pool:
    min: 2
    max: 20

redis:
  hostname: 'localhost'
  port: 6379

log:
  level: 'debug'

user:
  video_quota: -1
```

### 6. Run Development Server

```bash
# Start the development server with hot reload
pnpm run dev:server
```

The server will start at `http://localhost:9000`

**Development Credentials:**
- Username: `root`
- Password: `test`

### 7. Access the Application

- **API**: http://localhost:9000/api/v1
- **Web UI**: http://localhost:3000 (if running full dev stack)

### Optional: Run Full Development Stack

If you want to also run the client development server:

```bash
# Start both server and client
pnpm run dev
```

This will run:
- Backend server on port 9000
- Frontend on port 3000

---

## Docker Deployment

### 1. Prepare Docker Environment

```bash
cd PeerTube/support/docker/production

# Create required directories
mkdir -p docker-volume/data
mkdir -p docker-volume/config
mkdir -p docker-volume/db
mkdir -p docker-volume/redis
mkdir -p docker-volume/nginx
```

### 2. Configure Environment Variables

```bash
# Copy the environment template
cp .env.example .env

# Edit the .env file with your settings
nano .env
```

**Essential variables to configure:**

```bash
# Database
POSTGRES_DB=peertube
POSTGRES_USER=peertube
POSTGRES_PASSWORD=<generate_strong_password>
POSTGRES_INITDB_ARGS=-c shared_preload_libraries=pg_stat_statements

# PeerTube
PEERTUBE_DB_USERNAME=peertube
PEERTUBE_DB_PASSWORD=<same_as_postgres_password>
PEERTUBE_DB_HOSTNAME=postgres
PEERTUBE_DB_PORT=5432
PEERTUBE_DB_SUFFIX=

# Secrets
PEERTUBE_SECRET=<generate_with_openssl_rand_-hex_32>

# WebServer
PEERTUBE_WEBSERVER_HOSTNAME=<your-domain.com>
PEERTUBE_WEBSERVER_HTTPS=true
PEERTUBE_WEBSERVER_PORT=443

# Email (optional but recommended)
PEERTUBE_SMTP_HOSTNAME=<your-smtp-server>
PEERTUBE_SMTP_PORT=587
PEERTUBE_SMTP_USERNAME=<your-email>
PEERTUBE_SMTP_PASSWORD=<your-password>
PEERTUBE_SMTP_FROM_ADDRESS=noreply@<your-domain.com>

# Admin user
PEERTUBE_ADMIN_EMAIL=admin@<your-domain.com>
```

### 3. Network Configuration

Create or edit docker-compose.yml to match your requirements:

```bash
# Uncomment and configure the nginx/webserver section for production
# Update the peertube service to use your domain
# Configure SSL certificates if using HTTPS
```

### 4. Build and Start Containers

```bash
# Option A: Using pre-built images (recommended for production)
docker-compose pull
docker-compose up -d

# Option B: Building from source
docker-compose build --build-arg ALREADY_BUILT=0
docker-compose up -d

# Verify all services are running
docker-compose ps
```

### 5. Initial Setup

```bash
# Wait for containers to be healthy (check docker-compose logs)
docker-compose logs -f peertube

# The application should be accessible at your configured domain

# You can also access it directly via port 9000 during setup:
# http://<your-server-ip>:9000
```

### 6. Common Docker Operations

```bash
# View logs
docker-compose logs -f peertube
docker-compose logs -f postgres
docker-compose logs -f redis

# Stop all services
docker-compose down

# Stop and remove all data (⚠️ careful - this deletes everything)
docker-compose down -v

# Restart a specific service
docker-compose restart peertube

# Execute a command in the container
docker-compose exec peertube npm run create-import-video-file-job -- --help

# Backup database
docker-compose exec postgres pg_dump -U peertube peertube > backup.sql

# Restore database
docker-compose exec -T postgres psql -U peertube peertube < backup.sql

# Update to latest image
docker-compose pull peertube
docker-compose up -d peertube
```

---

## Environment Configuration

### Application Configuration Files

Configuration files are located in `/config` directory inside the container:

- **Main Config**: `/app/config/default.yaml` - Default settings (don't edit)
- **Custom Config**: `/config/production.yaml` - Your custom configuration
- **Docker Config**: `/app/support/docker/production/config/` - Docker-specific defaults

### Key Configuration Options

**Video Upload Settings:**
```yaml
upload:
  rate_limit_bytes_per_second: -1  # -1 means unlimited
  max_file_size: 500GB

transcoding:
  enabled: true
  allow_additional_extensions: true
  allow_audio_files: true
  threads: 0  # 0 = auto-detect
```

**Federation:**
```yaml
federation:
  videos:
    federate_unlisted: true
  max_followers: -1
```

**Live Streaming:**
```yaml
live:
  enabled: true
  allow_replay: true
  max_duration: 0  # 0 = unlimited
  max_user_lives: 3
```

---

## Troubleshooting

### Development Server Issues

**Port already in use:**
```bash
# Find process using port 9000
lsof -i :9000
# Kill the process
kill -9 <PID>
```

**PostgreSQL connection failed:**
```bash
# Check PostgreSQL is running
sudo systemctl status postgresql

# Check database exists
sudo -u postgres psql -l | grep peertube

# Check extensions
sudo -u postgres psql -d peertube_dev -c "\dx"
```

**Redis connection failed:**
```bash
# Check Redis is running
sudo systemctl status redis-server

# Test Redis connection
redis-cli ping
```

**Build errors:**
```bash
# Clear node_modules and reinstall
rm -rf node_modules pnpm-lock.yaml
pnpm install --frozen-lockfile

# Rebuild
pnpm run build:server
```

### Docker Deployment Issues

**Containers not starting:**
```bash
# Check logs for errors
docker-compose logs peertube
docker-compose logs postgres
docker-compose logs redis

# Verify environment variables
cat .env

# Restart services
docker-compose restart
```

**Database permission errors:**
```bash
# Fix directory permissions
sudo chown -R $(id -u):$(id -g) docker-volume/

# Restart database
docker-compose restart postgres
```

**Port conflicts:**
```bash
# Check if ports are in use
netstat -tlnp | grep 9000
netstat -tlnp | grep 5432
netstat -tlnp | grep 6379

# Change ports in docker-compose.yml and .env
```

**Memory issues:**
```bash
# Check Docker memory limits
docker stats

# Increase Docker memory in Docker Desktop Settings
# Or adjust container memory limits in docker-compose.yml
```

**Certificate renewal failing:**
```bash
# Check Certbot logs
docker-compose logs certbot

# Manual renewal
docker-compose exec certbot certbot renew --force-renewal

# Verify certificate
docker-compose exec webserver nginx -t
```

---

## Next Steps

### After Installation

1. **Admin Panel**: Access `/admin` to configure instance settings
2. **User Management**: Create additional user accounts
3. **Plugin Installation**: Install plugins from the admin panel
4. **Custom Branding**: Customize theme and instance name
5. **Federation**: Configure federation settings if needed

### Maintenance

- **Regular Backups**: Set up automated PostgreSQL backups
- **Log Monitoring**: Monitor application and system logs
- **Updates**: Keep Docker images updated
- **Disk Space**: Monitor storage for videos and uploads
- **Database Maintenance**: Run `VACUUM` and `ANALYZE` periodically

### Security

- Change default admin password immediately
- Configure firewall rules
- Use HTTPS in production
- Keep Node.js and dependencies updated
- Review security settings in admin panel
- Configure rate limiting appropriately