Deployment Guide¶

This guide covers deploying TALOS from a quick local demo to a production ground station network.

Quick Demo (Local, 3 minutes)¶

Run the full stack on your machine to see the dashboard and track satellites visually.

cd ops
docker compose -f docker-compose.yml -f docker-compose.demo.yml up -d --build

Wait for all services to be healthy:

docker compose ps

Run database migrations:

docker compose exec core alembic upgrade head

Then run the demo seed script:

python scripts/demo-seed.py

Open http://localhost:8000 and follow the on-screen instructions. A default organization is automatically created for the first user.

What you get¶

Live mission control dashboard at http://localhost:8000
Real satellite data from SatNOGS (after sync)
"Magic Find" to discover satellites overhead in real-time
Real-time orbital visualization on the map
Working Director computing SGP4 at 2 Hz with multi-campaign support

What you do not get (without hardware)¶

Actual antenna movement (needs a rotator + rotctld)
RF signal reception (needs an SDR or radio + rigctld)
Telemetry from real ground stations

To stop:

docker compose -f docker-compose.yml -f docker-compose.demo.yml down -v

Production Deployment¶

Architecture¶

                    Internet
                       |
              +--------+--------+
              |   Reverse Proxy |  (Caddy / Nginx / Traefik)
              |   :443 HTTPS   |
              +--------+--------+
                       |
         +-------------+-------------+
         |                           |
  +------+------+          +---------+---------+
  | Core API    |          | MQTT Broker       |
  | :8000       |          | :1883 TCP         |
  |             |          | :9001 WebSocket   |
  +------+------+          +---------+---------+
         |                           |
  +------+------+          +---------+---------+
  | PostgreSQL  |          |    Director       |
  | :5432       |          | (physics engine)  |
  +--------------+          +-------------------+
                                     |
                              MQTT over TLS
                                     |
                    +----------------+----------------+
                    |                |                |
              +-----+-----+  +-----+-----+  +------+-----+
              | Agent (Pi) |  | Agent (Pi) |  | Agent (Pi) |
              | Station 1  |  | Station 2  |  | Station 3  |
              +------------+  +------------+  +------------+

Option A: Single VPS (Recommended for <50 stations)¶

Any Linux VPS with 2 GB RAM is sufficient. Hetzner CX22 (~4 EUR/month) or DigitalOcean Basic Droplet work well.

1. Provision the server¶

ssh root@your-server
apt update && apt install -y docker.io docker-compose-plugin git

2. Clone and configure¶

git clone https://gitlab.com/pierros/talos.git
cd talos/ops
cp .env.example .env

Edit .env with strong secrets:

# Generate secure values
python3 -c "import secrets; print(secrets.token_urlsafe(64))"

3. Generate MQTT credentials¶

chmod +x scripts/gen_mqtt_credentials.sh
./scripts/gen_mqtt_credentials.sh

4. Set up TLS with Caddy (recommended)¶

Create Caddyfile alongside docker-compose:

talos.yourdomain.com {
    reverse_proxy core:8000
}

mqtt.yourdomain.com {
    reverse_proxy broker:9001
}

Add Caddy to docker-compose as a service, or run it standalone.

5. Start the stack¶

docker compose up -d --build

6. Run database migrations¶

docker compose exec core alembic upgrade head

Migrations also run automatically on container startup. The first user to log in will have a default organization created automatically.

7. Verify¶

docker compose ps          # All services healthy
docker compose logs -f     # Watch startup
curl https://talos.yourdomain.com/  # Dashboard loads

Option B: Home Server with Cloudflare Tunnel¶

If you want to run TALOS on a home machine without exposing ports:

1. Install Cloudflare Tunnel¶

# Install cloudflared
curl -fsSL https://pkg.cloudflare.com/cloudflared-linux-amd64.deb -o cloudflared.deb
dpkg -i cloudflared.deb

# Authenticate
cloudflared tunnel login

# Create tunnel
cloudflared tunnel create talos

2. Configure tunnel¶

Create ~/.cloudflared/config.yml:

tunnel: <tunnel-id>
credentials-file: /root/.cloudflared/<tunnel-id>.json

ingress:
  - hostname: talos.yourdomain.com
    service: http://localhost:8000
  - hostname: mqtt.yourdomain.com
    service: http://localhost:9001
  - service: http_status:404

3. Run¶

cd talos/ops
docker compose up -d --build
cloudflared tunnel run talos

Option C: Kubernetes (for large networks, 50+ stations)¶

Use the Dockerfiles to build images and deploy via Helm or plain manifests. This is only justified at scale. Key considerations:

Each component (Core, Director, Broker, DB) runs as a separate Deployment
Director should be a single replica (it holds station state)
PostgreSQL should use a managed service (CloudSQL, RDS, etc.)
MQTT broker should use EMQX or HiveMQ for clustering
Use Ingress for HTTPS termination

A Helm chart is on the roadmap but not yet available.

Connecting Ground Stations¶

Once the central server is running, connect edge agents:

1. Provision via dashboard¶

Log into the dashboard
Click [+] to add a new node
Enter a SatNOGS station ID (or use 0 for a custom station)
Copy the generated agent command

2. Set up the Raspberry Pi¶

# On the Pi
sudo apt install python3-pip hamlib-utils

# Start Hamlib daemons for your hardware
rotctld -m 601 -r /dev/ttyUSB0 -t 4533 &    # Rotator
rigctld -m 1 -t 4532 &                        # Radio (dummy for testing)

# Install and run the agent
pip3 install paho-mqtt
python3 agent.py --id gs_your_station_xxxx --key sk_your_key_here

3. Point agent at your server¶

Edit the BROKER variable in agent.py or pass it as an environment variable:

BROKER=mqtt.yourdomain.com python3 agent.py --id gs_xxx --key sk_xxx

The agent will: 1. Connect to the MQTT broker 2. Announce itself (Director picks it up automatically) 3. Receive hardware config from the Director 4. Start accepting tracking commands

Monitoring¶

Logs¶

docker compose logs -f core       # API requests, auth events
docker compose logs -f director   # Physics loop, station binding, TLE updates

Health checks¶

docker compose ps                 # Service health status
curl localhost:8000/              # API responds

MQTT inspection¶

# Watch all TALOS messages
mosquitto_sub -h localhost -t "talos/#" -v

# Watch Director heartbeat
mosquitto_sub -h localhost -t "talos/director/heartbeat"

# Watch a specific station
mosquitto_sub -h localhost -t "talos/gs/gs_your_station/+" -v

Backup and Recovery¶

Database backup¶

docker compose exec db pg_dump -U talos talos_core > backup_$(date +%Y%m%d).sql

Restore¶

docker compose exec -T db psql -U talos talos_core < backup_20260401.sql

Full stack backup¶

The only stateful component is PostgreSQL. MQTT messages are ephemeral. TLE data is re-fetched from SatNOGS on sync.

Updating¶

cd talos
git pull
cd ops
docker compose up -d --build

# Apply any new database migrations
docker compose exec core alembic upgrade head

The Director and Core will restart with the new code. Active tracking sessions will resume after the Director re-fetches active campaign assignments from the database.