Installation Manual

Not supported anymore, but still available up to version 4.0.2 , there is a Windows-only installer, that installs all components (client, server and config editor) on your machine locally: How to install the full MSP Challenge Simulation Platform

To install the MSP Challenge client follow the instructions on the Client installation instructions page. Using only the client, you can already log on to our demo server to quickly try-out MSP Challenge.

To host your own MSP Challenge game sessions, the MSP Challenge server also needs to installed.

Only install the server if you intend to turn your computer into a server, i.e., a computer open to participants with the client to connect to, thus a computer open to outside connections.

This section pertains to fresh installations (so not upgrades) through Docker on Linux or Windows only. We have supported Docker since version 4.0.0.

If you're interested in running the Server through Docker, we assume a (basic) system administrator's level of expertise. In other words, we assume you are a bit familiar with Docker itself.

You can either host the server locally on your machine, or in your LAN (Local network). Or, if you want to put your server online make sure to first get your hands on a (sub-)domain name and make sure it refers to the IP address of your machine. This means defining an A record in the domain's DNS settings, through some DNS-setting tool that your domain or hosting provider should provide.

These are the server installation steps for both Linux and Windows:

• Install Docker Engine or Docker Desktop if not done so already. Linux or Windows, both should work.
• If you installed Docker Desktop, you might need to restart your machine.
• If you installed Docker Desktop, open it, go to Settings (Press the gear-icon), choose "General" on the left, and make sure to enable "Use the WSL 2 base engine" as well as "Add the *.docker.internal names to the host's /etc/hosts file"
• Do you have any existing MSP Challenge sessions? IMPORTANT! You'll have to backup your existing MSP Challenge sessions using the Save feature of the Server Manager application, and by then downloading the ZIP file to your computer. Make sure the save and download work, by re-uploading the saved ZIP and reloading the saved session. Did everything work? You'll be able to re-upload the ZIP file again after the (clean) install, and then you'll be able to reload a session using that save. Note that this will be only necessary if for some reasons the existing sessions are not working after the install,
• Clean any previous MSP server installations.
  • Open a terminal
    • on Windows: press the Windows-key, type Powershell and press Enter
  • Next step is to clean-up any previous installed MSP Challenge.
    • IMPORTANT! The following commands will remove all docker containers installed in Docker - so not only MSP Challenge. If you do not want this, you will have to manually remove the containers, images, network, volumes, see [1]
    • To start cleanup, you first run the command:

      docker stop $(docker ps -a -q)

      to stop the containers, and then to clean-up the Docker system, its network using:

      docker system prune -af; docker network prune -f

  • If you want to try upgrading and keep your volume data (which includes the sessions), then skip the following command, otherwise run it to clean-up all Docker data volumes:

    docker volume prune -af

    Note that you can always restore the sessions using the saved ZIP files from earlier.
    • Using Docker Desktop you can also go to "Volumes" on the left to see all volumes and to remove them individually if needed. Keep the volume ending with "_mariadb_data" to maintain the database data (the sessions).
• Before you continue, make sure you have a working internet connection.
• Navigate to a folder where you want to install MSP Challenge server (so it will be installed in that directory, not a sub-directory)
  • on Windows: Open Windows explorer, navigate to the folder, select the address, as-in select "> This PC > …." and then replace it with "powershell" and press Enter (this is neath trick to open the folder directly into PowerShell)
• Copy below one-liner command into your clipboard:
  • on Windows:

    Invoke-WebRequest -Uri "https://raw.githubusercontent.com/BredaUniversityResearch/MSPChallenge-Server/refs/heads/dev/setup/prod.ps1" -OutFile "prod.ps1"; .\prod.ps1

  • on Linux (tested on Ubuntu/Debian):

    sudo apt-get update && sudo apt-get install -y wget && wget -q https://raw.githubusercontent.com/BredaUniversityResearch/MSPChallenge-Server/refs/heads/dev/setup/{run-ps1.sh,prod.ps1} && sudo bash run-ps1.sh prod.ps1

