Skip to content

Server setup

A Borne server is one program, borne-server, and a PostgreSQL database. Engine data (accounts, flags, scripts, bans) lives in PostgreSQL 15 or newer. Levels, images, and script databases live in a data folder.

  • PostgreSQL 15 or newer, and a database with a user that can create tables.
  • A folder for the data. The sample world in sample-world/ is a ready example.
  • A signing key and a cache secret for a public server (keys and TLS).
Terminal window
borne-server --config server.toml run

--config names the configuration file and defaults to server.toml in the current folder. A relative server.data_dir is resolved against the folder of that file. The environment variable BORNE_DATABASE_URL overrides database.url.

Every key is described in configuration; deploy/server.example.toml is a complete example to copy.

On the first start the server:

  1. connects to the database and applies the migrations in order. It refuses to start when the database has a newer migration than it knows;
  2. loads the scripts from the data folder when the database has none (weapons, NPCs, classes);
  3. creates a self-signed TLS certificate under <data_dir>/tls when you did not configure one, and prints its SHA-256 fingerprint. Give the fingerprint to your players;
  4. prints a hint with the grant-staff command when there is no staff account yet (staff bootstrap).

The server stops cleanly on SIGTERM. It stops accepting logins, logs every player out, writes everything to the database, and exits. It waits at most 30 seconds.

--dev allows plain ws:// connections from the same computer, generates a development cache secret, and, when security.signing_key is not set, signs scripts with the public development key that development client builds trust. Use it only on your own machine:

Terminal window
BORNE_DATABASE_URL=postgres://borne:change-me@localhost/borne \
borne-server --config sample-world/server.toml --dev run

deploy/docker-compose.yml starts the server and PostgreSQL, each with a named volume, and checks that they are healthy.

Terminal window
docker compose -f deploy/docker-compose.yml up -d --wait
docker compose -f deploy/docker-compose.yml down
  • Set POSTGRES_PASSWORD in the environment. The default change-me is for tests only.
  • Copy signing.key and cache.secret into the server-secrets volume. The volume is mounted read-only at /etc/borne/secrets.
  • The game port is 14900. PostgreSQL is not published.
  • deploy/docker-compose.sample.yml adds the sample world with generated development keys:
Terminal window
BORNE_UID=$(id -u) BORNE_GID=$(id -g) \
docker compose -f deploy/docker-compose.yml -f deploy/docker-compose.sample.yml up --wait

Stop the server, back up the database and the data folder (backups), install the new version, and start it. The migrations run by themselves.

Engine version 0.1.0. Built 2026-11-18.