Skip to main content
This guide covers building Temporal Server binaries and related tools from source code.

​
Initial Build

For your first build, use the default make command to install all build dependencies and compile the binaries: 
make
This target:
  • Installs required build tools (protoc plugins, linters, etc.)
  • Compiles all proto definitions
  • Builds all binaries
  • Runs the complete test suite

​
Build Binaries Only

After the initial setup, you can build binaries without running tests: 
make bins
This builds the following binaries:
  • temporal-server - Main server binary
  • temporal-cassandra-tool - Cassandra schema management tool
  • temporal-sql-tool - SQL database schema management tool
  • temporal-elasticsearch-tool - Elasticsearch schema management tool
  • tdbg - Temporal debugging tool

​
Build Individual Binaries

You can build specific binaries individually:

​
Temporal Server

make temporal-server
The server is built with CGO_ENABLED=0 by default. To enable CGO: 
CGO_ENABLED=1 make temporal-server

​
Temporal Server (Debug Build)

make temporal-server-debug
This builds the server with the TEMPORAL_DEBUG tag, which extends functional test timeouts for debugging sessions.

​
Database Tools

Cassandra Tool: 
make temporal-cassandra-tool
SQL Tool (MySQL/PostgreSQL): 
make temporal-sql-tool
Elasticsearch Tool: 
make temporal-elasticsearch-tool

​
Debugging Tool

make tdbg

​
Cross-Platform Builds

You can build for different platforms by setting GOOS and GOARCH: 
# Build for Linux AMD64
GOOS=linux GOARCH=amd64 make bins

# Build for macOS ARM64
GOOS=darwin GOARCH=arm64 make bins

# Build for Windows
GOOS=windows GOARCH=amd64 make bins

​
Build Tags

Temporal Server uses several build tags:
  • disable_grpc_modules - Excludes gRPC dependencies from cloud.google.com/go/storage, reducing binary size by ~16MB
  • test_dep - Enables test hooks implementation for testing
  • TEMPORAL_DEBUG - Extends timeouts for debugging
  • integration - Includes integration test dependencies
Build tags are automatically applied by the Makefile. To apply them manually: 
go build -tags disable_grpc_modules,test_dep -o temporal-server ./cmd/server

​
Proto Compilation

If you modify .proto files, regenerate the Go code: 
make proto
This command:
  1. Lints proto definitions
  2. Compiles proto files to Go code
  3. Generates service clients and server interceptors
  4. Generates search attribute helpers

​
Code Generation

After modifying files with //go:generate directives, run: 
make go-generate
This regenerates:
  • Mock implementations (using mockgen)
  • String methods (using stringer)
  • RPC wrappers

​
Clean Build

To remove all build artifacts and start fresh: 
make clean
This removes:
  • All binary files
  • Build tools in .bin/
  • Test output in .testoutput/
  • Go test cache

​
Build Verification

After building, verify the binaries: 
# Check server version
./temporal-server --version

# Check all binaries exist
ls -lh temporal-*

​
Updating Dependencies

​
API Dependencies

To update to the latest api and api-go: 
make update-go-api

​
Minor Version Updates

Update all dependencies to their latest minor versions: 
make update-dependencies

​
Major Version Updates

List available major version updates: 
make update-dependencies-major

​
Working with Local API Changes

If you need to modify the gRPC/protobuf definitions alongside server changes:
1

Clone Related Repositories

git clone https://github.com/temporalio/api.git
git clone https://github.com/temporalio/api-go.git
git clone https://github.com/temporalio/sdk-go.git
2

Make Changes to api Repository

Commit your changes to a branch in the api repository.
3

Update api-go

cd api-go
git submodule update --init --recursive
git submodule set-url proto/api ../api
git submodule set-branch --branch mystuff proto/api
git submodule update --remote proto/api
make proto
4

Point Server to Local Copies

Add to go.mod in the temporal repository:
replace (
    go.temporal.io/api => ../api-go
    go.temporal.io/sdk => ../sdk-go
)
Then rebuild:
make proto && make bins

​
Common Build Issues

​
Protoc Not Found

If you see “protoc: command not found”: 
# macOS
brew install protobuf

# Ubuntu
sudo apt install protobuf-compiler

​
Out of Date Generated Code

If you see errors about generated code: 
make proto
make go-generate

​
Build Cache Issues

go clean -cache -modcache -testcache
make clean
make bins

Build docs developers (and LLMs) love

Get started for freeTalk to us