Workload · Hosting a Veloren world

A Veloren server of your own, kept in step with every weekly release

To host a Veloren server for a group, run the project's official server-cli image with Docker on an x86 Linux machine, let players in on TCP port 14004, make yourself admin from the server console, and set up the bundled updater (one setting is needed on current Docker) so the server follows the weekly releases and players on Airshipper can keep connecting. The steps below follow the Veloren book and Docker's own documentation, plus two edits to the sample file worth making before the address goes out.

The short version
  1. The official route: the server-cli Docker image on the weekly channel
  2. Port 14004 TCP for players; port 14005 stays off the internet
  3. Admin rights are granted only from the server console
  4. A whole x86 machine of your own, on an unmetered port

What the world asks of the machine

A Veloren server is one program, veloren-server-cli, that simulates the world and generates terrain for everyone connected; the Veloren book notes that in multiplayer this work moves off each player's computer and onto the server. The project publishes no minimum memory or processor figure. It does document the settings in settings.ron that decide how hard the machine works:

SettingWhat it changesValue in the book's example
max_playersHow many people can be in the world at once100
max_view_distanceHow far out the server sends terrain, so how much it keeps loaded around each playerSome(65)
map_fileThe bundled map, a newly generated one, or one you savedNone (the bundled map)
x_lg / y_lgGenerated world size: each step up doubles the length and roughly doubles generation time and memory10, the default

A custom world of standard size takes about ten minutes to generate on a good processor, the book says. Generate it once with Some(Save(())), then load the saved file, or the server rebuilds it at every start. The book puts that work on the server's processor, so size by processor first, then leave memory headroom.

Which ports to open, and which to keep shut

PortProtocolWhat it carriesOpen to the internet?
14004TCP, UDP if you enable itThe gameYes
14005TCPThe web interface and metricsNo: bind it to 127.0.0.1
14006UDPServer query, for Airshipper's list of active serversOptional

Docker's documentation warns that published container ports are reachable from outside by default and skip ufw's rules, so the ports list in docker-compose.yml is your real fence. If you also run ufw for other services, allow SSH before enabling it and keep its IPv6 handling on.

The machine that fits a Veloren world

A whole machine suits Veloren because the server does the world simulation and terrain generation for every player, and on a server of your own nobody else's job competes for the processor. Our game servers ranked by single-thread speed list every processor we sell that scores 2,000 or more on PassMark's single-thread test. For one world and a group of friends, the Intel Xeon E3-1585L v5 is the modest pick there: NVMe storage, 32 GB of memory, sold in all five cities. The many-core EPYC and Xeon Gold machines suit Veloren sharing the box with other game servers.

  • An unmetered port, not shared with another customer at the access switch, so a busy evening's terrain traffic is never counted.
  • Five cities: New York, Miami, San Francisco, Amsterdam and Bucharest. Time each one from your browser and pick the nearest to most players.
  • Monthly, no contract. A racked machine is yours about 30 minutes after the order is approved; the payment check comes first and is the part that varies.
  • x86 only. The book says the Docker version of the server will not run on ARM processors.

To try Veloren with two or three friends first, a Cloud VPS is a smaller start, but it is a virtual machine on a server shared with other customers, with vCPUs that are not pinned. Every whole-machine line is on the dedicated servers page.

Up and running in an evening

These steps follow the book's Docker guide, its route for a server that runs around the clock, on Ubuntu 24.04.

  1. Choose Ubuntu 24.04 on an x86 machine at checkout and log in over SSH once it is handed over.
  2. Install Docker Engine with the Compose plugin using Docker's instructions for Ubuntu. Current Docker spells it docker compose; the book's docker-compose is the Compose V1 spelling, which Docker stopped updating in July 2023.
  3. Make a folder and download the project's sample Compose file into it (first block below).
  4. Edit the file (second block): bind 14005 to 127.0.0.1, change restart: on-failure:0 to restart: unless-stopped under both services, and give the watchtower service the DOCKER_API_VERSION line explained further down. Docker's documentation says an on-failure container is not restarted when the daemon restarts, so after a reboot the world would stay down.
  5. Start it with sudo docker compose up -d and watch the first start with sudo docker logs veloren-game-server-master.
  6. Make yourself admin: run sudo docker attach veloren-game-server-master, type admin add yourname admin with your Veloren username, then leave with Ctrl+p followed by Ctrl+q. Not Ctrl+c: Docker passes that to the server and stops it.
  7. Give players the server's IP address to enter in the game's multiplayer screen.
