Installation Guide

Get PEON running on your system in minutes with Docker Compose.

Prerequisites

Docker: Version 20.10 or higher
Docker Compose: Version 2.0 or higher
System Requirements: 4GB RAM, 2 CPU cores minimum

!!! tip "System Check" Run these commands to verify your system:

docker --version
docker compose version

Quick Install (Docker Compose)

1. Download PEON

git clone https://github.com/the-peon-project/peon.git
cd peon

2. Configure Environment

cp .env.sample .env
nano .env  # Edit configuration

Key Environment Variables:

# Orchestrator Configuration
PEON_API_KEY=your_secure_api_key_here
PEON_DIRECTORY=/root/peon

# Optional shared cache proxy for game downloads and updates
PEON_CACHE_ENABLED=true
PEON_CACHE_URL=http://host.docker.internal:3128
PEON_CACHE_BYPASS=localhost,127.0.0.1,host.docker.internal,peon.orc,peon.webui,peon.db

# Optional HTTPS reverse proxy (Caddy + Let's Encrypt)
PEON_PROXY_ENABLED=false
PEON_PROXY_DOMAIN=server.example.com
PEON_PROXY_EMAIL=ops@example.com
PEON_WEBUI_HOST_PORT=80

# Discord Bot Configuration
DISCORD_TOKEN=your_discord_bot_token_here

3. Start PEON Services

./deploy_peon.sh

To run non-interactively with HTTPS reverse proxy enabled:

./deploy_peon.sh --orchestrator --webui --proxy \
  --proxy-domain server.example.com \
  --proxy-email ops@example.com

This will start:

Orchestrator: Core API service (port 5000)
Cache Proxy: Shared HTTP cache for SteamCMD and other proxy-aware downloads (port 3128, when enabled)
Discord Bot: Slash command interface
Web UI: Browser interface (port 80 by default, port 8080 when reverse proxy is enabled)
Reverse Proxy: Caddy with automatic Let's Encrypt certificates (ports 80/443, when enabled)

When the cache proxy is enabled, newly generated game server manifests receive standard proxy environment variables and a host.docker.internal host-gateway alias. Downloads that honor HTTP_PROXY or HTTPS_PROXY will reuse cached content locally instead of fetching every update from the internet again.

4. Verify Installation

Check that all services are running:

docker compose ps

You should see:

NAME               SERVICE      STATUS       PORTS
peon.orc           orc         running      0.0.0.0:5000->5000/tcp
peon.bot.discord   bot         running      
peon.webui         webapp      running      0.0.0.0:80->80/tcp

:::warning{title="Updating containers: keep the service aliases"} The reverse proxy (and the Web UI / Discord bot) reach each other by Docker Compose service name (webapp, orc, …), which Compose registers as a DNS alias on the shared network. If you ever recreate a container with a plain docker run instead of docker compose, those aliases are dropped and the proxy will return 502 even though every container is healthy. Re-add an alias with:

docker network connect --alias webapp --ip <container-ip> peon_zugnet peon.webui

See the FAQ — I get a 502 (Bad Gateway) from the web UI for diagnosis and the full fix. :::

For API documentation:

WebUI API docs: http://localhost/docs
Orchestrator docs through WebUI sub-path: http://localhost/api/proxy/{orchestrator_id}/docs

Discord Bot Setup

1. Create Discord Application

Go to Discord Developer Portal
Click "New Application"
Name your application (e.g., "PEON Game Server Bot")
Go to "Bot" section
Click "Add Bot"
Copy the bot token to your .env file

2. Set Bot Permissions

Your bot needs these permissions: - Send Messages - Use Slash Commands - Embed Links - Attach Files - Read Message History - Use External Emojis

Permission Integer: 137443262464

3. Invite Bot to Server

Use this URL (replace CLIENT_ID):

https://discord.com/api/oauth2/authorize?client_id=YOUR_CLIENT_ID&permissions=137443262464&scope=bot%20applications.commands

4. Test Bot

In your Discord server, type:

/peon

You should see the PEON interface!

Manual Installation

Option A: Individual Containers

Run each component separately:

# Orchestrator
docker run -d \
  --name peon.orc \
  -p 5000:5000 \
  -e LOCAL_API_KEY=your_api_key \
  -v $(pwd)/config:/app/config \
  -v $(pwd)/data:/home/peon \
  umlatt/peon.orc:latest

# Discord Bot
docker run -d \
  --name peon.bot.discord \
  -e DISCORD_TOKEN=your_token \
  -e LOCAL_API_KEY=your_api_key \
  -v $(pwd)/config:/app/config \
  umlatt/peon.bot.discord:latest

# Web UI
docker run -d \
  --name peon.webui \
  -p 80:80 \
  -e REACT_APP_BACKEND_URL=http://localhost \
  umlatt/peon.webui:latest

Option B: Native Installation

!!! warning "Advanced Users Only" Native installation requires managing Python dependencies and system services manually.

See the development documentation for native installation instructions.

Troubleshooting

Common Issues

Bot not responding: - Check Discord token in .env file - Verify bot permissions in Discord server - Check bot container logs: docker logs peon.bot.discord

API errors: - Verify orchestrator is running: curl http://localhost:5000/api/v1/orchestrator - Check API key configuration - Review orchestrator logs: docker logs peon.orc

Container startup issues: - Ensure Docker daemon is running - Check available disk space - Verify port availability