GitHub - Arata1202/WorkAdventure: A collaborative web application (virtual office) presented as a 16-bit RPG video game

Getting Started

This guide supports both AWS EC2 and Azure VM with Terraform.

Prepare Repository

# Local and VM

# Clone repository
git clone https://github.com/Arata1202/WorkAdventure.git
cd WorkAdventure

# Install dependencies
make wa-init

Create Resources with Terraform

# Local

# Move to repository
cd WorkAdventure
cd terraform/aws # or terraform/azure

# Prepare and edit local values
cp terraform.tfvars.example terraform.tfvars
vi terraform.tfvars

# Create resources
terraform init
terraform plan
terraform apply

Connect AWS EC2 with SSM

Default for AWS is SSM.

# Local

# Configure AWS CLI credentials and region before connecting
aws configure

# Connect to AWS EC2 via SSM
aws ssm start-session --target <EC2_INSTANCE_ID>

# Switch to ubuntu user
sudo -iu ubuntu

Configure SSH Access

Default for Azure is SSH (Azure Bastion can be costly).

# Local

# Save the VM private key
vi ~/.ssh/workadventure_key.pem
chmod 600 ~/.ssh/workadventure_key.pem

# Configure SSH host aliases
vi ~/.ssh/config

Host workadventure
  HostName <VM_PUBLIC_IPV4_ADDRESS>
  User ubuntu
  IdentityFile ~/.ssh/workadventure_key.pem

# Local

# Connect to VM via SSH
ssh workadventure

Set Up WorkAdventure Server

# VM

# Set up Ubuntu
./ubuntu/setup.sh

# Move to repository
cd WorkAdventure

# Remove existing .env file
rm -f .env

# Generate random strings for .env values
openssl rand -hex 16
openssl rand -hex 32

# Prepare and edit .env file
cp .env.example .env
vi .env

# Encrypt .env file
make encrypt

# Start services with the basic configuration.
# For production, prefer the recommended initial production setup in this section.
make up

# Required
SECRET_KEY=<UNIQUE_RANDOM_64_HEX>
DOMAIN=<YOUR_FQDN>
MAP_STORAGE_AUTHENTICATION_TOKEN=<UNIQUE_RANDOM_64_HEX>
MAP_STORAGE_AUTHENTICATION_USER=admin
MAP_STORAGE_AUTHENTICATION_PASSWORD=<UNIQUE_RANDOM_32_HEX>

Add an A record in your DNS provider to point your domain to the VM public IP

Record Name	Type	Value	TTL
<YOUR_FQDN>	A	<VM_PUBLIC_IPV4_ADDRESS>	300

Recommended Initial Production Setup

Use this flow for a new production server before the first start.
Start from a clean .env, add all values from the sections you plan to use, then start the stack once.
Run the Synapse commands only when Matrix is configured.

# VM

# Move to repository
cd WorkAdventure

# Prepare a clean .env file for initial setup
rm -f .env
cp .env.example .env

# Edit .env once with all values from the sections you plan to use
vi .env

# Encrypt .env file
make encrypt

# Prepare Synapse data volume when Matrix is enabled
npx dotenvx run -- docker compose run --rm --user root --entrypoint sh synapse -lc 'chown -R 991:991 /data'

# Start services with the completed .env
make up-f

# Create a Matrix Admin User when Matrix is enabled
npx dotenvx run -- sh -lc 'docker compose exec synapse register_new_matrix_user -c /data/homeserver.yaml -u "$MATRIX_ADMIN_USER" -p "$MATRIX_ADMIN_PASSWORD" --admin http://localhost:8008'

Edit .env file for basic settings

# VM

# Move to repository
cd WorkAdventure

# Edit .env file
make decrypt
vi .env
make encrypt

# Restart server
make up-f

# Required
TZ=Asia/Tokyo

# Optional
ACME_EMAIL=<EMAIL_ADDRESS>
ENABLE_TELEMETRY=true
SECURITY_EMAIL=<EMAIL_ADDRESS>
FEATURE_FLAG_BROADCAST_AREAS=true

Upload a Map Edited with Tiled

https://docs.workadventu.re/map-building/tiled-editor/publish/wa-hosted

# Local

# Move to repository
cd WorkAdventure

# Prepare .env file
cp maps/.env.example maps/.env

# Preview the map locally
make wa-dev

# Edit the map file (maps/office.tmj) using Tiled

# Upload the map
make wa-upload

Please enter your Map storage URL: https://<YOUR_FQDN>/map-storage/
Please enter your API Key: <MAP_STORAGE_AUTHENTICATION_TOKEN>
Upload directory: maps

# VM

# Move to repository
cd WorkAdventure

# Edit .env file
make decrypt
vi .env
make encrypt

