Skip to content

Local development setup

A local BitAgent dev environment needs Go, Python, Postgres, and the Task build tool. The repo ships a Nix flake for reproducibility; manual install also works.

This page is for contributors. For runtime configuration see configuration.md.

Prerequisites

Tool Version
Go 1.22+
Python 3.11+
Postgres 16
Task latest
Docker (optional) latest, for compose-based dev

Clone

gh repo clone gekleos/bitagent
cd bitagent

The flake.nix provides a reproducible shell with everything pinned.

nix develop

Drops you into a shell with Go, Python, Postgres, Task, and the Go module dependencies preinstalled.

Option B: Manual install

If you don't use Nix:

  • Go — go.dev/dl/ (1.22+)
  • Python — python.org or pyenv install 3.11
  • Task — brew install go-task/tap/go-task or taskfile.dev/installation/
  • Postgres — brew install postgresql@16 (macOS) or apt install postgresql-16 (Debian/Ubuntu)

Local Postgres setup

Create the user and database BitAgent expects.

createuser bitmagnet
createdb -O bitmagnet bitmagnet
psql -c "ALTER USER bitmagnet WITH PASSWORD 'devpass';"

Environment file

cp examples/.env.public.example .env

Edit .env and set:

POSTGRES_HOST=localhost
POSTGRES_PASSWORD=devpass
LOG_LEVEL=debug

Build and run

The repo's Taskfile.yml is the build entry point.

# Build the binary
task build

# Run all workers in the foreground
./bitagent worker run --all

You should see DHT bootstrap logs within ~30 seconds, and bitagent_dht_ktable_hashes_added_total start ticking up after ~3 minutes (visible at http://localhost:3333/metrics).

Run tests

# All tests
task test

# A subset
go test ./internal/classifier/...

The classifier tests are the slowest because they cover the CEL rule chain end-to-end. Most other packages run in seconds.

Vet and lint

task vet           # go vet
task lint          # golangci-lint (if installed)
golangci-lint run  # explicitly

Dashboard development

The dashboard is a separate Python FastAPI app in the ui/ subdirectory. Open a second terminal:

cd ui
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

BITAGENT_GRAPHQL_URL=http://localhost:3333/graphql \
BITAGENT_METRICS_URL=http://localhost:3333/metrics \
  uvicorn app:app --reload

Dashboard is at http://localhost:8000. The --reload flag picks up Python changes; restart for env-var changes.

Working with the GraphQL schema

Schema files live at graphql/schema/*.graphqls. Generated bindings are in internal/gql/gql.gen.go.

After editing a schema file, regenerate:

task graphql:generate
# or directly
go run github.com/99designs/gqlgen generate

Then run task vet to catch any resolver gaps.

Database migrations

Migrations live in migrations/ as NNNNN_name.sql (goose format). The worker auto-applies them on startup, so during dev you don't usually invoke goose manually.

If you need to run migrations explicitly (e.g., to test a new migration in isolation):

./bitagent migrate up

Down migrations are best-effort — for a clean reset during dev, drop and recreate the database.

dropdb bitmagnet
createdb -O bitmagnet bitmagnet
psql -c "ALTER USER bitmagnet WITH PASSWORD 'devpass';"

Common dev tasks

Reload classifier rules. The CEL rules are bundled in the binary; rebuild and restart:

task build && ./bitagent worker run --all

Inspect resolved config. The From column tells you which env var or default produced a given value:

./bitagent config show

View the loaded classifier workflow:

./bitagent classifier show --format yaml | head -50

Probe live metrics during dev:

curl -s http://localhost:3333/metrics | grep -E '^bitagent_' | head -30

Submitting a pull request

  1. Fork the repo (gekleos/bitagent).
  2. Branch from main — name like feat/your-feature or fix/issue-NNN.
  3. Run task vet test lint before pushing.
  4. Push and open a PR. Reference any related issue in the description.
  5. The CI pipeline runs vet + tests + lint on every push.
  6. See CONTRIBUTING.md at the repo root for style and process notes.

See also