Skip to content

Development / Building from Source

This page covers building connect from source and the local dev workflow. For adding a new tunnel type or management Extension in your fork, see Extension Authoring — this page only covers the surrounding build/test/verify loop, not how to write the extension itself.

Prerequisites

  • Go (version per go.mod, currently 1.27+)
  • uv — only needed if you're also building the documentation site locally (see Documentation below)
  • openssl, yamllint, shellcheck, golangci-lint, gosec, gograph — used by make lint/make verify; not required just to build the binary

Build

git clone https://github.com/dioad/connect.git
cd connect
go generate ./...
go build .

go generate ./... builds the embedded management-UI web assets (Vite/React, under web/ and the mail management UIs) — required before go build . will produce a working binary with a functional management UI.

Test

go test -race ./...

make verify

The full pre-completion check, run in CI and expected before any change is considered done:

make verify

This runs, in order:

  1. go fmt / go fix / golangci-lint run / gosec / go vet — linting and static analysis.
  2. yamllint over the example agent/server configs and shellcheck over the test scripts.
  3. gograph boundaries — checks package imports against the layers in boundaries.json.
  4. go test -race ./... — the full test suite, race detector enabled.
  5. go generate ./... + go build . — the same build as above.
  6. bash test-scripts/smoke_test_local.sh — starts a real agent and server locally against generated test certificates and exercises reverse/forward tunnels, DNS, and the management API end to end.

Local test certificates

The local smoke test and several manual testing flows need a local CA and leaf certificates:

make test-certificates

Generates a server and client CA plus leaf certificates under .local-dev/ (gitignored). Re-run if you need fresh certificates; existing ones aren't regenerated once present (see the Makefile's file-based targets).

Documentation site

The contents of doc/ are built into two mkdocs-material sites — this usage site, and a separate Architecture site covering internals/C4 models (linked from the home page). Building them locally:

make docs-serve                  # usage site, http://127.0.0.1:8000
make docs-serve-architecture     # architecture site, http://127.0.0.1:8001

Both regenerate the CLI reference (internal/tools/gendocs) and run uv sync first. make docs builds both statically (same --strict checks CI runs) into site/ (gitignored).

Adding a custom tunnel type

If you fork and compile the agent yourself, internal/cmd/agent/registry_init.go is where built-in tunnel types are registered — see Extension Authoring § Register the Tunnel Type for the full walkthrough (defining a config struct, implementing a ServerType, and registering it).