mkdir -p ~/veloren && cd ~/veloren && wget https://gitlab.com/veloren/veloren/-/raw/master/server-cli/docker-compose.yml
  game-server:
    ports:
      - "14004:14004"
      - "127.0.0.1:14005:14005"
      - "14006:14006/udp"
    restart: unless-stopped
  watchtower:
    environment:
      - DOCKER_API_VERSION=1.44
    restart: unless-stopped

Settings to sort out before you share the address

The first start creates userdata beside the Compose file; its server/server_config folder holds the files below, and sudo docker compose restart game-server applies your edits.

  • settings.ron: server name, player limit, seed, view distance and map. Keep auth_server_address on the official service: the book warns that a custom one shows players a security warning, and that switching authentication off lets anyone log in under any name, an admin's included.
  • description.ron: message of the day and rules. Once rules are set, newcomers must accept them, and see them again after each change.
  • whitelist.ron: while it has any entry, only listed players can join. For a private group, add each friend with /whitelist add and their username before posting the address.
  • banlist.ron and admins.ron: bans by player and IP, and the admin list. Moderators use /kick, /ban with a duration such as 3d2h30m, and /unban.

Admin rights come only from the console or the files, so nobody can claim them by joining first. If you enable UDP for the game, add 14004:14004/udp to the Compose ports too; Docker publishes TCP unless told otherwise.

Keeping the server and players' clients on the same build

Your server has to follow the weekly releases, because that is what players' launchers install. When the Veloren team moved servers to the weekly channel, it wrote that Airshipper's client stays compatible as long as the server updates with those releases. The FAQ says an update should land every Thursday.

The sample file handles it: the image is tagged weekly, and a Watchtower container checks for a newer one every 30 seconds, stops the old server with a 130-second timeout and removes the replaced image. On current Docker Engine (29 and later) the sample's Watchtower image is too old to talk to the daemon and stops at once, so add DOCKER_API_VERSION=1.44 under an environment: list in the watchtower service (Watchtower's documented setting for this), then check it stays up with sudo docker compose ps. If it still exits, update by hand each Thursday: cd ~/veloren && sudo docker compose pull && sudo docker compose up -d. Before restarting, the server warns players and waits; update_shutdown_grace_period_secs (120) and update_shutdown_message in userdata/server-cli/settings.ron set how long and what it says. Pin an older version and every player needs a matching client. For your own maintenance, run shutdown graceful --reason "Back in ten minutes" 120 in the console for a two-minute countdown.

Backups and keeping an eye on it

Everything worth keeping is in userdata: the world database at server/saves/db.sqlite and every config file. Stop the game server so the database is not mid-write, archive the folder, start it again. The line below archives only if the stop succeeded, and starts the server either way:

cd ~/veloren && sudo docker compose stop game-server && sudo tar -czf "$HOME/veloren-userdata-$(date +%F).tar.gz" userdata; sudo docker compose start game-server

Copy each archive off the machine; a backup on the same disk goes when the disk does. Day to day, sudo docker logs veloren-game-server-master shows what the server is doing and sudo docker stats its memory and processor use, the honest way to size up once real players arrive. Leave experimental_terrain_persistence off unless you accept its warning: no guaranteed forwards-compatibility, and it may be removed with no migration.

When this is the wrong place to run it

  • Everyone plays in one house. The book's LAN guide runs the server on one of your own computers.
  • You want a game panel and someone to update it. You get the machine with root access; we do not install mods, panels or game updates.
  • You need ARM. The Docker image does not run there.

Questions people ask

Do my players need a Veloren account to join?
Yes, with the default settings. The server checks logins against the official account service, so one account from the Veloren website works on your world and every other server that keeps authentication on. Turning authentication off removes that step but lets anyone take any name, including yours.
How much memory should I give a Veloren server?
The project publishes no figure. Memory grows with player count, view distance and world size, and the book says each doubling of a generated world's dimensions roughly doubles the memory used to generate it. Start with headroom above the operating system and watch sudo docker stats once people play.
My friends updated their game and now cannot connect. Why?
Most likely the server is still on last week's build. Check with sudo docker compose ps in ~/veloren; if Watchtower keeps exiting, it needs the DOCKER_API_VERSION setting described above. Until then, cd ~/veloren && sudo docker compose pull && sudo docker compose up -d fetches the new image and restarts the server on it.
Can Veloren share a machine with other game servers?
Yes. Each game server is its own process on its own port, and Veloren needs only 14004, plus 14006 to appear in Airshipper's server list. Give each server a fast core and its own share of memory, and pick a processor with cores to go round.

Start your Veloren world

Pick a whole machine in the city nearest your players, and have the server-cli image running once it is handed over. Monthly, no contract, and a person on chat whenever you want one.

Find a server for your world

Read next