Run a server

A Playmat server is four containers started with Docker Compose: the XMage game server, Caddy serving the web client over HTTPS, a cache for card pictures, and a nightly backup. You don't build anything: the images are published for x86 and ARM.

What you need

A Linux machine with Docker Engine and the Compose plugin (docker compose version answers). Docker Desktop on a Mac or Windows works too, but the Update button needs Linux.
About 1 GB of memory for the server; 2 GB leaves room. One CPU is enough for a group's evening.
A domain name pointed at the machine, with ports 80 and 443 open, so Caddy can get a certificate. For a group on one home network you can do without one: see Private server on a LAN.

Install

# get the compose file and its settings
git clone https://github.com/arcanite24/playmat.git
cd playmat
cp ops/web/.env.example ops/web/.env

# edit ops/web/.env (below), then start it
docker compose -f ops/web/docker-compose.yml --env-file ops/web/.env up -d

The first start pulls the images and takes a minute or two. Then open https:// and your domain.

Settings to set first

All settings live in ops/web/.env; empty ones use the defaults. These are the ones to look at before the first start:

Setting	What it does
`DOMAIN`	The server's address, without `https://`. Required.
`XMAGE_AUTH`	`true` makes players register with a password. Use it on any server others can reach; staff roles and Career need it.
`XMAGE_OWNER`	The account name of the server's owner. Register that name first: it gets the admin console, with every staff tool.
`XMAGE_ADMIN_PASSWORD`	A break-glass password for the admin console, for when no owner can sign in. Leave it empty to turn that off.
`XMAGE_SERVER_IMAGE`, `XMAGE_WEB_IMAGE`	The images to run. The example file names the newest build of `master`; leave them as they are.

Mail (for password resets), Discord notifications, registration rules and the rest are in the settings table. After changing .env, run the same up -d again to apply it.

If the game server runs out of memory, it stops and Docker starts it again within seconds (games in progress end). To find out what filled it, set XMAGE_HEAP_DUMP=true: the next time it writes the memory to logs/heap-oom.hprof in the logs volume. XMAGE_MEMORY sets the memory size.

After the first start

Open your domain and register the account named in XMAGE_OWNER.
Find Admin in the account menu. Its Overview shows the server's load, and Updates says whether it's up to date.
To update from there with one button later, turn on the updater.

On a machine with 1 GB of memory, add the small-VPS preset first: cat ops/web/small-vps.env >> ops/web/.env. It lowers the limits to what one CPU keeps responsive. See Small VPS.

Building the images yourself

To run your own changes, empty XMAGE_SERVER_IMAGE and XMAGE_WEB_IMAGE in .env and start with up -d --build. The first build compiles every card and takes tens of minutes; it needs more than 1 GB of memory.