Development

This page lists what you need to run and develop SecureBuild locally. The project provides a Nix flake (flake.nix) that pins versions; the requirements below are consistent with that setup.

Container runtime

You need a container runtime for building and running images. Use either:

• Docker — or a Docker-compatible daemon (e.g. Docker Desktop, or Colima/Lima on macOS as used in the Nix shell).
• OrbStack — a lightweight Docker-compatible runtime, especially common on macOS.

The Nix dev shell checks that docker is available; with OrbStack or another Docker-compatible CLI, the same commands apply.

Requirements

The following are required for a full development environment, matching the SecureBuild flake.nix:

• Go — used to build the worker, builder, and other Go components.
• Node.js — for the SecureBuild app (Next.js).
• Docker or OrbStack — container runtime (see above).
• Git — for version control and repo operations.
• PostgreSQL — local DB for development (the flake provides pg_isready).
• pipx — for installing Python CLI tools (e.g. vunnel).
• Grype — vulnerability scanning (used in pipelines and scan jobs).
• Apko — Chainguard apko for building APK-based images.
• Melange — Chainguard melange for building packages.
• Syft — SBOM generation.
• Dagger — for CI/pipeline automation.
• SchemaHero — DB schema management.
• vunnel — installed via pipx (vulnerability data pipeline).
• grype-db — installed via go install (Grype database tooling).

On macOS, the Nix shell also includes Colima, Lima, and QEMU for running a local container runtime when not using Docker Desktop or OrbStack.

Using the Nix flake

The project uses a Nix flake for the development environment. From the SecureBuild repo root:

• Run nix develop to enter a shell with the above tools, or use direnv with use flake in .envrc so the environment loads automatically.
• The shell hook will install vunnel and grype-db if missing and print the status of each tool. For pinned versions and details, see flake.nix in the SecureBuild repository.

Make targets

Run make help to see available targets.

Go (worker, builder, proxies)

• Build worker: make build-worker — builds the worker with embedded builder binaries.
• Run services: make run-worker, make run-oci-proxy, make run-apk-proxy — each builds first if needed.

TypeScript (app)

• Install: cd securebuild-app && npm install (and similarly for other app directories in the repo).
• Dev server: npm run dev (app runs on port 3000).

Database

Migrations: make migrate — runs SchemaHero-based migrations.

Testing

• Unit tests (all): make test-unit — runs Go unit tests plus app tests.
• Go unit tests only: make test-unit-go.
• Integration tests: make test-integration-oci-proxy, make test-integration-apk-proxy, make test-integration-worker.

CI runs tests on pull requests; run the relevant targets locally before submitting.