Getting started

How to build, test, and run Consul from this repository.

Prerequisites

• Go — the version pinned in .go-version (currently 1.26.2). The Makefile reads .go-version directly.
• Git — to fetch dependencies and embed build metadata.
• Make — every developer command goes through the Makefile.
• Docker (optional) — required for building the UI, the dev container, and the integration test suites.
• Node.js + Yarn — only needed when working on the Ember UI in ui/ (see ui/packages/consul-ui/README.md).

Building

Build a development binary for your local OS/arch:

make dev

The resulting consul ends up in both ./bin and $GOPATH/bin. Build dates and the git commit hash are wired in via -ldflags in the Makefile and the version/version.go GitCommit and BuildDate variables (the date itself is produced by build-support/scripts/build-date.sh).

To build for every supported OS/arch combination, run the default make target. To build a Docker image, run make dev-docker. To build the Linux binary used by integration tests, make linux.

Running

Start a single-node dev agent (everything in memory, server + UI enabled):

./bin/consul agent -dev -ui

The HTTP API listens on 127.0.0.1:8500, DNS on 127.0.0.1:8600, and the gRPC xDS server on 127.0.0.1:8502. Open http://127.0.0.1:8500/ui/ for the embedded web UI.

Configuration files (HCL or JSON) are loaded with -config-file / -config-dir. Defaults and parsing live in agent/config/. See the operator docs at https://developer.hashicorp.com/consul/docs/agent/config/config-files for the full schema.

Testing

The full test suite is large (830 *_test.go files). During development, run only the packages you touched:

# Run all tests in a package
go test -v ./agent/consul

# Run a single test by name
go test -v -run TestRetryJoin ./command/agent

# Skip slow tests (use the -short flag)
go test -short ./...

make test runs lint + test-internal (every package). make test-race enables the data race detector. make test-all walks every Go module (api/, sdk/, envoyextensions/, proto-public/, troubleshoot/, root).

Integration suites live in test-integ/ (deployer-based, Docker required) and test/integration/ (Envoy/connect, Docker required). Run them with make test-deployer, make test-envoy-integ, make test-compat-integ.

Linting and formatting

make fmt    # gofmt + goimports across every module
make lint   # golangci-lint (pinned version v2.11.4)

Pre-commit hooks defined in .pre-commit-config.yaml run formatters and golangci-lint automatically on staged files when pre-commit is installed.

Code generation

Several artifacts are generated:

• Protobuf: make proto (uses buf v1.56.0). Schemas live under proto/ and proto-public/.
• Mock interfaces: make mocks-tools then make mocks (uses mockery v3.5.2). Config: .grpcmocks.yaml.
• Deep-copy helpers: generated via per-package deep-copy.sh scripts (e.g., agent/consul/state/deep-copy.sh, agent/structs/, agent/proxycfg/).
• Version metadata: version/VERSION is a one-line file embedded by //go:embed into version/version.go.

Common developer tasks

Task	Command or file
Add a new HTTP endpoint	Register in agent/http_register.go, implement in agent/<thing>_endpoint.go
Add a new RPC	Add method on a *_endpoint.go server type in agent/consul/, register it
Add a new config-entry kind	See docs/contributing/checklist-adding-config-fields.md and agent/structs/config_entry.go
Add a CLI subcommand	New package under command/, register in command/registry.go
Add a Raft FSM command	agent/consul/fsm/commands_ce.go, agent/consul/state/<thing>.go
Update Go module dependencies	go mod tidy then commit go.mod and go.sum
Add a changelog entry	.changelog/<PR>.txt (see docs/contributing/add-a-changelog-entry.md)

See How to contribute for the PR workflow and review expectations.