Prerequisites

Gordon is developed on macOS (Apple Silicon) and deployed to ARM64 Linux (srv-apps, Raspberry Pi 5). An X64 dev machine works fine — the deploy host is ARM64 but your local environment does not need to match.

Required tools

Tool	Version	Purpose
Docker	Latest	Compose-based test and e2e stacks
Rust toolchain	1.94.1 (stable)	All Rust services and library crates
Node.js	20+	gordon-console (Next.js)
Python	3.12+	gordon-lab research and data pipeline
uv	Latest	Python package manager for gordon-lab
sccache	Latest	Rust compiler cache — required for fast rebuilds
cargo-nextest	Latest	Faster test runner used by all Rust repos
GNU Make	Any	Workspace task runner
overmind	Latest	Process manager for make dev-up

Install on macOS

Docker

Install Docker Desktop or Colima:

brew install colima docker docker-compose
colima start

Rust

Install via rustup:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

The workspace pins Rust at 1.94.1 stable via rust-toolchain.toml in each repo. rustup will pick up the correct toolchain automatically when you enter any repo directory.

Build tooling

cargo install sccache
cargo install cargo-nextest --locked

Set RUSTC_WRAPPER=sccache in your shell profile. make dev-init checks for this.

Python 3.12+ and uv

brew install python@3.12
curl -LsSf https://astral.sh/uv/install.sh | sh

Node.js 20+

brew install node@20

Or use fnm:

brew install fnm
fnm install 20
fnm use 20

overmind

brew install overmind

Verify

docker --version        # Docker version 27+
rustc --version         # rustc 1.94.1
cargo nextest --version # cargo-nextest 0.9+
sccache --version       # sccache 0.x
python3 --version       # Python 3.12+
uv --version            # uv 0.x
node --version          # v20+
overmind --version      # overmind v2+
make --version          # GNU Make 3.x+

Environment files

Gordon uses per-service environment variables. The dev stack reads from .env.dev, generated by make dev-init.

GORDON_DATABASE_URL=postgresql://gordon:gordon_dev@localhost:5432/gordon

Never commit .env.dev or any .env file. Use .env.example as the reference for required variables.

ARM64 deploy target

srv-apps is a Raspberry Pi 5 (ARM64). All GHCR images are built for linux/arm64. Your dev machine can be any architecture — builds run natively on your machine and are pushed to GHCR for deploy.