Deploy otomo on a VM¶
This guide takes you from an empty Linux virtual machine to a complete otomo for your game: every service, the admin website, a public HTTPS address for players, and a pool of game servers. Everything after this page assumes you've done it.
Plan for two to three hours, most of it waiting and checking. The guide is entirely in the terminal; if that's new to you, read Command-line basics and Servers and containers first.
Throughout this guide, play.example.com stands for your domain name and
203.0.113.10 for your VM's IP address. Replace them with your own every time.
What's yours and what's otomo's¶
Before starting, it helps to know where the line is:
| Part | Who provides it |
|---|---|
| Auth, Gateway, Patch, Session, Allocator, Gameplay Proxy, Dashboard, admin website, edge, wiki | Otomo. You run and configure them; you don't change their code for your game. |
| Settings documents and their schemas, content packs | Your game. You create them in the admin website (Content and patching). |
| Lobby rules (party size, allowed lobby settings) | Your game, as the server namespace session.rules. |
| The game server | Your game: your Godot server export (Run a new game server build). |
| The game client | Your game, with the SDK (Install the SDK). |
The public website at / |
Your game, from its own repository (Wikis and sites). |
What you need¶
- A Linux VM from any cloud provider, running Ubuntu 24.04, with at least 2 CPU
cores, 4 GB of memory and 40 GB of disk. You need to be able to log in to it with SSH
and use
sudo. - A domain name you control, such as
play.example.com, with an A record pointing at the VM's IP address. Your domain provider's DNS settings page is where you add it. It's needed for the HTTPS certificate. Check it from your PC:nslookup play.example.comshould print the VM's IP. - Ports open in your cloud provider's firewall (often called a security group): TCP 22 (SSH), TCP 80 and 443 (HTTPS), and UDP 27000 (the Gameplay Proxy).
- On your PC: an SSH client. On Windows, use WSL (Before you begin).
Nothing else is needed on the VM besides Docker: no Go, no Node, no database. Everything runs in containers.
Step 1: Prepare the VM¶
Log in to the VM from your PC:
Every command from here to the end of Step 7 runs on the VM.
Install Docker, git and openssl¶
These are the commands from Docker's own "Install Docker Engine on Ubuntu" page. Run them one block at a time:
sudo apt-get update
sudo apt-get install -y ca-certificates curl git openssl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] \
https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" \
| sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
Let your user run Docker without sudo, then log out and back in so it takes effect:
The last command should print a version number such as Docker Compose version v2.29.1.
Turn on the firewall¶
ufw is Ubuntu's firewall. Allow SSH before enabling it, or you'll lock yourself out:
Docker-published ports bypass ufw
Docker writes its own firewall rules, so a port a container publishes is reachable even
without a ufw allow rule. Otomo therefore publishes only the ports it needs to (80,
443 and the Gameplay Proxy's UDP port) and binds everything else to the VM's own
address. The ufw rules below record your intent; your cloud provider's firewall is
the other layer.
Step 2: Get otomo onto the VM¶
git clonedownloads the repository into a new folder,~/otomo(~is your home folder).git checkout mainmakes sure you're onmain, the branch with the latest release.stagingholds the work going into the next release, and can change at any time.
Step 3: Generate secrets¶
Otomo needs passwords for its databases, and keys that let its services recognise each other. A script makes them all:
It creates:
deploy/.env, a text file of settings and passwords, oneNAME=valueper line;deploy/secrets/, a folder of key files;deploy/valkey/valkey.conf, the settings for Valkey (see How otomo fits together).
It's safe to run again: it never overwrites a secret that already exists.
Give the key folders to the right owner¶
Otomo's containers run as a restricted user with the number 65532, not as you, so the folders they write keys into must belong to that user. The script prints the exact commands to run at the end. They look like this:
sudo chown -R 65532:65532 /home/you/otomo/deploy/secrets/admin_auth
sudo chown -R 65532:65532 /home/you/otomo/deploy/secrets/service_keys /home/you/otomo/deploy/secrets/allocator
Copy the lines the script printed, not these: yours contain your own folder path.
chown changes who owns a file; -R applies it to everything inside the folder too.
Step 4: Start everything¶
This is the one command that brings otomo up. It takes 10 to 20 minutes the first time, most of it building images. In order, it:
- builds every service's image;
- starts the database (Postgres), Valkey and the local image registry, and waits for them;
- prepares the databases (runs each service's migrations, which create the tables it needs);
- generates signing keys for logins, once, and creates the emergency admin account;
- starts every service;
- checks each one answers, printing
okorFAILEDper service.
The end of a successful run looks like this:
waiting for services
ok auth liveness (/healthz)
ok auth readiness (/readyz)
…
ok gameplay-proxy readiness (/readyz)
If one line says FAILED
Services depend on each other and some take a moment to start. Run up.sh again: it's
safe to repeat, and it skips work that's already done. If the same service fails
twice, look at its log: cd deploy && docker compose logs --tail 50 <service>.
At this point otomo is running, but only reachable from the VM itself. The next steps make it reachable by players.
Step 5: A public HTTPS address¶
Players' games must reach otomo over HTTPS, which needs a certificate proving the server owns its domain name (How games go online). Otomo gets a free one from Let's Encrypt, an organisation that issues certificates automatically.
Let's Encrypt limits how many certificates you can get
Let's Encrypt allows only a small number of new certificates per domain per week. If your host name sits under a domain you share with others (a company's or a school's), everyone on it shares that limit. Otomo's script therefore makes you rehearse first, which costs nothing, and refuses to request a real certificate twice. Follow the steps in order and don't skip the rehearsal.
In deploy/, open .env in a text editor (nano deploy/.env) and set:
OTOMO_PUBLIC_HOST is your domain name. COMPOSE_PROFILES=edge switches on the edge,
the HTTPS front door, which is off by default. Save and exit (Ctrl+X,
Y, Enter), then run, from the otomo folder, one at a time:
# 1. Open ports 80 and 443 in the VM's firewall.
sudo ufw allow 80/tcp comment 'otomo edge'
sudo ufw allow 443/tcp comment 'otomo edge'
# 2. Install certbot, the program that talks to Let's Encrypt.
sudo deploy/edge/certbot.sh install
# 3. Start the edge (it waits for a certificate).
deploy/scripts/up.sh
# 4. Rehearse. This checks that Let's Encrypt can reach your VM, and costs nothing.
sudo OTOMO_PUBLIC_HOST=play.example.com deploy/edge/certbot.sh dry-run
# 5. ONLY if step 4 succeeded: request the real certificate, once.
sudo OTOMO_PUBLIC_HOST=play.example.com deploy/edge/certbot.sh issue --confirm-single-issuance
Then set OTOMO_PUBLIC_BASE_URL=https://play.example.com in deploy/.env, and run
deploy/scripts/up.sh one more time.
Check it from your own PC:
HTTP/1.1 200 OK with some JSON means players can reach otomo. The certificate renews
itself from now on; you never run issue again.
Step 6: The Gameplay Proxy port¶
Open the proxy's UDP port in the firewall:
If another program on the VM already uses UDP 27000 (you'd see address already in use
when the proxy starts), pick another free port, open that instead (in ufw and your
cloud provider's firewall), and set it in deploy/.env:
Otomo tells games the port automatically, so nothing changes on the game's side.
Step 7: Game servers¶
Follow Run a new game server build to put your game server in
deploy/gameserver/build/. Then add gameservers to the profiles in deploy/.env:
and run deploy/scripts/up.sh.
You can skip this step for now and come back to it: patching and logins work without game servers.
Step 8: Sign in to the admin website¶
The admin website isn't on the internet (see Use the admin website). Read the root password on the VM:
Then, from your PC, open a tunnel and sign in as root@otomo.internal at
http://localhost:8090/admin/:
Create a personal account for each person on your team under Users, and keep root for emergencies.
Step 9: Point your game at it¶
In your game, set Project Settings › Otomo › Config › Base Url to
https://play.example.com. Run the SDK's test scene
(Install the SDK, Step 5) to check.
Keeping it running¶
Updating otomo¶
New otomo releases land on main. Read the release notes on GitHub first, then on the VM:
up.sh rebuilds only what changed and restarts only the services whose images changed.
Checking health¶
- The admin website's Overview page shows each service's state and any firing alerts.
- On the VM,
cd ~/otomo/deploy && docker compose pslists every container and whether it's running.
Where the important files are¶
Path (under ~/otomo/deploy/) |
What | Back it up? |
|---|---|---|
.env |
Settings and passwords | Yes, privately |
secrets/ |
Signing and service keys | Yes, privately. Losing the login signing key logs every player out. |
Docker volumes (docker volume ls) |
The databases and uploaded content | Yes: this is all your game's data |
Never commit .env or secrets/ to git: they're secrets, and otomo's .gitignore keeps
them out.
Backing up¶
deploy/scripts/backup.sh writes one archive holding a dump of every database, deploy/secrets and
deploy/.env, while the stack keeps running. It keeps 7 daily and 4 weekly archives under
~/otomo-backups/, and a systemd timer can run it every night. The archive contains your private
keys, so treat it like secrets/. What it covers, how to restore, and how to copy archives off the
host are in deploy/docs/BACKUP.md; Deployment and operations
summarises it.
Next¶
- Install the SDK in your game.
- Use the admin website.
- Troubleshooting.