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 22 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#

Create the VPS, then install Node 22 and pnpm:

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

2. Export the server#

Open Build → Export Game in the studio, choose the Server target and the profile you're deploying (usually Production), then Build. You get a server-bundle/ folder containing exactly what a game server needs and nothing it doesn't:

• the workspace manifests, already trimmed of the monorepo's development scripts
• the server and every package it depends on, already built
• packages/db/drizzle/ — the migration SQL, which the server applies on every startup
• a .env.example prefilled from your build profile, and a README.md with these same deploy steps

Upload that folder to your VPS (/opt/ed5 in the examples below). That's the whole step.

The export deliberately leaves out node_modules/ (a Windows-resolved install can't run on Linux), the admin app (authoring tools never belong on a public server), your local database, and the ~137 MB of demo art packs — those only feed the first-boot starter world, which your published world replaces anyway. Want them anyway? Export from the CLI with --include-seed-assets, or copy packages/db/assets/ across later and point ED5_DB_ASSETS_DIR at it.

If pre-flight blocks the export, believe it. The Server target refuses to build an engine with no compiled server or no migration SQL, because both produce a bundle that starts perfectly and then behaves as if your database were empty.

Doing it by hand instead#

You don't need to, but the bundle isn't magic — it's a filtered copy of the engine tree in your Studio install (%APPDATA%\@ed5-mmo-studio\studio\engine\). If you copy it yourself, copy the root of that folder — the level containing package.json, pnpm-lock.yaml, pnpm-workspace.yaml, .npmrc and packages/ — and take packages/shared, packages/db (including drizzle/), packages/world-gen, packages/game-server and packages/plugin-sandbox. Skip node_modules/, apps/admin and data/. Add apps/client only if you're self-hosting the client too (see step 6).

Two traps the export exists to remove:

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.

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. It looks like a mysterious "the database is empty / tables don't exist" problem much later.

Copying by hand also brings the monorepo's root package.json along unchanged, whose prepare script runs husky on install — a devDependency that --prod doesn't install, so step 3 exits with an error. The exported bundle replaces those scripts with a single start.

3. Install dependencies#

From the bundle root on the VPS:

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 packages ship already built, so there is no compile step for the server. The trailing ... matters — it pulls in the workspace dependencies too.

4. Configure environment#

Create a .env file at the engine root (the same folder as package.json). The server walks up from its own location to find it.

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#

With DB_MODE=remote, a Supabase connection string is automatically routed through Supabase's transaction pooler (port 6543) with prepared statements disabled. That is the supported configuration — paste your normal Supabase connection string and let the server handle it. Don't force the direct 5432 endpoint.

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.

About media#

Your server serves every image, sheet and sound to players itself, out of its database. If the server has its own database, Publish sends it the bytes it is missing. If the server uses the same database as Studio (see One database or two? below), the media is already there and nothing is sent. Either way nothing is written to Supabase Storage — an empty Storage bucket in your Supabase project is expected, and the Media Manager's footer reads Remote: sent on Publish rather than a sync count. Cloud storage sync only exists for projects hosted on Studio Web.

One database or two?#

Both layouts are supported, and Publish works out which one you have:

With a shared database, Publish is the reload. The server keeps the copy of your world it read when it started, so an edit shows up in game after the next Publish (or a server restart) — not the instant you save it. The exception is a map object's or tileset's collision: those are pushed to a shared-database server as you save them.

5. Run it#

Start the server from the engine root — path resolution depends on 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?#

Usually not. You have two options:

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#

Put a reverse proxy (nginx, Caddy, or Cloudflare) in front and terminate TLS:

• 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

Forward the Upgrade and Connection headers on the game-server route. Without them, everything looks fine — the health check passes, the page loads — and players simply never connect. Caddy does this automatically; nginx needs it configured explicitly.

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#

With the server reachable over HTTPS/WSS, open your ED5 account dashboard, register the server under Connect your own VPS (its public URL + wss:// URL), then enable the public play link for your project and share it. See Publishing Your Game.

Pointing the desktop Studio at it#

In the desktop app the same address goes in Server Control → Connection → Use my own VPS:

1. Paste the server address, e.g. wss://your-server.com:3001, into Game server URL.
2. Paste the server's ADMIN_API_KEY (from its .env) into Admin API key.
3. Press Test. It asks the server whether it is up and whether it accepts the key, and tells you what is wrong if not.
4. Press Connect, then Restart editor now.

Publish answers "HTTP 401 Unauthorized"? The key is missing or wrong — the server is up and refusing the content. Paste the key and press Test. If Test still says rejected, check whether an ADMIN_API_KEY is also saved in the server's database settings (Settings → Server Settings): a value saved there wins over the .env file, so the server is expecting that one.

Pasting a raw IP with wss:// in front is the most common reason "the server is running but I can't connect": the connection fails at the TLS handshake before it ever reaches your game server. Use ws:// until the domain and certificate are in place.

Restart the editor afterwards. Studio hands the server address and key to the editor when the editor starts, so a freshly connected server is not picked up until then — press Restart editor now under the Connect button. Until you restart, publishes still go to the local server. You can confirm which one is live from the Server URL shown in Settings.

Clearing the URL and connecting again with it blank puts Studio back on its own embedded server.

What each Publish step means#

Open Server → Publish and press Publish. The steps run in order, and each one reports what it did:

A step timed out or showed "AbortError"? On engine versions before this fix, Publish pushed every definition and media row through the server even when the server already had them, and a large project could outlast the step's time limit. The server kept working after the editor gave up, which is why trying again a few minutes later seemed to work — and why the next step then timed out against a server that was still busy. Update Studio and your server, then Publish once; if a step still stalls, restart the server from Server → Restart before publishing again rather than stacking attempts.

A map is black in game? Open https://your-server/status. zones.withoutTerrain lists maps whose ground never reached the server — Publish, and Terrain chunks sends it. zones.terrainProblems lists every other case by map name, with the reason and what to do: the server could not read the map's ground from its database (load-failed — it tries again by itself while a player is waiting, so check the database is reachable), the map's rows hold no painted tile (no-usable-rows — open the map, check it has ground, publish), or a player was sent to a map that is not in the game (not-on-board, streamed-world-piece, unknown-map — Project Health lists what leads there). The server writes the same lines to its log, starting with Terrain problem —, and Publish repeats them under Apply on live server. If Maps & rendering and Terrain chunks read Shared DB — no push needed while your server uses a different database from Studio, update Studio — that message is only right when both read the same database.

What a save sends. When you save an item, ability, monster or other definition, Studio asks your server what it already holds and sends only the rows that differ — usually just the one you saved. Media, maps and map events still travel with Publish. If two updates reach your server at once, the newer one's rows are kept. A server exported before this was added still receives the whole table on each save, and can let an older update undo a newer one — export the server again and redeploy it.

Prefer Docker?#

The engine includes the same container definition our managed servers run. It handles the build, the production install, and shipping the migrations for you. Build it with the engine root as the build context:

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

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

Do not leave out the -v. Uploaded images and audio are stored as files under data/, inside the container. Without that volume they live and die with the container, so the next time you rebuild the image or re-run this command, every asset your game serves is gone — your media rows survive, but the files they point to don't, and the game starts answering No media bytes available. The volume keeps them on the VPS, where an upgrade can't reach them.

Upgrading your server#

Your world lives in two places, and an upgrade only ever replaces one of them. Your database holds the definitions, maps and media records. /opt/ed5/data holds the actual image and audio files (and, if you never moved to Postgres, the embedded database too). The engine itself is disposable; those two are not.

Before you upgrade, back both up:

tar czf ~/ed5-data-$(date +%F).tgz -C /opt/ed5 data
cp /opt/ed5/.env ~/ed5-env-backup

Then take a dump of your database — pg_dump for your own Postgres, or a snapshot from the Supabase dashboard.

Then upgrade without overwriting them:

Then check it worked, before you tell anyone the server is back:

If assets are missing, Publish once from Studio. Publish now compares your Media Library against the files the server actually holds on disk and uploads whatever it lacks, so a rebuilt server re-seats itself from your editor. You will see N file(s) sent on the Media manifest step. (This needs a server new enough to accept them; an older one skips it silently, and you can copy .ed5-media across by hand instead — the filenames are content hashes, so copying over the top is always safe.)

Publish is the repair tool. Because media files are stored under a hash of their own contents, sending them again is harmless and an interrupted publish simply picks up where it left off. If a server is serving No media bytes available, Publish is the first thing to try.

Keep a nightly copy anyway. Publish can re-seat your server's media from your editor, so your editor is a real second copy — but only of what is still in it. That one tar czf line in a cron job, plus a database dump, is what covers the case where the editor is the machine you lose.

Keep admin private#

The admin app (authoring tools, port 3002) and your database should never be publicly exposed. Author your world in Studio on your own machine and publish to the live server — you don't need admin running on the VPS at all.

Troubleshooting#