Server Integrations Setup

Optional services that extend dashboard functionality. Configure only what you need - the app degrades gracefully when any of these are absent.

Tailscale (Network Tab)

The Network tab shows all devices on the club's shared Tailscale network and surfaces join requests from members.

Install Tailscale on the server

$ curl -fsSL https://tailscale.com/install.sh | sh
$ sudo tailscale up

Follow the login URL printed by tailscale up to authenticate with the club Tailscale account.

Generate an API key for the dashboard

1. Tailscale admin console → Settings → Keys → Generate access token
2. Give it a description (e.g. dashboard) and set an expiry
3. Add to .env.production:

$ TAILSCALE_API_KEY=<paste here>
$ TAILSCALE_TAILNET=-

Restart the dashboard to pick up the new values:

$ sudo systemctl restart trickfire-dashboard

Connect other devices

On any device you want on the network:

$ sudo tailscale up

Log in with the club Tailscale account. The device will appear in the Tailscale admin console and in the dashboard Network tab.

Quick reference

OnShape Simulation Export Proxy

/api/sim/export lets external tooling - notably our simulation software - pull a OnShape model through the dashboard's own OnShape credentials and get back a generated simulation asset archive, without every script needing its own OnShape API keys. Callers authenticate with the club's current 6-digit sim access code, read off the dashboard's API Keys page and sent as an X-Access-Code header (see Security for how it rotates). See External Integrations for how the export/cache/streaming code itself works.

Generated archives are cached on disk under SIM_CACHE_DIR (default /var/cache/trickfire-sim). The Next.js server runs as the trickfire user, but /var/cache/ itself is root-owned, so the process can't create its own subdirectory there. Create it and hand ownership to trickfire before starting the server:

$ sudo mkdir -p /var/cache/trickfire-sim
$ sudo chown trickfire: /var/cache/trickfire-sim

Minecraft Server

The Minecraft server runs as an independent systemd service managed by Azalea. The dashboard can start and stop it, stream its logs, and send console commands via RCON - without the server depending on the dashboard process.

Install Azalea

Azalea requires Python 3.9+. Ubuntu 20.04 ships Python 3.8, so install 3.9 first if needed:

$ sudo apt-get install -y python3.9 python3.9-venv
$ python3.9 -m pip install --user git+https://github.com/matejstastny/azalea.git
$ sudo ln -sf /home/trickfire/.local/bin/azalea /usr/local/bin/azalea
$ azalea --version

Create the systemd service

Create /etc/systemd/system/minecraft.service:

[Unit]
Description=Minecraft Server
After=network.target

[Service]
Type=simple
User=trickfire
WorkingDirectory=/home/trickfire/minecraft
ExecStart=/usr/local/bin/azalea server run
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target

$ sudo systemctl daemon-reload
$ sudo systemctl enable minecraft   # enable but don't start - the dashboard controls that

Configure RCON

The dashboard sends console commands to the server via RCON. Enable it in /home/trickfire/minecraft/server.properties:

enable-rcon=true
rcon.port=25575
rcon.password=<openssl rand -hex 16>

Environment variables

Add these to .env.production:

$ MINECRAFT_SERVER_HOST=localhost
$ MINECRAFT_SERVER_PORT=25565
$ MINECRAFT_SERVER_PATH=/home/trickfire/minecraft
$ MINECRAFT_WORLD_PATH=/home/trickfire/minecraft/world
$ MINECRAFT_RCON_PORT=25575
$ MINECRAFT_RCON_PASSWORD=<same password as server.properties>
$ MINECRAFT_BOT_SKIN_URL=https://your-skin-host/bot.png

Bot names aren't configured here - they're detected automatically from a Minecraft scoreboard team named bots via RCON (see External Integrations). MINECRAFT_BOT_SKIN_URL only controls what skin those detected bots render with on the dashboard.

Restart the dashboard to pick up the new values:

$ sudo systemctl restart trickfire-dashboard

Troubleshooting

Pl3xMap (World Map)

The Minecraft page embeds the Pl3xMap world map. The dashboard proxies it at /pl3xmap so it's accessible via the dashboard URL without exposing Pl3xMap's port publicly.

Install Pl3xMap

Pl3xMap is a server-side Minecraft mod. Follow the official Pl3xMap docs for your server type (Fabric, Paper, etc.). Its internal web server runs on port 8080 by default.

Configure the dashboard

Add to .env.production:

# If Pl3xMap runs on the same machine as the dashboard:
$ PL3XMAP_URL=http://localhost:8080

# If Pl3xMap runs on a separate machine:
$ PL3XMAP_URL=http://<minecraft-server-ip>:8080

Restart: sudo systemctl restart trickfire-dashboard

Troubleshooting