# Restart server
make up-f

# Required
START_ROOM_URL=/~/maps/office.wam
MAP_STORAGE_ENABLE_BEARER_AUTHENTICATION=true

Access the uploaded map https://<YOUR_FQDN>

Set Up GitHub Actions

Configure GitHub Actions secrets for upload-wa-maps.yml

# Required
UPLOAD_MODE=MAP_STORAGE
MAP_STORAGE_URL=https://<YOUR_FQDN>/map-storage/
MAP_STORAGE_API_KEY=<MAP_STORAGE_AUTHENTICATION_TOKEN>
UPLOAD_DIRECTORY=maps

Configure GitHub Actions secrets for deploy.yml

Note

The deploy.yml workflow requires direct SSH access and is not compatible with the default AWS SSM setup.

# Required
SSH_HOST=<VM_PUBLIC_IPV4_ADDRESS>
SSH_USERNAME=ubuntu
SSH_PRIVATE_KEY=<SSH_PRIVATE_KEY>

Run the deploy workflow manually from GitHub Actions to apply repository changes to the VM

Set Up Microsoft Entra ID OIDC

For Google OIDC, see Set Up Google OIDC.

Access Microsoft Azure portal
Go to Microsoft Entra ID -> App registrations
Create a new registration
- Name: WorkAdventure
- Supported account types: Accounts in this organizational directory only
- Platform: Web
- Redirect URI: https://<YOUR_FQDN>/openid-callback
Open Authentication and add another Web redirect URI
- Redirect URI: https://matrix.<YOUR_FQDN>/_synapse/client/oidc/callback
Open Certificates & secrets and create a new client secret
Open Token configuration and add the email optional claim
- Token type: ID
- Claim: email
- Keep Turn on the Microsoft Graph email permission enabled
Save the following values
- Application (client) ID
- Directory (tenant) ID
- Client secret Value (not the Secret ID)

# VM

# Move to repository
cd WorkAdventure

# Edit .env file
make decrypt
vi .env
make encrypt

# Restart server
make up-f

# Required
OPENID_IDP_ID=microsoft
OPENID_IDP_NAME=Microsoft
OPENID_CLIENT_ID=<APPLICATION_CLIENT_ID>
OPENID_CLIENT_SECRET=<CLIENT_SECRET_VALUE>
OPENID_CLIENT_ISSUER=https://login.microsoftonline.com/<DIRECTORY_TENANT_ID>/v2.0
OPENID_LOGOUT_REDIRECT_URL=https://<YOUR_FQDN>
OPENID_USERNAME_CLAIM=preferred_username
OPENID_SCOPE=openid email profile

# Optional
DISABLE_ANONYMOUS=true

Set Up LiveKit

# VM

# Move to repository
cd WorkAdventure

# Generate random strings for .env values
openssl rand -hex 32

# Edit .env file
make decrypt
vi .env
make encrypt

# Restart server
make up-f

# Required
LIVEKIT_HOST=https://livekit.<YOUR_FQDN>
LIVEKIT_API_KEY=<UNIQUE_RANDOM_64_HEX>
LIVEKIT_API_SECRET=<UNIQUE_RANDOM_64_HEX>

# Optional
MAX_PER_GROUP=<NUMBER>

Add an A record in your DNS provider to point your domain to the VM public IP

Record Name	Type	Value	TTL
livekit.<YOUR_FQDN>	A	<VM_PUBLIC_IPV4_ADDRESS>	300

Set Up Coturn

# VM

# Move to repository
cd WorkAdventure

# Generate random strings for .env values
openssl rand -hex 32

# Edit .env file
make decrypt
vi .env
make encrypt

# Restart server
make up-f

# Required
TURN_SERVER=turn:<YOUR_FQDN>:3478,turns:<YOUR_FQDN>:5349
TURN_STATIC_AUTH_SECRET=<UNIQUE_RANDOM_64_HEX>
STUN_SERVER=stun:stun.l.google.com:19302

Set Up Matrix

# VM

# Move to repository
cd WorkAdventure

# Generate random strings for .env values
openssl rand -hex 16
openssl rand -hex 32

# Edit .env file
make decrypt
vi .env
make encrypt

# Prepare Synapse data volume
npx dotenvx run -- docker compose run --rm --user root --entrypoint sh synapse -lc 'chown -R 991:991 /data'

# Restart server
make up-f

# Create a Matrix Admin User
npx dotenvx run -- sh -lc 'docker compose exec synapse register_new_matrix_user -c /data/homeserver.yaml -u "$MATRIX_ADMIN_USER" -p "$MATRIX_ADMIN_PASSWORD" --admin http://localhost:8008'

