Installation Guide

Detailed instructions for installing TheiaCast on various platforms

Table of Contents

System Requirements

Server Requirements

ComponentMinimumRecommended
CPU2 cores4 cores
RAM2 GB4 GB
Storage10 GB50+ GB (depending on content)
OSLinux, Windows, macOSLinux (Ubuntu 22.04 LTS)
Network100 Mbps1 Gbps
SoftwareDocker & Docker ComposeDocker & Docker Compose

Display Device Requirements

Windows Client

ComponentMinimumRecommended
CPUIntel Core i3 or equivalentIntel Core i5 or better
RAM2 GB4 GB
Storage5 GB10 GB
OSWindows 10Windows 11
NetworkStable connection to serverWired Ethernet

Raspberry Pi Client

ComponentMinimumRecommended
ModelRaspberry Pi 3B+Raspberry Pi 4 (4GB RAM)
Storage16 GB microSD32 GB microSD (Class 10)
OSRaspberry Pi OS LiteRaspberry Pi OS (64-bit)
NetworkWi-FiWired Ethernet

Server Installation

Docker Installation (Recommended)

Docker provides the easiest and most reliable installation method.

Step 1: Install Docker

On Ubuntu/Debian:

# Update package index
sudo apt update

# Install prerequisites
sudo apt install -y apt-transport-https ca-certificates curl software-properties-common

# Add Docker's official GPG key
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

# Add Docker repository
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Install Docker
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

# Add your user to docker group
sudo usermod -aG docker $USER

# Log out and back in for group changes to take effect

On Windows:

  1. Download Docker Desktop from https://www.docker.com/products/docker-desktop
  2. Run the installer
  3. Restart your computer
  4. Launch Docker Desktop

On macOS:

  1. Download Docker Desktop from https://www.docker.com/products/docker-desktop
  2. Drag Docker.app to Applications
  3. Launch Docker from Applications

Step 2: Verify Docker Installation

docker --version
docker compose version

You should see version numbers for both commands.

Step 3: Create TheiaCast Directory Structure

mkdir -p ~/theiacast
cd ~/theiacast
mkdir -p ssl-certs  # For optional SSL certificates

Step 4: Create docker-compose.yml

Create a file named docker-compose.yml with the following content:

services:
  postgres:
    image: postgres:15-alpine
    container_name: theiacast-postgres
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-postgres}
      POSTGRES_DB: theiacast
    volumes:
      - postgres_data:/var/lib/postgresql/data
    ports:
      - "5432:5432"
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres -d theiacast"]
      interval: 5s
      timeout: 5s
      retries: 5
      start_period: 10s
    restart: unless-stopped

  backend:
    image: ghcr.io/jimmyeao/theiacast-backend:latest
    container_name: theiacast-backend
    environment:
      - ConnectionStrings__Default=Host=postgres;Port=5432;Database=theiacast;Username=postgres;Password=${POSTGRES_PASSWORD:-postgres}
      - ASPNETCORE_ENVIRONMENT=Production
      - Jwt__Secret=${JWT_SECRET:-dev-secret-key}
      - BASE_URL=http://backend:8080
    ports:
      - "5001:8080"
    depends_on:
      postgres:
        condition: service_healthy
    volumes:
      - theiacast_media:/app/wwwroot
    restart: unless-stopped

  frontend:
    image: ghcr.io/jimmyeao/theiacast-frontend:latest
    container_name: theiacast-frontend
    ports:
      - "${HTTP_PORT:-80}:80"
      - "${HTTPS_PORT:-443}:443"
    volumes:
      - ${SSL_CERT_PATH:-./ssl-certs}:/etc/nginx/ssl:ro
    depends_on:
      - backend
    restart: unless-stopped

volumes:
  postgres_data:
  theiacast_media:

Step 5: Create Environment File (.env)

Create a .env file in the same directory:

# PostgreSQL password
POSTGRES_PASSWORD=YourSecurePassword123!

