Makefile Targets

make is the single entry point for every recurrent command in RAT. All targets run inside Docker containers — nothing is installed on the host machine. If you find yourself typing a raw command more than once, it should be a Makefile target.

Run make help to see all available targets with descriptions.

Why Make?

• Standardization: Everyone runs the same command the same way
• Documentation: make help is the command reference
• Reproducibility: Targets are idempotent — running twice produces the same result
• Containerized: All targets use Docker — your host machine stays clean

Setup

make setup

First-time setup. Generates all code (protobuf stubs, sqlc, TypeScript SDK) so the project is ready to build and test.

make setup

What it does:

1. Runs make proto — generates Go + Python gRPC stubs from .proto files
2. Runs make sqlc — generates type-safe Go code from SQL queries
3. Runs make sdk-build — builds the TypeScript SDK

Lifecycle

These targets manage the Docker Compose stack (all 7 services).

make up

Start all services in detached mode. Builds images if they do not exist yet.

make up

After starting, prints the URLs for portal, API, MinIO, and Nessie.

make down

Stop all services. Preserves data volumes (Postgres, MinIO).

make down

make restart

Stop and restart all services (equivalent to make down && make up).

make restart

make build

Build all Docker images. Uses layer caching for fast subsequent builds.

make build

make rebuild

Rebuild all Docker images from scratch (no cache). Use when you need a completely clean build.

make rebuild

make logs

Tail logs from all services in real-time. Press Ctrl+C to stop.

make logs

To view logs for a specific service, use Docker Compose directly:

docker compose -f infra/docker-compose.yml logs -f ratd

make status

Show the status of all services (running, healthy, exited).

make status

Testing

RAT has 26+ Makefile targets, with testing being the largest group. All tests run inside Docker containers.

make test

Run all tests sequentially: Go, Python, then TypeScript.

make test

This is equivalent to running make test-go, make test-py, and make test-ts one after another.

make test-all-parallel

Run all tests in parallel (Go + Python + TypeScript simultaneously). Faster on machines with multiple cores.

make test-all-parallel

Uses make -j3 internally to run the three test suites concurrently.

make test-go

Run Go tests for the platform/ service. Uses the race detector (-race) and disables test caching (-count=1).

make test-go

What it runs:

go mod tidy && go test -v -race -count=1 ./...

make test-py

Run Python tests for both runner/ and query/ services. Uses pre-built test images if available (run make test-images first for faster execution).

make test-py

What it runs:

• Runner tests: pytest -v in the runner/ directory
• Query tests: pytest -v in the query/ directory

make test-images

Build pre-cached Docker images for Python tests. These images have all dependencies pre-installed, making make test-py significantly faster.

make test-images

make test-ts

Run TypeScript tests for the SDK and portal. Builds the SDK first (via make sdk-test), then runs portal tests.

make test-ts

make test-integration

Run Go integration tests against real Postgres and MinIO instances. Starts a separate test Docker Compose stack, runs the tests, then tears it down.

make test-integration

What it does:

1. Starts postgres and minio from infra/docker-compose.test.yml
2. Runs integration tests in platform/internal/postgres/ and platform/internal/storage/
3. Tears down the test services

make smoke-test

Run an end-to-end smoke test against a running stack. Requires make up to have been run first.

make smoke-test

Executes the infra/scripts/smoke-test.sh script which verifies that all services are healthy and basic operations work.

Code Quality

make lint

Lint all code across all languages: Go, Python (runner + query), and Protobuf.

make lint

What it runs:

• Go: go vet ./...
• Python: ruff check . && ruff format --check . (for both runner and query)
• Proto: buf lint

make lint-go-strict

Run golangci-lint with the project’s .golangci.yml configuration. Stricter than go vet — catches style issues, unused code, and common mistakes.

make lint-go-strict

make fmt

Auto-format all code (Go + Python). Modifies files in place.

make fmt

What it runs:

• Go: goimports -w .
• Python: ruff format . (for both runner and query)

Code Generation

make proto

Generate Go and Python gRPC stubs from .proto files in the proto/ directory.

make proto

Uses buf generate with the configuration from proto/buf.gen.yaml. Generated files are written to:

• platform/gen/ (Go)
• runner/src/rat_runner/gen/ (Python)
• query/src/rat_query/gen/ (Python)

make sqlc

Generate type-safe Go code from SQL queries defined in platform/internal/postgres/.

make sqlc

Uses sqlc generate to produce Go structs and functions from SQL queries. See the sqlc documentation for the query annotation format.

Development

make dev-ratd

Start the Go platform service with hot reload using air. The service automatically restarts when you save a Go file.

make dev-ratd

Exposes ports 8080 (REST) and 8081 (gRPC) on the host. Connects to the infra_default Docker network so it can reach Postgres, MinIO, and other services.

make dev-portal

Start the Next.js portal with hot reload. Builds the SDK first (automatically runs make sdk-build).

make dev-portal

Exposes port 3000 on the host. Connects to the Docker network so server-side rendering can reach ratd.

make sdk-build

Build the TypeScript SDK. Produces ESM, CJS, and TypeScript declaration outputs.

make sdk-build

Output is written to sdk-typescript/dist/.

make sdk-test

Build the SDK and run its test suite (27 vitest tests).

make sdk-test

make portal-build

Build the portal for production (standalone Next.js output). Builds the SDK first.

make portal-build

Output is written to portal/.next/.

make portal-typecheck

Type-check the portal without building. Faster than make portal-build for verifying type correctness.

make portal-typecheck

Documentation

make docs

Start the documentation site dev server (Nextra) on port 3001 with hot reload.

make docs

make docs-build

Build the documentation as a static site.

make docs-build

Output is written to website/out/.

make docs-serve

Build and serve the static documentation site on port 3001.

make docs-serve

Operations

make backup

Create a timestamped backup of Postgres (pg_dump) and MinIO (mc mirror).

make backup

Backups are saved to ./backups/YYYYMMDD_HHMMSS/ with subdirectories for postgres/ and minio/.

make restore

Restore Postgres and MinIO from a previous backup.

make restore BACKUP_DIR=./backups/20260216_093000

make clean

Remove all containers, volumes, and generated files. This deletes all data.

make clean

What it removes:

• Docker containers and volumes (docker compose down -v)
• Generated proto stubs (platform/gen/, runner/src/rat_runner/gen/, query/src/rat_query/gen/)
• Build artifacts (portal/.next/, sdk-typescript/dist/)

make clean-all

Full clean — everything make clean does plus Docker images and pre-built test images.

make clean-all

Quick Reference