Code for Life
Search
⌃K

Dev Containers Setup

Working environment setup for all the repositories.
We have revamped our setup process to work with Dev Containers!
🙌
This document will guide you through getting setup with them. If you would rather follow the old process, go through the Manual Setup.

1. Install and set up Git

If you don't already have Git installed on your machine, follow the installation instructions here.
Once Git is installed, follow the first-time setup instructions here.

2. Install Docker CE

Docker CE is needed on your machine to run the Dev Containers. Follow the Docker CE installation instructions for your OS here.

3. Install VS Code

We officially support Dev Containers setup with the VS Code IDE. If you don't have VS Code already, you can install it directly here.

4. Recursively checkout the codeforlife-workspace

Go to the codeforlife-workspace. This repo collects all of CfL's repos into one.
Recursively clone the CfL repos by running:
git clone --recurse-submodules https://github.com/ocadotechnology/codeforlife-workspace.git
in a directory of your choice.
You should now have cloned the workspace and the repos inside it!

5. Open the workspace in VS Code

Open a new VS Code window and open up the workspace folder using:
File > Open Folder... > path/to/codeforlife-workspace/
Please do not open the workspace by using Open Workspace from File...
Opening it in this way is likely to cause issues with the new Dev Containers implementation. Because of this we are likely to change the workspace structure soon, including the deletion of the codeforlife.code-workspace file.

6. Install the Dev Containers extension in VS Code

Open up the Extensions tab in VS Code. Search for the Dev Containers extension and install it.

7. Build and run a Dev Container

Each CfL repo in the workspace has an associated Dev Container (except the aimmo and codeforlife-kurono-badges repos). You'll need to build and run the Dev Container associated with the repo you wish to work in.
As we are currently working on a complete restructure of our system, we have some repos that maintain the current monolithic service, and others that are building towards the new microservices architecture.
Current monolithic app
Future microservices app
codeforlife-portal
codeforlife-package-python
rapid-router
codeforlife-package-javascript
aimmo (no Dev Container)
codeforlife-service-template
codeforlife-deploy-appengine
codeforlife-portal-react
​
codeforlife-sso
​
codeforlife-kurono-badges (no Dev Container)
To build and run a Dev Container, press Ctrl/Cmd + Shift + P and select the following command:
Dev Containers: Rebuild and Reopen in Container
The command will ask you to select which container to build. Select the one associated to the repo you want to work in.
VS Code will refresh your current window so it can it build and run the container. If you wish to see the output of the build as it is happening, click the following prompt in the bottom-right:
The first time the container is built takes some time, as it needs to download its base image as well as the images for the various features in it. The duration of the build will also depend on your internet speed and can go up to 10 minutes.
Luckily, this is a one-off: any following rebuilds will be significantly faster!
If, during the build, you get some errors stating that specific images or dependencies failed to install, it could be due to any VPN / DDoS mitigation software you might have running on your machine or network. Try disabling those temporarily to see if it helps.
Once the build is successful, the container will run an additional command to install the dependencies needed to run the project locally. You should see the output of this automatically in a terminal window in VS Code.
Example of the postCreateCommand in one of the containers
Your container has now been built!

8. Enable source control

Open the Source Control tab in VS Code and click "Manage Unsafe Repositories".
Then, select the only repository available in the dropdown. Source control for this repo is now enabled, meaning you can checkout branches, commit and push changes like normal.

9. Run the web server

Finally, inside a new terminal, run:
./run
This command will:
  • sync the database
  • collect the static files
  • run a development web server
You should see output like the following:
Django version 3.2.23, using settings 'settings'
Starting development server at http://127.0.0.1:8000/
Quit the server with CONTROL-C.
At this point the development server is accessible in your browser at http://localhost:8000/
Use this server to familiarise yourself with our app, view your changes as you do them, do some manual testing and login using our test accounts!
Please do not hesitate to ask questions if you found any difficulties to get things up and running. Github Discussion is the perfect place for this. It is monitored by the core developers and your questions may help other contributors who bump into the same issues.

10. Exiting the container

Should you want to exit the Dev Container, simply click on the tab in the bottom-left on the screen:
Select Close Remote Connection if you just want to close the container. Select Reopen Folder Locally if you want to close the container but reopen the local workspace.