Getting started

This page mirrors CONTRIBUTING.md and the Makefile targets that you will actually run as a contributor. If anything here disagrees with CONTRIBUTING.md, treat the latter as authoritative.

Prerequisites

• Go — version pinned in go.mod (go 1.26.2 at the time of writing).
• Docker — for runtime dependencies (Cassandra, MySQL, Postgres, Elasticsearch). Optional if you only run unit tests against SQLite.
• Protocol buffers — only if you change .proto files. Install with brew install protobuf on macOS.
• Temporal CLI — brew install temporal. Lets you talk to the server you start.

On Linux you can install Go via your package manager; on Windows use WSL2.

Build

make            # default target: installs build deps and builds binaries
make bins       # build binaries without running tests

Top-level make produces three binaries in ./ :

Binary	Purpose
temporal-server	The cluster process — see cmd/server/main.go.
temporal-cassandra-tool	Schema setup / migration for Cassandra.
temporal-sql-tool	Schema setup / migration for MySQL / PostgreSQL / SQLite.

make will also generate any out-of-date Go code under api/ and proto/. The full list of targets is at the top of the Makefile.

Run the server locally

The fastest path uses SQLite as an embedded persistence backend, no Docker required:

make start            # SQLite in-memory
make start-sqlite-file  # SQLite file-backed (./temporal.db)

Other backends (need make start-dependencies first to bring up the relevant Docker container):

make install-schema-cass-es && make start-cass-es     # Cassandra + Elasticsearch
make install-schema-mysql && make start-mysql
make install-schema-postgresql && make start-postgres

These targets pass a config file from config/ to temporal-server start. Equivalent direct invocation:

./temporal-server --env development-sqlite --allow-no-auth start

Once the server is up, create a namespace and run a sample with the Temporal CLI:

temporal operator namespace create -n default
temporal workflow list

The web UI is available at http://localhost:8233 if you started dependencies.

Testing

There are three layers of tests; pick the one you need.

Layer	Make target	What it covers
Unit	make unit-test	Pure Go tests under service/, common/, chasm/, etc.
Integration	make integration-test	Persistence-backed tests requiring a real DB.
Functional	make functional-test	E2E tests under tests/ — spin up an in-process cluster.
Everything	make test	All three.

Run a single test:

go test -tags test_dep -v ./service/history -run TestHistoryEngine

The -tags test_dep flag is required by some test files (AGENTS.md calls it out as mandatory). Functional/integration tests use testify suites; unit tests prefer plain require.

For coverage and parallelisation hints see How to contribute → testing.

Code generation

Several files are generated. After editing the corresponding sources, regenerate:

make proto              # all proto + grpc + interceptor stubs
make update-go-api      # pull latest go.temporal.io/api into go.mod

If you modify anything tagged //go:generate in a Go file, run go generate ./... for the affected package. Generators live in cmd/tools/, e.g. genrpcwrappers, gendynamicconfig, gensearchattributehelpers.

Linting and formatting

make lint-code     # golangci-lint with the project's ruleset (.github/.golangci.yml)
make fmt-imports   # group/sort imports the way the linter wants

Both are enforced by CI (.github/workflows/). Run them before pushing.

IDE setup

The repository checks in .vscode/ defaults that work out of the box. For GoLand the CONTRIBUTING.md section covers run/debug configurations. To debug the server, set the package path to go.temporal.io/server/cmd/server and pass --env development-sqlite --allow-no-auth start as program arguments.

Common gotchas

• make fails on first run — usually a missing protoc or Go version mismatch. Re-read the prereqs above.
• docker compose cleanup — make stop-dependencies after switching backends, otherwise stale ports linger.
• License headers — every Go file needs the project header. make copyright checks; running it once also reports missing headers.
• PR titles — start with an upper-case letter and have no trailing period (see CONTRIBUTING.md).

Next steps

• Architecture — how the services fit together.
• How to contribute — branch / review / merge cycle.
• Glossary — Temporal-specific vocabulary used throughout this wiki.