Work-Adventure/install

Introduction

Since early 2021, Techinc hosts an 'instance' of Work-Adventure on play.social.techinc.nl.

[Work-Adventure] can be described as a spatially-enabled meet/chat space in an environment that is akin to 16-bit RPG games from the 90's. It allows text-based messaging, has direct web-rtc enabled video/audio chats available for up to 4 people in eachother's vincinity, as well as providign mechanisms to have 'rooms' of more participants by leveraging a [JITSI] server of choice.

The software has been designed by [The Coding Machine] and is released on their [github repo] as open source. The release is fully functional, apart from lacking an authentication/management backend that would allow restricting access, moderation, administrator-rights, etc. The API is documented however, and creation of a custom backend seems relatively easy to do.

By default, installing the github-provided release is most easily done via their included 'docker-compose.yaml', as listed on the README.MD file in the repo. While the mechanism works well, it lacks instructions on how to configure and run the software in a publically-accessible context instead of just on 'workadventure.localhost' as the README.MD explains you how to do.

The challenge for newcomers to docker comes with the way that the software is composed from multiple moving parts that are all required to be started alongside eachother. This is true of Work-Adventure itself which starts 4 service-containers all on its own; but becomes even more clear when you also want to host the JITSI-instance locally (instead of relying on jitsi.meet) and you want to use ssl-certs to make things work properly, as webrtc and CORS is rather picky about non-https content loaded into https-enabled sites.

All of the above can make an installation of work-adventure (with, or without Jitsi locally) a challenging endevour. This guide hopes to give some aid in understanding and configuring the infra.

Parts

Work-adventure

Work-adventure is found [on github] as a project deployed through 'docker-compose'. You do not need to know exactly the role of each container to get it to work with the install-guide supplied later, but it is handy to understand 'reverse-proxy', 'front' and 'maps', mainly. There is a '.env.template' file that should be copied to '.env' and edited for settings. (more about this later).

By default, the docker-compose file provisions the following containers:

• reverse-proxy: a 'traefik:v2.0' container from the public docker repo's. This is an auto-configuring proxy-service that can be crucial in getting things to run smoothly. Understanding what it does can be crucial to getting work-adventure and jitsi to work. This guide contains info about this, later.
• front: based on a 'node-js' image from TheCodingMachine docker-repo. Runs code for the interface part of the game. Has sprites for characters, login-screens, menu's, etc.
• pusher: tbd
• maps: Serves the 'map' files via an apache server. No active components
• back: tbd
• uploader: tbd
• messages: A container without a need of being reachable from the outside world; internally used to distribute/sync ProtoBuf messaging format between instances (i think)
• coturn: provides a TURN-server to allow NAT-traversal for those behind restricted/crippled networks. (not enabled yet on techinc infra; we use a public one)

JITSI

Jitsi is easily installed using [their github-repo for a docker-compose install]. There is an 'env.example' file that should be copied to .env and edited (more about this later).

Their docker-compose file provides the following containers:

• web: The frontend-service that clients talk to
• prosody: The XMPP service that carries text-messages and internal system-messages between parts.
• jicofo: Jitsi COnference FOcus; a part responsible in organizing video-connections between participants and the JitsiVideoBridge (jvb)
• jvb: The Jitsi Video Bridge server serves as a router for video-data; reducing bandwidth-load on participants.

Of note is that the jitsi-setup does not provide a config for use with Traefik by default, though there are some examples provided in 'examples' for traefik and kubernetes. Inspiration from these have been used to create a working docker-compose file using traefik v2.0 in a way that works well with Work-adventure

Understanding Docker and Traefik

If you are familiar with Traefik and docker, you can likely skip all this. If it is your first run-in with either, this chapter is likely essential to make any sense of what is going on in the install-instructions further on; though they will likely work well enough, regardless.

tbd.

Installation instructions

Pre-requisites and config

The setup instructions are written with the following assumptions in mind:

• you have a domain-name you have control over
• You have publically reachable IPv4 space
• You have a VM or physical hardware you want to dedicate to running jitsi+WA infra

It is likely other scenarios can be made to work, like hosting it on a DSL-line at home, with proper port-forwarding on your modem, or wanting to run the infra on a machine that also runs web-based services outside of a docker-context. These are definately possible, but are hard to cater for in this guide. Understanding the parts and how they go together will enable you to get things to work , however.

First steps:

• Set a wildcard DNS-record for *.whatever.your.domain.is to the publically reachable IP of the machine you want to host it on. Using a CNAME record works fine. It might be good to set TTL to 5mins at first
• Create a directory for all the parts we'll be installing (This guide assumes /opt for all of this)
• Install docker and docker-compose with apt-get install docker docker-compose if under a debian-like OS

Running Traefik and configuring docker-networking

By default, a container running traefik is started through the docker-compose.yaml file included with the work-adventure repo.

