Skip to content
HoloMUSH HoloMUSH HoloMUSH

Deploying HoloMUSH

Deploy a production HoloMUSH instance on a DigitalOcean droplet with automatic HTTPS, telnet support, and optional monitoring. The entire deployment runs in Docker and takes about 10 minutes.

Prerequisites

Section titled “Prerequisites”
  • A domain name you control (for HTTPS certificates)
  • A DigitalOcean account (or any Linux host with Docker 24+)

Quick Start

Section titled “Quick Start”

1. Create a Droplet

Section titled “1. Create a Droplet”

In the DigitalOcean control panel:

  1. Click Create Droplet
  2. Choose Ubuntu 24.04 LTS
  3. Select the $6/mo plan (1 vCPU, 1 GB RAM) — sufficient for most games
  4. Choose a datacenter region close to your players
  5. Under Advanced Options, check Add Initialization Scripts
  6. Paste the cloud-init script into the User Data field
  7. Click Create Droplet

The script installs Docker, creates the deployment directory at /opt/holomush/, and generates a configuration file with a random database password.

2. Point Your DNS

Section titled “2. Point Your DNS”

Create an A record pointing your domain to the droplet’s IP address:

mush.example.com  →  A  →  203.0.113.42

Wait for DNS to propagate (usually 1–5 minutes).

3. Configure

Section titled “3. Configure”

SSH into your droplet and edit the configuration:

Terminal window
ssh root@your-droplet-ip
nano /opt/holomush/.env

Set DOMAIN to your actual domain:

Terminal window
DOMAIN=mush.example.com

Save and exit.

4. Start the Stack

Section titled “4. Start the Stack”
Terminal window
cd /opt/holomush
docker compose up -d

On first boot, HoloMUSH runs database migrations and seeds the default world (“The Crossroads”). This takes about 30 seconds.

5. Verify

Section titled “5. Verify”
  • Web client: Visit https://your-domain — you should see the HoloMUSH landing page. Click “Try as Guest” to enter the game.
  • Telnet: Connect with any MU* client: telnet your-domain 4201
  • Logs: docker compose logs -f core to watch game events.
Section titled “Block Storage (Recommended)”

For easier backups and the ability to resize storage independently:

  1. In DigitalOcean, create a Volume (10 GB is plenty to start)
  2. Attach it to your droplet
  3. Mount it:
Terminal window
# Mount the volume (DigitalOcean provides exact commands)
mount -o defaults,nofail,discard /dev/disk/by-id/scsi-0DO_Volume_xxx /mnt/holomush


# Stop the stack
cd /opt/holomush && docker compose down


# Move data to the volume
mv /opt/holomush/data /mnt/holomush/data


# Update .env
echo 'DATA_DIR=/mnt/holomush/data' >> /opt/holomush/.env


# Restart
docker compose up -d

Now you can snapshot the volume for backups.

Monitoring (Optional)

Section titled “Monitoring (Optional)”

HoloMUSH exports OpenTelemetry data (traces, metrics, logs) to any OTLP-compatible backend. Grafana Cloud offers a generous free tier (10K metrics series, 50GB logs, 50GB traces).

Set Up Grafana Cloud

Section titled “Set Up Grafana Cloud”
  1. Sign up at grafana.com (free)
  2. Go to Connections → Add new connection → OpenTelemetry (OTLP)
  3. Copy the OTLP endpoint URL and generate an API token
  4. Add to /opt/holomush/.env:
Terminal window
OTEL_EXPORTER_OTLP_ENDPOINT=https://otlp-gateway-prod-us-central-0.grafana.net/otlp
OTEL_EXPORTER_OTLP_HEADERS=Basic <your-base64-token>
  1. Start with the observability profile:
Terminal window
docker compose --profile observability up -d

Any OTLP-compatible backend works — Axiom, SigNoz, Better Stack, and others all accept the same format. Change the endpoint and headers in .env.

Upgrading

Section titled “Upgrading”

Pull the latest images and restart:

Terminal window
cd /opt/holomush
docker compose pull
docker compose up -d

Database migrations run automatically on startup. Check logs after upgrading:

Terminal window
docker compose logs core | head -50

Backups

Section titled “Backups”

The entire deployment lives in /opt/holomush/. Back it up with:

Terminal window
# Stop postgres to ensure consistency
cd /opt/holomush && docker compose stop postgres


# Archive
tar czf /tmp/holomush-backup-$(date +%Y%m%d).tar.gz /opt/holomush/


# Restart
docker compose start postgres

Or snapshot the DigitalOcean volume if using block storage.

Troubleshooting

Section titled “Troubleshooting”
SymptomCheck
HTTPS not workingDNS propagated? dig your-domain should show droplet IP
”502 Bad Gateway” from CaddyGateway healthy? docker compose logs gateway
Telnet connection refusedUFW allows 4201? ufw status
Game world emptyCore bootstrap logs: docker compose logs core | grep bootstrap
Caddy cert errorsPort 80 open? ACME needs it for HTTP-01 challenge

For detailed monitoring and health check information, see Operations.

Generic Linux Host

Section titled “Generic Linux Host”

Any Linux host with Docker 24+ works. Skip the DigitalOcean-specific steps and instead:

  1. Install Docker: docs.docker.com/engine/install
  2. Download compose.prod.yaml to /opt/holomush/compose.yaml
  3. Download docker/otel-collector/config.prod.yaml to /opt/holomush/config/otel-collector.yaml
  4. Create /opt/holomush/.env (see the generated .env in the cloud-init script for the template)
  5. Create the data directories: mkdir -p /opt/holomush/{data/postgres,config/certs,caddy/{data,config}}
  6. Follow steps 3–5 from the Quick Start above

Alternative: Cloudflare Tunnel ingress

Section titled “Alternative: Cloudflare Tunnel ingress”

If you want your server reachable only through Cloudflare (no public HTTP ports open on the droplet), use the tunnel ingress profile instead of Caddy. Cloudflare terminates TLS at its edge and your droplet makes an outbound connection to Cloudflare — nothing connects inbound to 80 or 443.

  1. In the Cloudflare dashboard, go to Zero Trust → Networks → Tunnels and create a new tunnel named holomush.

  2. Copy the tunnel token (it starts with eyJh...).

  3. In the tunnel’s Public Hostnames tab, add a route: mush.example.com → http://gateway:8080.

  4. Set your cloud-init user-data to include these env vars:

    Terminal window
    HOLOMUSH_INGRESS=tunnel
    HOLOMUSH_DOMAIN=mush.example.com
    CLOUDFLARE_TUNNEL_TOKEN=eyJh...your-token...

  5. Create the droplet with the cloud-init script. Once first boot completes, https://mush.example.com is live.

Telnet (port 4201) still reaches your droplet directly — Cloudflare does not proxy arbitrary TCP. Add a “DNS only” A record for telnet.mush.example.com pointing at your droplet’s IP.

Automated nightly backups (encrypted)

Section titled “Automated nightly backups (encrypted)”

To back up Postgres nightly to S3-compatible storage (DigitalOcean Spaces, AWS S3, Cloudflare R2) with client-side encryption, add these vars to your cloud-init:

Terminal window
BACKUP_S3_BUCKET=my-holomush-backups
BACKUP_S3_ENDPOINT=sfo3.digitaloceanspaces.com   # omit for AWS S3
BACKUP_S3_ACCESS_KEY=...
BACKUP_S3_SECRET_KEY=...
KOPIA_PASSWORD=...           # long random string — encrypts every snapshot
BACKUP_KEEP_DAILY=7          # optional
BACKUP_KEEP_WEEKLY=4         # optional
BACKUP_KEEP_MONTHLY=6        # optional

When set, the cloud-init enables the backups compose profile, which runs a cron container that dumps Postgres at 03:00 UTC and streams it through Kopia. Kopia encrypts the stream client-side (your cloud provider cannot read the backups), deduplicates against previous snapshots, compresses with zstd, and uploads. Retention is policy-based — expired snapshots are pruned automatically.

Keep KOPIA_PASSWORD somewhere recoverable. If you lose it, every snapshot in the repository becomes unrecoverable. Kopia has no recovery backdoor.

Run a one-off backup via:

Terminal window
cd /opt/holomush
docker compose --profile caddy --profile backups exec backup /usr/local/bin/backup.sh

(Replace --profile caddy with --profile tunnel if you use tunnel ingress.)

Restore from a backup: see Restoring a backup.