# JWT secret (minimum 32 characters)
JWT_SECRET=your-very-long-and-secure-secret-key-here-32-chars-minimum

# Optional: Custom ports
# HTTP_PORT=80
# HTTPS_PORT=443

# Optional: Custom SSL certificate path
# SSL_CERT_PATH=./ssl-certs

Important Security Notes:

  • Replace YourSecurePassword123! with a strong, unique password
  • Replace the JWT_SECRET with a long, random string (32+ characters)
  • Keep this file secure and never commit it to version control

Step 6: Start TheiaCast

sudo docker compose up -d

This command will:

  • Download the required Docker images (first time only)
  • Create and start all containers
  • Set up the database
  • Configure networking

Step 7: Verify Installation

Check that all containers are running:

sudo docker compose ps

You should see three containers (postgres, backend, frontend) with status "Up".

Check the logs:

# View all logs
sudo docker compose logs

# Follow backend logs
sudo docker compose logs -f backend

# Follow frontend logs
sudo docker compose logs -f frontend

Step 8: Access the Dashboard

Open your web browser and navigate to:

  • HTTP: http://localhost or http://your-server-ip
  • HTTPS: https://localhost or https://your-server-ip (if SSL configured)

First Login:

  1. Click "Register" (if shown) or use default credentials
  2. Create an admin account
  3. The first user becomes the administrator

Client Installation

Windows Client

The Windows installer provides an interactive setup that configures everything automatically.

Step 1: Register Device in Dashboard

  1. Open the TheiaCast web dashboard
  2. Navigate to "Devices"
  3. Click "+ Add Device"
  4. Enter a device name (e.g., "Reception Display")
  5. Enter a unique device ID (e.g., "reception-01")
  6. Click "Create"
  7. Copy the device token from the popup - you'll need this during installation

Step 2: Download and Run Installer

  1. Download the installer from our CDN
  2. Run the installer as Administrator
  3. When prompted, enter:
    • Server URL: http://your-server-ip:5001
    • Device ID: The device ID you created (e.g., "reception-01")
    • Device Token: The token you copied from the dashboard
  4. The installer will automatically install and start the client as a Windows service

Note: The installer handles all configuration automatically. You do not need to manually edit any files or install the service using PowerShell.

Step 3: Verify Connection

  1. Return to the TheiaCast web dashboard
  2. Go to "Devices"
  3. Your device should show "Online" with a green indicator
  4. If not online, check the service status in Windows Services or view logs in Event Viewer

Raspberry Pi Client

The automated installer script handles all dependencies, configuration, and service setup.

Step 1: Prepare Raspberry Pi

1. Install Raspberry Pi OS:

2. Update system:

sudo apt update
sudo apt upgrade -y

Step 2: Register Device in Dashboard

  1. Open the TheiaCast web dashboard on another computer
  2. Navigate to "Devices"
  3. Click "+ Add Device"
  4. Enter a device name (e.g., "Lobby Display")
  5. Enter a unique device ID (e.g., "lobby-pi-01")
  6. Click "Create"
  7. Copy the device token from the popup - you'll need this during installation

Step 3: Run Automated Installer

Run the following command on your Raspberry Pi. The installer will automatically detect your system, install all required dependencies (Node.js, Chromium, etc.), and configure the client.

curl -sSL https://gist.githubusercontent.com/jimmyeao/9a6922cdf1c69da92f1be9c7e3463052/raw/install-theiacast-client.sh | bash

During installation, you will be prompted to enter:

  • Server URL: http://your-server-ip:5001
  • Device ID: The device ID you created in the dashboard
  • Device Token: The token you copied from the dashboard

Note: The installer script handles everything automatically including:

  • Installing Node.js and other dependencies
  • Downloading and installing the TheiaCast client
  • Creating the configuration file
  • Setting up the systemd service
  • Starting the client automatically

Step 4: Verify Connection

  1. Check the service status:
    sudo systemctl status theiacast-client
  2. Return to the TheiaCast web dashboard
  3. Go to "Devices"
  4. Your device should show "Online" with a green indicator

