Building from Source

Learn how to build Temporal Server and related tools from source

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