Deploy WorkAdventure

Deploy and Host WorkAdventure on Railway

WorkAdventure is an open-source virtual office where your team gathers on a customizable 2D map. Each person controls a pixel-art avatar, and walking up to someone instantly opens a video and audio call with them. Maps can include meeting rooms, embedded websites, whiteboards and quiet zones, so remote teams get the casual conversations of a real office.

About Hosting WorkAdventure

WorkAdventure is made of several Node.js services: a front end and WebSocket server, a back end that holds room state, a map storage service, a chat upload service and a favicon service, all backed by Redis. The official setup routes them with Traefik, which reads the Docker socket. Railway has no Docker socket, so this template replaces Traefik with a small Caddy proxy that routes requests by path and adds a shared site password. Video calls run directly between browsers over WebRTC, which works best with an external TURN server because Railway does not support UDP.

Common Use Cases

• Giving a remote or hybrid team a shared virtual office for spontaneous conversations
• Hosting online events, meetups and workshops where attendees move between areas
• Running virtual classrooms or study spaces with group corners and presentation areas

Dependencies for WorkAdventure Hosting

• Official WorkAdventure Docker images: play, back, map-storage and uploader (pinned to v1.34.4)
• matthiasluedtke/iconserver for website favicons
• Railway Redis for map variables and chat uploads
• A Railway volume on the map storage service for uploaded maps
• A Caddy reverse proxy built from the template repository

Implementation Details

Services

Logging in

WorkAdventure has no login system of its own, so anyone with the URL could join. This template puts a shared password in front of the whole site:

• Username: ACCESS_USER on the proxy service (default workadventure)
• Password: ACCESS_PASSWORD on the proxy service (generated on deploy)

The password is asked once per browser and remembered for 30 days. Changing it signs everyone out. Leave ACCESS_PASSWORD empty to make the site public. Inside the game, each person picks their own display name.

Adding maps

New visitors land on WorkAdventure's starter office. To add your own maps, open https:///map-storage/ and log in with AUTHENTICATION_USER and AUTHENTICATION_PASSWORD from the mapstorage service. From there you can upload maps built with Tiled as a ZIP file, or link a map hosted elsewhere.

Each map has its own URL, such as https:///~/office.wam. To change the landing map, set START_ROOM_URL on the play service. To upload maps from your computer with the official map-starter-kit, use AUTHENTICATION_TOKEN from the mapstorage service as the API key.

What works and what doesn't

TURN server (video on strict networks). Video calls connect browsers directly. On mobile data or strict corporate networks, a direct connection is often impossible and the call needs a TURN relay server. TURN servers need UDP ports, which Railway does not offer, so one cannot run in this template. Without TURN, two people on ordinary networks can usually see each other, but someone on mobile data may not get video. To fix this, sign up for a hosted TURN service and set TURN_SERVER, TURN_USER and TURN_PASSWORD on both the play and back services.

Chat history. The built-in chat is a proximity chat for whoever is nearby. It is not saved by design and clears when the page reloads. Saved conversations, direct messages and chat rooms require a Matrix server (Synapse) with personal logins for every user. That adds several services and an identity provider, so it is not part of this template.

Map editor. WorkAdventure can edit maps inside the game, but without personal accounts it cannot tell users apart. Turning it on would let everyone who knows the site password change your maps. It is disabled with ENABLE_MAP_EDITOR="false" on play and back. Edit maps with Tiled and upload them through /map-storage/ instead.

Jitsi meeting rooms. Map areas marked as meeting rooms open a Jitsi call so everyone in the room shares one conversation. By default they use the public meet.jit.si server, which limits calls embedded in other sites to 5 minutes. Self-hosting Jitsi also needs UDP, so it cannot run on Railway. For longer meetings, set JITSI_URL on play and back to a Jitsi server you host elsewhere.

Personal accounts. Everyone shares the same site password. Per-person logins require connecting an OpenID Connect provider such as Google Workspace or Keycloak through the OPENID_* variables on the play service.

Deploy into a new project. The services connect to each other over IPv4, which Railway's private network supports in environments created after October 16, 2025. Every new deploy of this template meets this requirement.

Updating. The WorkAdventure images are pinned to a release. To upgrade, change the image tag on play, back, mapstorage and uploader to the same new version, and keep all four on the same version.

Why Deploy WorkAdventure on Railway?

Railway is a singular platform to deploy your infrastructure stack. Railway will host your infrastructure so you don't have to deal with configuration, while allowing you to vertically and horizontally scale it.

By deploying WorkAdventure on Railway, you are one step closer to supporting a complete full-stack application with minimal burden. Host your servers, databases, AI agents, and more on Railway.