Getting Started

Getting Started

This guide covers building Apache Traffic Server from source and setting up a development environment.

Prerequisites

You need CMake (3.20+), Ninja, a C++20 compiler (GCC 11+ or Clang 14+), and several libraries. Install the packages for your OS below.

Fedora / CentOS / RHEL

cmake ninja-build pkgconfig gcc-c++ openssl-devel pcre2-devel
libcap-devel hwloc-devel ncurses-devel libcurl-devel

Ubuntu / Debian

cmake ninja-build pkg-config g++ zlib1g-dev libssl-dev libpcre2-dev
libcap-dev libhwloc-dev libncurses5-dev libcurl4-openssl-dev

Alpine Linux

build-base libexecinfo-dev pcre2-dev libressl-dev cmake ninja linux-headers

macOS (Homebrew)

cmake ninja pkg-config openssl pcre2

FreeBSD

cmake ninja devel/gmake devel/pkgconf security/openssl devel/pcre2 devel/hwloc

Building from Source

Quick Start

git clone https://github.com/apache/trafficserver.git
cd trafficserver
cmake --preset default
cmake --build build-default
cmake --build build-default -t test    # optional: run tests
cmake --install build-default

Using CMake Presets

The project includes CMakePresets.json with several useful presets:

Preset	Purpose
default	Standard debug build with Ninja, warnings-as-errors
dev	Development build with compile_commands.json for IDE integration
dev-asan	Development build with AddressSanitizer
release	Optimized release build, installs to /opt/ats
autest	Build configured for running AuTests

# List available presets
cmake --list-presets

# Use a preset
cmake --preset dev
cmake --build build-dev

Custom User Presets

You can create a CMakeUserPresets.json file to define your own presets that inherit from the project presets. Copy CMakePresets.json as a starting point and clear the configurePresets array, then add your own:

{
  "name": "mydev",
  "displayName": "My development preset",
  "inherits": ["dev"],
  "cacheVariables": {
    "CMAKE_INSTALL_PREFIX": "/opt/ats-dev",
    "BUILD_EXPERIMENTAL_PLUGINS": true,
    "ENABLE_JEMALLOC": true
  }
}

Common CMake Options

cmake -B build \
  -DCMAKE_INSTALL_PREFIX=/opt/ats \
  -DBUILD_EXPERIMENTAL_PLUGINS=ON \
  -DENABLE_AUTEST=ON \
  -DOPENSSL_ROOT_DIR=/opt/openssl \
  -Djemalloc_ROOT=/opt/jemalloc

Use ccmake build for an interactive configuration UI.

Building and Installing

cmake --build build              # build everything
cmake --build build -t traffic_server  # build just the server
cmake --install build            # install to prefix

Default Installation Layout

/usr/local                        (or your CMAKE_INSTALL_PREFIX)
├── bin/                          executable binaries
├── etc/trafficserver/            configuration files
├── libexec/trafficserver/        plugins
├── var/log/trafficserver/        log files (created at runtime)
└── var/trafficserver/            runtime files

Running Traffic Server

# Start
trafficserver start

# Stop
trafficserver stop

# Check status
traffic_ctl server status

# Reload configuration without restart
traffic_ctl config reload

Setting Up Your Editor

EditorConfig

The repo includes an .editorconfig file. Most editors support this natively or via plugin. Key settings:

• Line endings: LF
• Max line length: 132
• C/C++ indent: 2 spaces
• Python indent: 4 spaces
• Trailing whitespace: trimmed

clang-format Integration

The .clang-format file at the repo root defines the project's formatting rules. Most editors can use this automatically:

• VS Code: Install the C/C++ extension, it picks up .clang-format automatically
• CLion: Built-in support, auto-detects the file
• Vim: Use vim-clang-format plugin

To format from the command line:

cmake --build build --target format

Or use the helper script:

tools/clang-format.sh

clang-tidy Integration

The .clang-tidy file configures static analysis checks. Your editor can run these as you type if configured with a compile_commands.json:

cmake --preset dev   # generates compile_commands.json via CMAKE_EXPORT_COMPILE_COMMANDS=ON

Point your editor's clangd or clang-tidy at the build-dev/compile_commands.json file.

Using CI Docker Images Locally

The Docker images used in CI are publicly available. This is useful for reproducing CI failures locally:

# Pull the CI image
docker pull controller.trafficserver.org/ats/centos:8

# Run a container
docker run -it -u 1200:1200 --init --cap-add=SYS_PTRACE \
  --network=host controller.trafficserver.org/ats/centos:8 /bin/bash

# Inside the container, clone and build
cd ~
git clone https://github.com/apache/trafficserver.git
cd trafficserver
cmake --preset default
cmake --build build-default

Next Steps

• Read the Coding Style guide before submitting code
• See Contributing for the PR workflow
• Check Testing to learn how to run and write tests