Skip to main content

Setting up a dev environment

There are three ways to get a working development environment:

  1. Setup a local environment. This requires creating a Python environment + installing additional system dependencies, but provides the best experience and performance (provided your machine is capable enough).
  2. Use GitHub Codespaces. This provides a pre-configured environment in the cloud where everything works out of the box
  3. Setup VS Code Dev Containers. This provides a local pre-configured environment with little setup. Dev containers are generally less performant, but this setup can help if option 1 fails and you still want to work locally.

Once this is done, you should look at the Mono guide to manage Python packages and best work in the environment.

Option 1: Local Environment​

info

Prerequisite: set up Git and clone the monolith repository locally. I recommend following GitHub's guides on setting up Git and cloning a repository if you're not familiar.

  • Install uv, our Python package manager, using the official instructions
  • At the root of the repository, run uv venv && uv sync
    • This will install the right Python version, create a .venv folder for the Python environment, and install basic dependencies.
  • Activate the virtual environment: source .venv/bin/activate
  • Initialize your development profile: mono init
    • This will create a mono.toml configuration file and install all the dependencies you need
    • If you are part of a team with a dedicated profile, you should specify it here: mono init <profile>
  • You're good to go!
    • If you are using a profile with geospatial projects and are missing system packages, use Homebrew to install GDAL

To get environment variables working, you will also need to set up Doppler (see Appendix A).

Option 2: GitHub Codespaces​

  • On the main page of the Monolith repository, click the green "Code" button at the top right above the file structure.
  • Select the "Codespaces" tab.
  • Click the "+" button to launch a new Codespace.
  • A new tab will open for your codespace.
    • It may take one or two minutes to start and will provide you with an in-browser code editor.
    • You can also connect your desktop VS Code by clicking on the "Codespaces" button at the bottom left and picking "Open in VS Code Desktop" from the Command Palette that opens.

Option 3: Dev Container​

info

Prerequisite: set up Git and clone the monolith repository locally. I recommend following GitHub's guides on setting up Git and cloning a repository if you're not familiar.

To set up a local development environment:

  1. Install VS Code (or any VS Code based editor)
  2. Install the Dev Containers extension
  3. Clone the monolith repository locally and open its folder in the editor.
  4. Open the command palette (Ctrl/Cmd + Shift + P)
  5. Search for one of these two options:
    • Dev Containers: Rebuild and reopen in container
      • Works with the copy of the repository on your system. It's a more lightweight setup, but it can be slower for file operations, especially when installing packages.
    • Dev Containers: Clone Repository in Container Volume... (recommended)
      • Creates a completely separate copy of the repository in the Dev Containers. Any changes to your local clone of the repository will not appear there. This is more performant for file operations. The only downside is that you cannot work both
  6. Wait for the container to build
  7. Once complete, you should see Dev Container: Brimstone - Monolith in the bottom left
  8. Follow Appendix A to setup Doppler

After initial setup, you can return to this environment through:

  • Command Palette (Ctrl/Cmd + Shift + P) > File: Open Recent
  • File > Open Recent menu
  • Search for monolith to find the Dev Container setup

Appendix A: Setting up Doppler for environment variables​

Doppler is the service we use to share environment variables. It acts as the central place where all environment variables are defined, with separate configurations for development, production, and others. From there, environment variables are synced to our AWS production environment, our GitHub Actions pipelines, and more.

During development, we'll pull the environment variables using the Doppler CLI. You will need to install it if you're setting up a local environment. Gitpod and the Dev Container already have it.

If you are a team member with access to Doppler, you can run doppler login in your terminal, follow the instructions, and be set.

Otherwise, make sure you can access the DOPPLER_TOKEN item available in the Software Engineering 1Password Vault (shout at Erwin if you can't). Copy its value into a .env file at the root of the repository so that it looks like this:

DOPPLER_TOKEN=XXXXXX

This file is ignored by Git, but will be picked up by the code that loads environment variables.