[Skip Introduction and directly jump to step-by-step guide]
Workadventure (WA) is a cool interactive meeting and collaboration tool in the design of a pixel RPG.
As you visit this blog article you probably already know.
As it is under a licence that allows Self-Hosting, you can setup your own workadventure server, for you, your friends, or your company, to reach maximum flexibility.
The Wokadventure Coding team provides a production ready docker-compose file that already did the most work for you.
Although there is the compose file, no step-by-step guide is given in the README how to bring the instance alive.
There are some community tutorials, but the process is much easier now.
I dont really understand why they don’t provide one (maybe it’s because very easy self hosting is against their own economic interest or because they think it’s kind of very intuitive), but I want to share the steps you need to do to set up the most basic version on your own.
Circumstances:
- Date: 27.7.22
- Latest WA Release Tag: v1.11.4
- Last WA GitHub Master Update: 21.7.22
- Operating System: Ubuntu 20.4 LTS
- RAM: 4 GB
- Storage: 16 GB
- Open Ports: 22, 80, 443
- Installed additional Software: docker (20.10.17)
I’m sure these specifications aren’t really critical.
I guess new release versions of WA will work as well as other (debian based) Unix Systems.
Feel free to comment if you tested (successfully or not) under other circumstances to easify others work :)
Successfully Tested
System:
- Raspberry Pi 4 B (4GB, Raspberry Pi OS Lite 64-bit v22.4.4)
DNS Provider:
- dynu.com (dynamic DNS)
Unsuccessfully Tested
System:
- Raspberry Pi 4 B (4GB, Raspberry Pi OS Lite 32-bit v.22.4.4)
→ As Workadventure is not shipping their docker images for ARMv7/32- bit Systems
Start by cloning the workadventure github repo into your home directory:
cd
git clone https://github.com/thecodingmachine/workadventure.gitWhen checking your directory with ls you should see the workadventure folder.
Now head to the directory with the production docker compose file and change to the master branch.
cd ~/workadventure/contrib/docker/
git switch masterYou now should have the right files in front of you.
Approve by typing git status
Copy the .env.prod.template file to .env with cp .env.prod.template .env
Now edit the .env file in your favorite editor.
I prefer using an IDE like VS Code, where you can connect to a machine via the ssh extension to work on files, but you can also use tools like WinSCP or stay with good old vi or nano.
As we won’t change much, they are totaly fine.
In the most easy setup we just need to edit 7 variables.
First, replace all appearances of workadventure.localhost with your domain.
For example with wa.mynicesite.org (if you have not yet registered a domain, follow the digression in the next section and come back here when done).
I prefer using CTRL+F in VS Code to do that.
After that, you just need to edit the ACME_EMAIL variable at the lower-middle of the file. Just enter one of your mail adresses you want to use.
Don’t forget to save the file :)
Digression — Register a Domain
If you don’t know anything about DNS, it’s worth learning the basics before going on, but it will also work without.
What we need to register is a wildcard-A-record that maps every subdomain under another (sub-) domain, do a dedicated IP.
You can also use CNAMEs.
As an example, we want the domains play.wa.mynicesite.org, pusher.wa.mynicesite.org, maps.wa.mynicesite.org, … to point to the same IP adress.
So we head to our provider and add the A record *.wa.mynicesite.org that has our IP adress (of the machine we currently work on with ssh) 123.45.67.89 as value.
This kind of record is offered by nearly every provider for classic and dynamic DNS.
As I am using Open Telekom Cloud (OTC) and they have DNS included, I don’t need to use an external services.
I maybe provide some guidance for free DynDns in the future, but I’m optimistic you know what to do on your service :)
When done, you just need to use compose to let docker build your workadventure instance, but be aware!
Do not just use sudo docker compose up , as this would use the development compose file from the root of the project, and not the compose file of the directory you are in.
Use the -f option to specify the file.
cd ~/workadventure/contrib/docker #make sure you're in the right dir
sudo docker compose -f ./docker-compose.prod.yaml upUse the -d flag to start docker compose in detached mode (“background”), but I recommend following the output on first start.
After a couple of secondes you will be able to reach your instance under play.wa.yournicesite.org. Happy Workadventure!
Appendix:
- Shut down instance in interactive mode using CTRL+C
andsudo docker compose -f ./docker-compose.prod.yaml down
Feel free to comment about your experiences with workadventure and about improvement suggestions.
