Installation Guide

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

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)

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

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

Step 1: Prepare Raspberry Pi

1. Install Raspberry Pi OS:

• Download Raspberry Pi Imager: https://www.raspberrypi.com/software/
• Flash Raspberry Pi OS (64-bit recommended) to microSD card
• Boot the Raspberry Pi and complete initial setup

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.

sudo curl -sSL https://gist.githubusercontent.com/jimmyeao/9a6922cdf1c69da92f1be9c7e3463052/raw/install-theiacast-client.sh | sudo 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

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

Device status

The device card also shows:

• IP address - the device's IP address
• Seen from - the connection IP as observed by the server
• OS / version - the operating system running on the device
• Client version - the version of the TheiaCast client
• Screen resolution - the resolution of the attached display
• Last seen - when the device last checked in

Service Management

On Raspberry Pi the client runs as a system service, so these commands require sudo.

# Check status
sudo systemctl status theiacast-client

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

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

# Restart the client app
sudo systemctl restart theiacast-client

# Stop the client
sudo systemctl stop theiacast-client

Updating the Client

To update, re-run the same install one-liner. It preserves your existing configuration - press Enter at each prompt to keep the current Server URL, Device ID, and Device Token. Upgrades from older versions are migrated automatically.

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

Device Controls

The device card in the dashboard has two power actions:

• Restart client software (↻) - relaunches the TheiaCast client app only. It takes a few seconds and does not reboot the operating system. Use this for a stuck client, or to clear a browser memory leak.
• Reboot device (OS) (⏻) - reboots the whole Raspberry Pi. The device will be offline for roughly 1-2 minutes.