View logs if needed:

# View recent logs
sudo journalctl -u theiacast-client -n 50

# Follow live logs
sudo journalctl -u theiacast-client -f

Post-Installation

SSL Certificate Setup (Optional)

For HTTPS access, you need SSL certificates.

Option 1: Self-Signed Certificate (Testing)

cd ~/theiacast/ssl-certs
openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
  -keyout key.pem -out cert.pem \
  -subj "/CN=localhost"

Option 2: Let's Encrypt (Production)

# Install certbot
sudo apt install certbot python3-certbot-nginx

# Obtain certificate
sudo certbot --nginx -d yourdomain.com

# Certificates will be in /etc/letsencrypt/live/yourdomain.com/
# Copy to TheiaCast directory
sudo cp /etc/letsencrypt/live/yourdomain.com/fullchain.pem ~/theiacast/ssl-certs/cert.pem
sudo cp /etc/letsencrypt/live/yourdomain.com/privkey.pem ~/theiacast/ssl-certs/key.pem
sudo chown $USER:$USER ~/theiacast/ssl-certs/*.pem

Restart frontend:

cd ~/theiacast
docker-compose restart frontend

Firewall Configuration

If you're using a firewall, open the required ports:

# Ubuntu/Debian with ufw
sudo ufw allow 80/tcp    # HTTP
sudo ufw allow 443/tcp   # HTTPS
sudo ufw allow 5001/tcp  # Backend API

# Or with firewalld (CentOS/RHEL)
sudo firewall-cmd --permanent --add-port=80/tcp
sudo firewall-cmd --permanent --add-port=443/tcp
sudo firewall-cmd --permanent --add-port=5001/tcp
sudo firewall-cmd --reload

Backup Configuration

Set up regular backups of your data:

#!/bin/bash
# backup-theiacast.sh

BACKUP_DIR="/backup/theiacast"
DATE=$(date +%Y%m%d_%H%M%S)

mkdir -p $BACKUP_DIR

# Backup database
docker exec theiacast-postgres pg_dump -U postgres theiacast > $BACKUP_DIR/db_$DATE.sql

# Backup media files
docker run --rm -v theiacast_media:/data -v $BACKUP_DIR:/backup alpine tar czf /backup/media_$DATE.tar.gz -C /data .

# Keep only last 7 days
find $BACKUP_DIR -name "*.sql" -mtime +7 -delete
find $BACKUP_DIR -name "*.tar.gz" -mtime +7 -delete

Make it executable and add to cron:

chmod +x backup-theiacast.sh
crontab -e
# Add: 0 2 * * * /path/to/backup-theiacast.sh

Troubleshooting

Server Issues

Containers won't start:

# Check logs
docker compose logs

# Check specific service
docker compose logs backend

# Restart all services
docker-compose restart

Database connection errors:

# Check PostgreSQL is running
docker-compose ps postgres

# Check database logs
docker compose logs postgres

# Reset database (WARNING: Deletes all data)
docker-compose down -v
docker-compose up -d

Port conflicts:

# Check what's using port 80
sudo lsof -i :80

# Change port in .env file
echo "HTTP_PORT=8080" >> .env
docker-compose up -d

Client Issues

Windows client won't start:

  1. Check Windows Event Viewer for errors
  2. Verify service is running in Windows Services
  3. Check firewall allows outbound connections
  4. Verify server URL is accessible: curl http://your-server:5001/health

Raspberry Pi client crashes:

# Check logs
sudo journalctl -u theiacast-client -n 100

# Check system resources
htop

# Increase memory (edit /boot/config.txt)
gpu_mem=256

# Restart
sudo reboot

Device shows offline:

  1. Check network connectivity: ping your-server-ip
  2. Verify device token is correct
  3. Check client logs for connection errors
  4. Verify firewall allows WebSocket connections (port 5001)

Common Issues

See the FAQ for more troubleshooting tips.

Next Steps

Need Help?

Need technical support? Visit our Contact page or email [email protected]