• Paste the one-liner command into your "terminal" (on Windows being Powershell, on Linux being bash) and Press Enter to run it
• This command will download a script and run it, which will ask for your input for parameters to setup the server. Below is a table of some examples for different situations. For any of the "presets" the parameters CADDY_MERCURE_JWT_SECRET and APP_SECRET will be automatically generated. Only the most basic parameters are listed below. Other parameters get a common default value based on the selected preset.

Preset Selection	For what purpose	Basic setup
Direct (Directly exposed)	The docker container running the MSP Challenge server is directly exposed to the internet on port 443 given the server name, e.g. https://your.domainname.here. The MSP Challenge web server (Caddy) will automatically obtain a TLS certificate for the given server name.	URL_WEB_SERVER_HOST=your.domainname.here URL_WS_SERVER_HOST=your.domainname.here URL_WS_SERVER_HOST and SERVER_NAME will be equal to the value of URL_WEB_SERVER_HOST
Proxy (Behind a proxy)	The docker container running the MSP Challenge server is behind a reverse proxy, like. Nginx, which is responsible for handling: the server name requests on https, port 443, e.g. https://your.domainname.here TLS certificates forwarding requests to the MSP Challenge server running on http (port 80 by default). We at BUas are also using a Nginx proxy, allowing us to run multiple versions of the server behind the same server.mspchallenge.info URL . If you are interested in such a setup, see our example on the Nginx proxy example page.	URL_WEB_SERVER_HOST=your.domainname.here URL_WS_SERVER_HOST=your.domainname.here URL_WS_SERVER_HOST will be equal to the value of URL_WEB_SERVER_HOST SERVER_NAME will be automatically set to :80
LAN (Network setup)	The docker container running the MSP Challenge server is exposed to the local area network, by the machine's IP address.	Set the URL_WEB_SERVER_HOST to the machine's IP adress, e.g. 10.55.7.186 Set the URL_WS_SERVER_HOST to that IP adress as well URL_WS_SERVER_HOST will be equal to the value of URL_WEB_SERVER_HOST SERVER_NAME will be automatically set to :80
Local setup	The docker container running MSP Challenge server is locally available on the host machine, e.g. host.docker.internal, or localhost.	Set the URL_WEB_SERVER_HOST to host.docker.internal Set the URL_WS_SERVER_HOST to host.docker.internal URL_WS_SERVER_HOST will be equal to the value of URL_WEB_SERVER_HOST

• Please fill-in all parameters, or just press Enter to use the parameter's default value shown.
• Finally it will ask you if you want to continue the installation given the input. Enter "n" if you want to cancel it, otherwise just press enter to continue
• The setup now install all Docker containers that are part of the MSP Challenge server. Wait for it to finish (it shows a list of containers with status "Started")
• You might need to give the container another minute or two, but after that you should be able to open up the Server Manager application in your browser under your machine's domain name, something like: https://your.domainname.here/ServerManager. You might first get redirected to the MSP Challenge Authoriser application prompting you to log in with your MSP Challenge account. This might not happen if you already did that in your current browser session (as we have a Single Sign-On functionality). After login, you should be on the Server Manager page where you can now set up your first new game session. If you're not familiar with this, then follow the instructions on this page.

Other ways of installing

On Linux, you can also follow the instructions on this separate page, which is an older setup method (but still supported), but does require you to download the full source code of the server and installing PHP software. You can also use this alternative setup on Windows, by first installing Docker Desktop and "Git for Windows", and from a Git Bash command-line app, follow the same instructions as explained above concerning Linux, starting from 'Now obtain the MSP Challenge Server code'.

You can, if you want, also hire a virtual machine from a service such as Microsoft Azure, and install the server on there using Docker. We have done this at BUas many times. Here's a page about using Microsoft Azure to do this.