# Required
MATRIX_API_URI=http://synapse:8008/
MATRIX_DOMAIN=matrix.<YOUR_FQDN>
MATRIX_PUBLIC_URI=https://matrix.<YOUR_FQDN>
MATRIX_ADMIN_USER=admin
MATRIX_ADMIN_PASSWORD=<UNIQUE_RANDOM_32_HEX>
MATRIX_REGISTRATION_SHARED_SECRET=<UNIQUE_RANDOM_64_HEX>
MATRIX_MACAROON_SECRET_KEY=<UNIQUE_RANDOM_64_HEX>
MATRIX_FORM_SECRET=<UNIQUE_RANDOM_64_HEX>
POSTGRES_DB=synapse
POSTGRES_USER=admin
POSTGRES_PASSWORD=<UNIQUE_RANDOM_32_HEX>

Add an A record in your DNS provider to point your domain to the VM public IP

Record Name	Type	Value	TTL
matrix.<YOUR_FQDN>	A	<VM_PUBLIC_IPV4_ADDRESS>	300

Log in to Matrix using Element

Access Element Web: https://element.io
Click Sign in -> Open Element web
Click Sign in
Enter your Matrix homeserver URL: https://matrix.<YOUR_FQDN>
Click Continue
Enter your Matrix credentials:
- Username: admin
- Password: <MATRIX_ADMIN_PASSWORD>
Click Sign in
After successful authentication, you will be redirected back to Element and logged in

Set Up Egress with RustFS

# VM

# Move to repository
cd WorkAdventure

# Generate random strings for .env values
openssl rand -hex 32

# Edit .env file
make decrypt
vi .env
make encrypt

# Restart server
make up-f

# Required
LIVEKIT_RECORDING_S3_ENDPOINT=http://rustfs-livekit:9000
LIVEKIT_RECORDING_S3_CDN_ENDPOINT=https://cdn-livekit.<YOUR_FQDN>
LIVEKIT_RECORDING_S3_ACCESS_KEY=<UNIQUE_RANDOM_64_HEX>
LIVEKIT_RECORDING_S3_SECRET_KEY=<UNIQUE_RANDOM_64_HEX>
LIVEKIT_RECORDING_S3_BUCKET=livekit-recordings
LIVEKIT_RECORDING_S3_REGION=ap-northeast-1
MAX_USERS_FOR_WEBRTC=0

Add A records in your DNS provider to point your domain to the VM public IP

Record Name	Type	Value	TTL
cdn-livekit.<YOUR_FQDN>	A	<VM_PUBLIC_IPV4_ADDRESS>	300
rustfs-livekit.<YOUR_FQDN>	A	<VM_PUBLIC_IPV4_ADDRESS>	300

Log in to RustFS

Access RustFS Console: https://rustfs-livekit.<YOUR_FQDN>
Enter your RustFS credentials:
- Username: <LIVEKIT_RECORDING_S3_ACCESS_KEY>
- Password: <LIVEKIT_RECORDING_S3_SECRET_KEY>
Click Sign in
After successful authentication, you will be logged in

Name		Name	Last commit message	Last commit date
Latest commit History 306 Commits
.github/workflows		.github/workflows
.husky		.husky
docs		docs
egress		egress
livekit		livekit
maps		maps
synapse		synapse
terraform		terraform
ubuntu		ubuntu
.env		.env
.env.example		.env.example
.gitattributes		.gitattributes
.gitignore		.gitignore
.rsyncignore		.rsyncignore
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
docker-compose.yaml		docker-compose.yaml
package-lock.json		package-lock.json
package.json		package.json

Navigation Menu

Repository files navigation

Getting Started

Prepare Repository

Create Resources with Terraform

Connect AWS EC2 with SSM

Configure SSH Access

Set Up WorkAdventure Server

Recommended Initial Production Setup

Edit .env file for basic settings

Upload a Map Edited with Tiled

Set Up GitHub Actions

Set Up Microsoft Entra ID OIDC

Set Up LiveKit

Set Up Coturn

Set Up Matrix

Log in to Matrix using Element

Set Up Egress with RustFS

Log in to RustFS

About

Contributors

Languages

Folders and files

Latest commit

History

Repository files navigation

Getting Started

Prepare Repository

Create Resources with Terraform

Connect AWS EC2 with SSM

Configure SSH Access

Set Up WorkAdventure Server

Recommended Initial Production Setup

Edit .env file for basic settings

Upload a Map Edited with Tiled

Set Up GitHub Actions

Set Up Microsoft Entra ID OIDC

Set Up LiveKit

Set Up Coturn

Set Up Matrix

Log in to Matrix using Element

Set Up Egress with RustFS

Log in to RustFS

About

Topics

Resources

Stars

Watchers

Forks

Contributors

Languages