It is suggested to run any infra-structure that is shared between Jitsi and Work-adventure separately from either of them.

Currently the obvious candidates are:

• reverse-proxy: traefik, also handles LetsEncrypt
• coturn: a TURN-server for NAT-breaking, primarily used by Jitsi, but possibly also WorkAdventure (or other apps you might want to run on your instance)

We'll create a /opt/traefik-infra directory for this purpose

# mkdir /opt/traefik-infra

Now go into the traefik-infra directory and create 'docker-compose.yaml' file with the following contents:

version: '3'

services:
    reverse-proxy:
      image: traefik:v2.3
      command:
        - --log.level=WARN
        #- --api.insecure=true
        - --api.dashboard=true
        - --providers.docker.network=web
        - --providers.docker
        - --entryPoints.web.address=:80
        - --entrypoints.web.http.redirections.entryPoint.to=websecure
        - --entrypoints.web.http.redirections.entryPoint.scheme=https
        - --entryPoints.websecure.address=:443
        - --entryPoints.video.address=:10000/udp
        - --certificatesresolvers.le.acme.email=${ACME_EMAIL}
        - --certificatesresolvers.le.acme.storage=/etc/traefik/acme/acme.json
        # used during the challenge
        - --certificatesresolvers.le.acme.httpchallenge.entrypoint=web
      ports:
        - "80:80"
        - "443:443"
        # The Web UI (enabled by --api.insecure=true)
        - "8080:8080"
      volumes:
        - /var/run/docker.sock:/var/run/docker.sock
        - "${CERT_LOCATION}:/etc/traefik/acme"
      restart: unless-stopped
      labels:
        - "traefik.enable=true"
        - "traefik.http.services.traefik.loadbalancer.server.port=888"
        - "traefik.http.routers.traefik.rule=Host(`admin.${DOMAIN}`)"
        - "traefik.http.routers.traefik.entrypoints=websecure"
        - "traefik.http.routers.traefik.tls.certresolver=le"
        - "traefik.http.routers.traefik.service=api@internal"
        - "traefik.http.routers.traefik.middlewares=traefik-auth"
        - "traefik.http.middlewares.traefik-auth.basicauth.users=admin:$$apr1$$yg1Ttw8S$$GcHPvbYsLL1nsfULFHhpy1"
      networks:
        web:
        meet.jitsi:

# Still working on a useful COTURN setup. Included for later use.
#    coturn:
#      image: coturn/coturn:4.5.2
#      command:
#        - turnserver
#        - --log-file=stdout
#        - --external-ip=$$(detect-external-ip)
#        - --listening-port=3478
#        - --min-port=10000
#        - --max-port=10010
#        - --tls-listening-port=5349
#        - --listening-ip=0.0.0.0
#        - --realm=coturn.${DOMAIN}
#        - --server-name=coturn.${DOMAIN}
#        - --lt-cred-mech
#        # Enable Coturn "REST API" to validate temporary passwords.
#        # - --use-auth-secret
#        # - --static-auth-secret=SomeStaticAuthSecret
#        # - --userdb=/var/lib/turn/turndb
#        - --user=workadventure:WorkAdventure123
#        # use real-valid certificate/privatekey files
#        # - --cert=/root/letsencrypt/fullchain.pem
#        # - --pkey=/root/letsencrypt/privkey.pem
#      network_mode: host
 
networks:
  meet.jitsi:
  web:
    external: true

Create the file .env with the following contents:

DOMAIN=some.domain.tld
# These are not used yet
TURN_SERVER=
TURN_USER=
TURN_PASSWORD=

# The email address used by Let's encrypt to send renewal warnings (compulsory)
ACME_EMAIL=my_letsencrypt_contact@email.addressA
# The directory on your OS that Traefik will store all ACME-produced certs in
CERT_LOCATION=/etc/traefik/acme

Now, we will need to create one

Work-Adventure

Installing work-adventure is as simple as:

• Pulling the [workadventure github repo]
• Copying the .env.example file to .env and editing it (changing settings and adding some new ones)
• Replacing the docker-compose.yaml file by an edited with the following changes:
  • Has understanding for the '$DOMAIN' environment variable
  • Has 'traefik' removed from it (we are running one already)
  • Has 'coturn' remove from it (we are running one already)

Jitsi

A general guide for running JITSI via DOCKER can be found [here]

Installing Jitsi is as simple as:

• Pulling the [Jitsi Docker repo] from github
• Copying the env.example file to .env
• Running a script that creates random passwords for between the JITSI parts (./gen-passwords.sh)
• Editing .env file. Most importantly the PUBLIC_URL setting
• Creating a set of CONFIG dirs (see guide-url above)
• Replacing docker-compose.yaml file with one adjusted for our setup

Reference material

• [Work-adventure github issue introducing better/easier configuration]