Hosting on a VPS

Running a beacon on your laptop is fine for trying it out, but for a server your friends actually use, put it on a machine that stays online. A small VPS does the job for a few dollars a month. This guide goes from a fresh server to a claimed dashboard.

What you'll need

• A VPS running a recent Linux (this guide uses Ubuntu 22.04/24.04 LTS).
• SSH access as a user with sudo.
• A plan for reaching the dashboard: Tailscale (recommended — private, no open ports) or a custom domain.

Sizing the server

Minecraft is memory-hungry. Size for the server you want, leaving ~1 GB beyond the JVM for the OS, Beacon, and the live-map renderer.

MC_MEMORY is just the JVM heap — the CLI sizes the container with extra off-heap headroom on top, and beacon up warns if your beacons' configured memory over-commits the host. So pick a VPS that fits the table and let the CLI do the math; you don't add headroom by hand.

Step 1 — Provision and connect

Create the VPS, add your SSH key, then connect and update it:

ssh youruser@your-server-ip
sudo apt update && sudo apt upgrade -y

Step 2 — Install Docker and Node.js

The CLI needs two things on the host: Docker (to run the stack) and Node.js 20+ (to run the CLI itself). Install both from their official sources so you stay current:

• Docker Engine — follow the official install guide for your distro. On a fresh Ubuntu box, Docker's convenience script is the quickest path:

  curl -fsSL https://get.docker.com | sh
  sudo usermod -aG docker "$USER"

  Log out and back in (or run newgrp docker) so your user can run Docker without sudo.

• Node.js 20+ — install from nodejs.org/download (the page generates the right commands for your platform and package manager), or use nvm and nvm install --lts.

Verify both before continuing:

docker run --rm hello-world
node -v

Step 3 — Install the Beacon CLI

curl -fsSL https://beacon-mc.io/install.sh | sh

If beacon isn't found afterward, add the install dir to your PATH:

export PATH="$HOME/.local/bin:$PATH"

Step 4 — Deploy

Run the guided wizard and pick your ingress at the Mode step:

beacon

The wizard probes Docker, generates secrets, pins the release, pulls the images, starts the stack, and waits for health. On a small VPS, first-world generation can take up to ~90 seconds.

Prefer scripted? Use beacon create --yes with explicit flags — see the CLI reference.

Step 5 — Lock down the firewall

Open only what your ingress needs.

sudo ufw allow OpenSSH
sudo ufw allow 25565/tcp        # Minecraft players
sudo ufw enable

sudo ufw allow OpenSSH
sudo ufw allow 25565/tcp        # Minecraft players
sudo ufw allow 80/tcp           # ACME challenge + redirect
sudo ufw allow 443/tcp          # dashboard over HTTPS
sudo ufw enable

Apply the same rules in your provider's cloud firewall (security groups) if it has one — both layers must allow the traffic. More detail in Ports & Access.

Step 6 — Claim the dashboard

Open the dashboard and claim the first admin account:

beacon admin

If the one-time claim URL scrolled past, run beacon restart, then beacon logs admin-rpc and open the latest ADMIN CLAIM LINK.

Keep it healthy