Quick Start Guide

Get TheiaCast up and running in just 5 minutes!

Prerequisites

  • Docker and Docker Compose installed (Install Docker)
  • A computer to run the server
  • At least one display device (Windows PC or Raspberry Pi)

Step 1: Install TheiaCast Server (2 minutes)

Fastest path: the automated installer does everything below for you in one run on Ubuntu/Debian, including the Teams Relay service this manual version needs too. If you’re on those platforms, use that instead and skip to Step 2. Otherwise, follow the manual steps here.

1. Create a directory for TheiaCast

mkdir -p theiacast/docker/mediamtx
cd theiacast

2. Create a docker-compose.yml file

services:
  postgres:
    image: postgres:15-alpine
    container_name: theiacast-postgres
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: your-secure-password
      POSTGRES_DB: theiacast
    volumes:
      - postgres_data:/var/lib/postgresql/data
    ports:
      - "5432:5432"
    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=your-secure-password
      - ASPNETCORE_ENVIRONMENT=Production
      - Jwt__Secret=your-secret-key-here-minimum-32-characters
      - BASE_URL=http://backend:8080
      # Teams Relay: shown to admins as the RTMP endpoint to hand meeting organizers -
      # "localhost" is fine until you actually set it up, see the Installation Guide's
      # Teams Relay notes for changing this to your public hostname/IP.
      - TeamsRelay__PublicRtmpHost=localhost
      - TeamsRelay__PublicRtmpPort=1935
      - TeamsRelay__MediaMtxApiBaseUrl=http://mediamtx:9997
    ports:
      - "5001:8080"
    depends_on:
      - postgres
    volumes:
      - theiacast_media:/app/wwwroot
      - theiacast_dataprotection_keys:/app/dataprotection-keys
    restart: unless-stopped

  frontend:
    image: ghcr.io/jimmyeao/theiacast-frontend:latest
    container_name: theiacast-frontend
    ports:
      - "80:80"
    depends_on:
      - backend
    restart: unless-stopped

  # Teams Relay's RTMP ingest (re-broadcasting a live Teams meeting to screens) - see the
  # Installation Guide for what this does. Required infrastructure even if you don't use
  # Teams Relay yet; it just sits idle until you configure it in the next step.
  mediamtx:
    image: bluenviron/mediamtx:1.9.3
    container_name: theiacast-mediamtx
    volumes:
      - ./docker/mediamtx/mediamtx.yml:/mediamtx.yml:ro
    ports:
      - "1935:1935"
    depends_on:
      - backend
    restart: unless-stopped

volumes:
  postgres_data:
  theiacast_media:
  theiacast_dataprotection_keys:

Important: Change your-secure-password and your-secret-key-here-minimum-32-characters to secure values! theiacast_dataprotection_keys must persist - it holds the keys that encrypt stored content passwords and auto-login sessions.

3. Create the Teams Relay config file

Create docker/mediamtx/mediamtx.yml with the content from the Installation Guide, Step 5. The mediamtx service above won’t start without it.

4. Start the services

docker compose up -d

5. Wait for services to start (about 30 seconds)

docker compose logs -f backend

Wait until you see "Application started" or similar message, then press Ctrl+C.

Step 2: Access the Dashboard (30 seconds)

1. Open your web browser

Navigate to:

http://localhost

(Or use your server's IP address if accessing remotely)

2. Create an admin account

  • The first user to register becomes the administrator
  • Click "Register"
  • Fill in username and password
  • Click "Create Account"

3. You're in!

You should now see the TheiaCast dashboard.

Step 3: Connect Your First Display (2 minutes)

For Windows Display

1. In the TheiaCast dashboard

  • Click "Devices" in the sidebar
  • Click "+ Add Device"
  • Enter a name (e.g., "Lobby Display")
  • Enter a unique Device ID (e.g., "lobby-01")
  • Click "Create"
  • Copy the device token shown in the popup

2. Download and install the Windows client

Download from our CDN

Run the installer - it will prompt you for the server URL, device ID, and device token from step 1.

3. Verify connection

  • Go back to the dashboard
  • The device should show as "Online" with a green indicator

For Raspberry Pi Display

See the full Installation Guide for Raspberry Pi setup instructions.

Step 4: Create Your First Playlist (1 minute)

1. Add content

  • Click "Content" in the sidebar
  • Click "+ Add Content"
  • Enter a name (e.g., "Welcome Page")
  • Enter a URL (e.g., "https://example.com")
  • Click "Save"

2. Create a playlist

  • Click "Playlists" in the sidebar
  • Click "+ Create Playlist"
  • Enter a name (e.g., "Main Lobby")
  • Click "Create"
  • Click "Add Item" to add your content
  • Set display duration (in seconds, or 0 for permanent)
  • Click "Save"

3. Assign to device

  • Click "Devices" in the sidebar
  • Find your device and click to flip the card
  • Click "Assign Playlist"
  • Select your playlist
  • Click "Assign"

4. Watch the magic!

Your display should now show the content.

🎉 You're Done!

Your first display is now showing content. Here's what to explore next:

Learn More

Quick Tips

  • Upload videos: Use the "Content" page to upload MP4 files
  • Upload presentations: Upload PowerPoint files for slideshow content
  • Upload images: Upload JPGs or PNGs for static displays
  • Schedule content: Use time windows to show content at specific times
  • Broadcast urgent messages: Use the broadcast feature for immediate alerts
  • Remote control: Click "Live Remote" on any device to see and control it in real-time

Need Help?

Next Steps

Read the full User Guide to learn about advanced features like scheduling, broadcasting, and remote control.