Self-Hosting on a VPS

Run your game server on a Linux VPS you control. This is the fullest-control way to put a game online (prefer one-click? Managed Hosting is available in private beta).

> You may only need to host the game server. If you use the ED5 public play link, we serve the client for you and point it at your server — so the whole client build step below is optional. Read step 6 before you start.

What you need

• A Linux VPS (Ubuntu 22.04 / Debian 12). Start around 2 vCPU / 4 GB RAM and scale up for more players.
• Node 20 and pnpm 9 on the VPS.
• A PostgreSQL database for production — your own Supabase project is fine. Do not use the embedded PGlite database online (see Production Database).
• A domain with DNS you can point at the VPS.
• Basic comfort with a Linux terminal. Every step below is copy-paste, but you will be using SSH.

1. Provision the server

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs
npm i -g pnpm

2. Copy the engine onto the VPS

Your Studio install already contains a complete engine tree. On Windows it lives at:

%APPDATA%\@ed5-mmo-studio\studio\engine\

Copy that folder itself — the root of it. You want the level that contains package.json, pnpm-lock.yaml, pnpm-workspace.yaml, .npmrc, apps/ and packages/.

> Do not copy just packages/game-server. It is a workspace package, not a standalone application — on its own it will not start. It imports @ed5-mmo-studio/shared, @ed5-mmo-studio/db, @ed5-mmo-studio/world-gen and @ed5-mmo-studio/plugin-sandbox at runtime, and the database migrations live in a different package.

The minimum set for a game-only server:

And leave these behind:

> packages/db/drizzle/ is not optional. The server applies its migrations from that folder on every startup. If the folder is missing, the server still boots — and silently applies nothing. This is the single most common self-hosting failure, and it looks like a mysterious "the database is empty / tables don't exist" problem later.

3. Install dependencies

cd /opt/ed5
pnpm install --prod --filter @ed5-mmo-studio/game-server...

If the lockfile complains, retry with pnpm install --prod --no-frozen-lockfile.

The engine ships with its packages already built, so there is no compile step for the server. The trailing ... matters — it pulls in the workspace dependencies too.

4. Configure environment

> Set CONFIG_ENCRYPTION_KEY once and keep it safe. It decrypts settings already stored in your database — change it later and those settings become unreadable. Back it up somewhere you won't lose it.

Then pick how players sign in — see Auth Setup for the full picture:

About the database

Migrations apply automatically on startup from packages/db/drizzle/. You do not need to run a migration command by hand. Watch the first boot all the way through before assuming it worked — and if you see no migration activity at all, re-read the warning in step 2.

5. Run it

cd /opt/ed5
npm i -g pm2
pm2 start "node packages/game-server/dist/index.js" --name game-server
pm2 save && pm2 startup

> The game server has no homepage. Opening its root URL in a browser returns a 404 — that is correct and by design. To check that it's alive, use /health or /status. The /status response includes a bootErrors list, which is the first place to look when something is wrong.

6. Do you need to host the client?

Option A — use the ED5 play link (recommended). Register your server in your account dashboard (step 8) and enable the public play link. We serve the client and point it at your server's wss:// address. Nothing more to build, deploy, or keep updated.

Option B — self-host the client too. Only if you want the client on your own domain. Build it before deploying, because the URLs are baked in at build time:

NEXT_PUBLIC_GAME_SERVER_WS_URL=wss://game.yourdomain.com \
  pnpm --filter @ed5-mmo-studio/client build

That produces a standalone bundle under apps/client/.next/standalone/ — copy .next/static and public alongside the generated server.js, then run it on port 3000.

> NEXT_PUBLIC_ values are frozen at build time. Setting them after you build has no effect, and the client will keep trying to reach whatever address it was built with. The client bundled inside your Studio install was built with local defaults — rebuild it with your own URLs. Changing your domain later means rebuilding.

7. HTTPS + WebSocket

• the game server on a subdomain → 127.0.0.1:3001
• the client, if you're hosting it, on your main domain → 127.0.0.1:3000

Use Let's Encrypt or Caddy automatic TLS so the wss:// endpoint is secure, then firewall ports 3000 and 3001 so only the proxy can reach them.

8. Go live

Prefer Docker?

cd /opt/ed5
docker build -f packages/game-server/Dockerfile -t ed5-game .
docker run -d --restart=always --env-file .env -p 3001:3001 ed5-game

The . at the end is important — the build needs the whole workspace, not just the server folder.

Keep admin private

Troubleshooting