Deploy to a VPS
On a VPS the shard runs in Docker Compose. Images are built on your machine and sent over SSH, so the server never compiles.
A shard with AI residents needs at least 4 GB of RAM. With 2 GB the AI service is swapped out and killed under memory pressure, and its residents keep dropping.
-
Create an Ubuntu server and log in once, so your machine learns its host key.
Terminal window ssh root@your-server-ipSSH shows the server’s key fingerprint and asks whether to trust it. Check it against the one in your provider’s console before answering
yes. -
Prepare it once.
Terminal window gemwright shard setup --ssh root@your-server-ip --public-host your-server-ip --clientSetup shows what it will change, then over one SSH session installs Docker, adds swap and opens the firewall ports (SSH, 2593, and 80/443 with
--client). The result is saved tovpsingemwright.json.Logged in as another user, setup gives that user Docker access, and sudo asks for its password on the server.
-
Deploy.
Terminal window gemwright shard deploy --target vps --server --client --ai --files ~/uoWithout flags, the questionnaire asks for SSH access, game files and an optional browser-client domain.
The gemwright user
Section titled “The gemwright user”Logged in as root, setup creates a non-root gemwright user and deploys as that user from then on.
- No password. The account is created without one and its password is locked, so nobody can log in as
gemwrightwith a password, over SSH or on the console. There is no password to look up or set. - Same SSH keys as root. Setup copies root’s
~/.ssh/authorized_keysto/home/gemwright/.ssh/authorized_keys, so every key that logs in as root also logs in asgemwrightwithout a password:ssh gemwright@your-server-ip. A key added to root later is not copied; add it to both files. - Docker, no sudo. It is in the
dockergroup, which on that server is equivalent to root access, and it has no sudo. Gemwright deploys and runs the shard as this user. - Root for everything else. For system updates and other administration, log in as
rootwith your key as before.
Browser client over HTTPS
Section titled “Browser client over HTTPS”Point an A record at the server, then deploy the client with its hostname:
gemwright shard deploy --client --domain play.yourshard.comCaddy gets the certificate once the name resolves to the server.
With Cloudflare DNS
Section titled “With Cloudflare DNS”The Cloudflare CLI (cf) changes the record from your machine. Find the record’s id, check the change with --dry-run, then apply it. Only the address changes; the record’s name, type and proxy setting stay as they are:
cf dns records list -z yourshard.com --name play.yourshard.com --type Acf dns records edit <record-id> -z yourshard.com --body '{"content":"your-server-ip"}' --dry-runcf dns records edit <record-id> -z yourshard.com --body '{"content":"your-server-ip"}'Until Caddy has its certificate, a proxied record answers with Cloudflare error 525: Cloudflare reaches the server, but no TLS handshake completes. Caddy retries by itself, waiting longer after each failure, and attempts made before the record changed fail against the old server. To try again at once, restart Caddy; the certificate arrives within a minute:
ssh gemwright@your-server-ip docker restart gemwright-caddyA login name for native clients, such as login.yourshard.com, needs its own A record, and it must not be proxied: Cloudflare’s proxy carries web traffic only, not the game’s TCP port. Players then log in at login.yourshard.com:2593, and a later move to another server changes only this record:
cf dns records create -z yourshard.com --body '{"type":"A","name":"login.yourshard.com","content":"your-server-ip","proxied":false,"ttl":1}'Run cf outside a folder whose .env sets CLOUDFLARE_API_TOKEN. Bun loads that file, and a token there replaces your cf login, so the zone can appear missing. cf auth whoami shows which credentials it uses.
Move to a new server
Section titled “Move to a new server”Pull from the old server before setup replaces the vps settings, deploy to the new one, then restore the pull there. The old server keeps running until you stop it.
gemwright shard pull --target vps --server --aigemwright shard setup --ssh root@new-server-ip --public-host new-server-ip --clientgemwright shard deploy --target vps --server --client --ai --files ~/uogemwright shard restore --target vps --server --aiPoint the domain at the new server last.
Review before installing
Section titled “Review before installing”--prepare writes the VPS bundle without installing or starting anything. --install-deps approves installing missing packages on the server.
For native clients, point an A record such as login.yourshard.com at the server’s public IPv4 address and set it as --public-host.
