Getting Started for Local Development


If you're new to Docker, please be aware that some resources are cached system-wide and might reappear if you generate a project multiple times with the same name (e.g. this issue with Postgres <docker-postgres-auth-failed>).


1. Clone your fork and keep in sync with upstream master

git clone<your-github-username>/metagrid.git

Rebase your fork with upstream to keep in sync

# Add the remote, call it "upstream":
git remote add upstream

# Fetch all the branches of that remote into remote-tracking branches
git fetch upstream

# Make sure that you're on your master branch:
git checkout master

# Rewrite your master branch so that any of your commits that
# aren't already in upstream/master are replayed on top of the
# other branch:
git rebase upstream/master
git push -f origin master

Checkout a new branch from master.

git checkout -b <branch-name> master

2. Set up pre-commit

This repo has default integration with pre-commit, a tool for identifying simple issues before submission to code review. These checks are performed for all staged files using git commit before they are committed to a branch.

2.1 Integrated Hooks (Quality Assurance Tools)

Platform Code Formatter Linter Type Checker
Python black flake8 mypy
JavaScript/TypeScript prettier ESLint N/A

2.2 Install

# Create a python3 virtual environment using system-level Python.
# There may be alternative ways for you to do this.
python3 -m venv backend/venv

# Activate the virtual environment
source backend/venv/bin/activate

# Install local requirements
pip install -r requirements/local.txt

# Install pre-commit hooks
pre-commit install

Note: any update to .pre-commit.config.yaml requires a reinstallation of the hooks

2.3 Helpful Commands

Automatically run all pre-commit hooks (just commit)

git commit -m '...'

Pre-commit Output

Manually run all pre-commit hooks

pre-commit run --all-files.

Run individual hook

# Available hook ids: trailing-whitespace, end-of-file-fixer, check-yaml, black, isort, flake8, mypy
pre-commit run <hook_id>.

3. Set up Back-end

Open the project in a terminal and cd backend.

3.1 Build and Run the Stack

This can take a while, especially the first time you run this particular command on your development system but subsequent runs will occur quickly:

docker-compose -p metagrid_backend_dev up --build

3.2 Additional Configuration

Update /etc/hosts file

The Keycloak docker service can be accessed by other containers over a shared network using its docker service name and port, keycloak:8080. More information on how this works can be found in Docker's networking guide.

You will need to bind the hostname keycloak to localhost to allow the browser to make requests to the Keycloak service. Otherwise, it will not recognize the hostname and a network connection won't be established.

  1. Open your hosts file with admin privileges
    1. Mac/Linux: /etc/hosts
    2. Windows: C:\Windows\System32\drivers\etc\hosts
  2. Append keycloak to the end of the file and save

Create user on Keycloak for authentication

This user will be used for logging into registered Keycloak clients, including the React and Django services.

  1. Head over to localhost:8080/keycloak:8080
  2. Login with admin credentials (automatically created)
    • username: admin
    • password: admin
  3. Follow the official Keycloak instructions to create a new user

3.3 Accessible Services

  • Django: localhost:8000
  • Keycloak: localhost:8080/keycloak:8080

3.4 Troubleshooting

Addressing Keycloak Boot Issue

Keycloak has a known fatal issue where if it is interrupted during boot (stopping docker-compose up prematurely), the command that adds the admin user fails.

As a result, the Keycloak docker service will not start and outputs the error "User with username 'admin' already...".

If you run into this problem, follow these workaround steps:

  1. Stop all back-end containers docker-compose -p metagrid_backend_dev down
  2. Comment out the two relevant lines (./backend/.envs/.local/.keycloak)

    • #KEYCLOAK_USER: admin
  3. Rebuild and restart the containers docker-compose -p metagrid_backend_dev up --build

  4. Un-do commenting
    • KEYCLOAK_USER: admin


4. Set up Front-end

Open the project in a terminal and cd frontend.

4.1 Build and Run the Stack

This can take a while, especially the first time you run this particular command on your development system but subsequent runs will occur quickly:

docker-compose -p metagrid_frontend_dev up --build

4.2 Accessible Services

  • React: localhost:3000

Convenience Script for Common Tasks

If you cd to the root project directory for metagrid, you'll see there is a script.

This script provides some convenience functions for common tasks related to running Metagrid. Selecting the 'Start / Stop Local Dev Containers' option in the main menu will automatically build the frontend and backend local containers using the same commands described earlier on this page. If the containers are already running, then the same option will stop the containers instead.

This is a quick way to start and stop the Metagrid app for local development. The other functions in the script are related to production mode and are explained further here: Getting Started for Production

VSCode Configuration

.vscode/settings.json files are provided to automatically configure your VSCode to leverage the quality assurance tools even if you use workspaces or open the folder directly.

Third Party Tool Integration

Code coverage: Codecov Coverage

Dependency Monitoring: Renovate enabled Updates

Docs: Documentation Status