Install the YAVTT Server

This folder contains everything you need to run the YAVTT server with Docker. Pick the path that matches your setup, follow the steps, and you'll have a running server in a few minutes.

What you need

• A VPS or a home server that run 24/7; or you can host it on the same PC your client uses, but it is suggested to deactivate the server with docker compose down when you do not need it.
• Docker and the Docker Compose plugin installed. Follow the official Docker docs: https://docs.docker.com/engine/install/ for Linux; https://docs.docker.com/desktop/ for Windows and Mac.
• Optional but recommended: a domain name pointing at your machine, so players connect to yavtt.example.com instead of an IP.

You do not need to clone the YAVTT repository.

The yavtt-server image is multi-arch (x86-64 and arm64), so a Raspberry Pi or other arm64 host pulls the right build automatically!

Pick your path

There are two ways to run YAVTT:

Path	When to pick it
A. Behind a reverse proxy (recommended)	You already run, or plan to run, Nginx Proxy Manager (NPM), Caddy, Traefik, plain Nginx, … in front of your services. This is the suggested way: you get HTTPS and ease of use but you need a domain name and slightly more tinkering.
B. Standalone	If you only host YAVTT and don't want the complexity of a proxy. Traffic is HTTP-only; players connect via http://your-ip:8000. Note: your public IP can change!

If unsure: pick A with Nginx Proxy Manager, as it's a one-click admin UI for the proxy and handles HTTPS via Let's Encrypt automatically.

---

Path A — Behind a reverse proxy

A.1 Set up the proxy first (skip if you already have one) and the yavtt server

If you don't already run a reverse proxy, the easiest is Nginx Proxy Manager (NPM). In that case, create a folder of your choosing, create a docker-compose.yml file and copy the contents of docker-compose_reverse.yml inside it.

Then, create a .env file and copy the contents of .env.example inside it. Make sure to change the passwords and to generate a JWT token following the simple instructions inside .env.example.

Now you can spin up your docker containers with docker compose up -d in your terminal.

Open http://your-server-ip:81 and log in with the default credentials (admin@example.com / changeme). NPM will force you to change them. Important: in your router or cloud firewall, port-forward / allow ports 80 and 443 to your machine. If you do not do this, you will not be able to access the admin UI.

To check if yavtt-server is working, paste this command into your terminal: docker compose logs -f yavtt-server; once you read Uvicorn listening on port 8000, the server is ready.

Note: if you already have a reverse proxy, you'll have to slightly modify the docker-compose settings.

A.2 Tell the proxy about YAVTT

If you have a domain: add an A record for yavtt.example.com pointing at your machine's public IP.

In NPM's admin UI:

1. Go to Hosts → Proxy Hosts → Add Proxy Host.
2. Domain Names: yavtt.example.com (or whatever you chose).
3. Forward Hostname / IP: yavtt-server (the container name. Remember npm and the yavtt-server must be on the same network!).
4. Forward Port: 8000.
5. Block Common Exploits: on.
6. Websockets Support: on (required — game sessions use WebSockets).
7. SSL tab: select Request a new SSL Certificate, tick Force SSL, HTTP/2 Support, agree to Let's Encrypt's terms, save.

Done. To check if it is working, use your browser to go to yavtt.example.com. If you see a "Welcome to YAVTT!" message, you're all set! Connect with the YAVTT client to yavtt.example.com.

---

Path B — Standalone (no reverse proxy)

B.1 Set up yavtt-server

Create a folder of your choosing, then create a docker-compose.yml file and copy the contents of docker-compose_noreverse.yml inside it.

Then, create a .env file and copy the contents of .env.example inside it. Make sure to change the passwords and to generate a JWT token following the simple instructions inside .env.example. You can skip the NPM_DATABASE_PASSWORD variable.

Now you can spin up your docker containers with docker compose up -d in your terminal.

To check if yavtt-server is working, paste this command into your terminal: docker compose logs -f yavtt-server; once you read Uvicorn listening on port 8000, the server is ready.

B.2 Open your ports

To allow your server to communicate with the Internet, you must open up the port 8000. If you are on your home server or on your PC, go to your router admin panel and open up the port 8000. If you are on a VPS, you'll have to follow that VPS docs to open port 8000.

Now try to connect to http://your-ip:8000 through your browser. If you read "Welcome to YAVTT!" then you're all set!

Day-to-day operations

Check what's running

docker compose ps

View logs

docker compose logs -f yavtt-server     # live tail; Ctrl+C to exit
docker compose logs --tail=200 yavtt-db

Update to a newer YAVTT version

Edit docker-compose.yml, change the image tag (e.g. codeberg.org/derto/yavtt-server:0.1.0 → :0.2.0), then:

docker compose pull
docker compose up -d

Your data (./yavtt_data, ./yavtt_systems, and ./yavtt_postgres_data) is preserved across upgrades. WARNING: even if you data remains, up until version 1.0 of YAVTT, there is NO GUARANTEE you will be able to safely migrate your adventures.

Starting from 1.0.0, every major version will guarantee backward compatibility. Remember: right now YAVTT is in an Alpha-state, so be wary!

Stop / start

docker compose stop          # stop without removing
docker compose start         # start back up
docker compose down          # stop and remove containers (data persists)

Back up

All persistent data lives in three folders next to docker-compose.yml:

• ./yavtt_postgres_data: the entire database
• ./yavtt_data: user-uploaded assets (maps, portraits, etc.) and journals
• ./yavtt_systems: installed game systems (downloaded from Plaza)

Stop the stack first (docker compose stop), then:

tar czf yavtt-backup-$(date +%F).tar.gz yavtt_postgres_data yavtt_data yavtt_systems

Start it back up. Keep at least one backup off-site.

Migrating from YAVTT-IS (Integrated Server)

If you started on YAVTT-IS, the all-in-one binary that runs the client, server, and database together, and now want a real server, you can move everything across. On the YAVTT-IS host, export a migration archive (Client Settings → Move to a hosted server). Then, on a fresh deployment here (compose file + .env set up, but not yet serving), place both the archive and migrate_in.sh (from this docker/ folder) next to your compose file, then run:

chmod +x migrate_in.sh
./migrate_in.sh yavtt-migration-<version>-<date>.tar.gz

It restores the database, places the uploads and systems, and carries the JWT secret into .env. The server image must be the same release or newer than the YAVTT-IS binary.

Uninstall and delete everything

docker compose down
rm -rf yavtt_postgres_data yavtt_data yavtt_systems .env docker-compose.yml

---

Troubleshooting

Connection refused from the client — check docker compose ps: both yavtt-server and yavtt-db should be in Up state. If yavtt-server is restarting, docker compose logs yavtt-server usually shows why.

Players can connect but the session never starts — almost always WebSocket support is off on the reverse proxy. Toggle "Websockets Support" on NPM's Proxy Host edit page.

Database password change — Postgres locks the password at first init. Changing POSTGRES_PASSWORD in .env after the DB exists has no effect. To actually rotate: connect with docker compose exec yavtt-db psql -U <user> <db> and run ALTER USER <user> WITH PASSWORD 'new', then update .env to match.