577 lines
11 KiB
Markdown
577 lines
11 KiB
Markdown
# 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
|
|
|