Environment Setup

Spordle Play uses a devcontainer based environment which runs in Docker through VS Code. This helps keep developer environments in sync and reproducible, and avoids clashing with anything else you’re working on if you’re working on other projects.

The devcontainer is configured with docker-compose to automatically sets up an environment with containers for nodejs, Postgres, RabbitMQ, and Minio with the correct versions. Compose creates an internal network that allows containers to communicate with each other using their container names, which is useful to know for your app container.

If you have any of these services already installed, the container networking won’t conflict with existing ports and VS Code will automatically expose services to the next available port, while the standard ports are used within the devcontainer environment.

Windows

1. Install WSL2 from the Microsoft Store and VS Code. You don’t need anything else! ✨

   • Docker Desktop is not necessary if you have WSL2 version 0.67.6 or higher (check wsl --version)

   • Install the Dev Containers extension in VS Code

2. Prepare WSL for docker. This may not be necessary in recent versions of Windows 11

   1. Enable systemd by updating /etc/wsl.conf to add:

      [boot] systemd=true

   2. Restart WSL (via cmd)

      wsl --shutdown

3. Install Docker. Follow Docker’s instructions to install docker-ce and docker-compose-plugin

   1. Once installed, add your user to the docker group for later convenience

      sudo usermod -aG docker $USER

4. Setup SSH agent forwarding by adding the following to .bashrc in WSL. This will allow git to work in the devcontainer

5. Clone the Play repository in WSL (~, not Windows C:/…)

6. Open it in VS Code

7. Relaunch in the devcontainer

   • You’ll see a notification in the bottom-right corner suggesting this

   • You can also relaunch via the Ctrl-P menu by searching for ‘dev containers’

   • This might take some time as it’s pulling and building a few docker images for the first time

   • If it fails to launch, the bottom-right notification lets you open the logs to see what the error is exactly. The error popup is usually vague and super misleading.

8. Follow README.md for further instructions on how to install and build Spordle Play

   1. https://github.com/Spordle/Play/blob/master/README.md

   2. Make sure to install NPM and the dependencies from the WSL Terminal!

9. Create a branch and open your first pull request! 🎉

macOS

Same as Windows, minus needing WSL2.