SolTube/INSTALLATION.md

SolTube Installation Guide

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

Table of Contents

• System Requirements
• Development Server Setup
• Docker Deployment
• Environment Configuration
• 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:

# 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):

# 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

# 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/

IMPORTANT: ✔ Check Add Python to PATH

---

2. Start PostgreSQL + Redis using Docker

Create a directory for local containers:

mkdir -p dev-services
cd dev-services

---

Create docker-compose.yml

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

docker compose up -d

Verify:

docker ps

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

3. Initialize PostgreSQL extensions

Run:

docker exec -it peertube-postgres psql -U peertube -d peertube_dev

Inside psql:

CREATE EXTENSION pg_trgm;
CREATE EXTENSION unaccent;
\dx
\q

4. Clone and Install Dependencies

# 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

# 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:

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

# 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:

# 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

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

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

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

Essential variables to configure:

# 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:

# 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

# 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

# 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

# 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:

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:

federation:
  videos:
    federate_unlisted: true
  max_followers: -1

Live Streaming:

live:
  enabled: true
  allow_replay: true
  max_duration: 0  # 0 = unlimited
  max_user_lives: 3

---

Troubleshooting

Development Server Issues

Port already in use:

# Find process using port 9000
lsof -i :9000
# Kill the process
kill -9 <PID>

PostgreSQL connection failed:

# 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:

# Check Redis is running
sudo systemctl status redis-server

# Test Redis connection
redis-cli ping

Build errors:

# 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:

# 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:

# Fix directory permissions
sudo chown -R $(id -u):$(id -g) docker-volume/

# Restart database
docker-compose restart postgres

Port conflicts:

# 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:

# 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:

# 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