Developer’s Guide

Use this guide to start developing applications that consume the Traffic Control APIs, to create extensions to Traffic Ops, or work on Traffic Control itself.

The Development Environment

A development environment is available in dev/. This environment only depends on Docker (version 20+) and Docker-Compose <https://docs.docker.com/compose/ (version 1.27+) and enables rapid changes to be made to components during active development. This is, in general far faster than Debugging inside CDN-in-a-Box, but covers less complex configurations for testing purposes. Continuous Integration typically makes use of CDN-in-a-Box, so developers in general are free to use the Development Environment.

Note

Many ports used by the development environment clash with those exposed locally by CDN-in-a-Box when the infrastructure/cdn-in-a-box/docker-compose.expose-ports.yml Compose file is included, so the two cannot be used at the same time.

atc

The command atc is made available by sourcing dev/atc.dev.sh (e.g. source dev/atc.dev.sh). While at the repository root, this command can be used to manipulate the development environment - most notably stopping and starting it.

Sourcing this file also sets TO_URL, TO_USER, and TO_PASSWORD to the values appropriate for the default setup of the development environment, such that toaccess may be used to access the development Traffic Ops instance without any extra steps.

#166 atc Usage
atc [-h] OPERATION
-h, --help

Print usage information and exit.

Each valid OPERATION is outlined in its corresponding section.

build

Build Docker images for the environment, but do not start it.

#167 atc build Usage
atc build [SERVICE...]
SERVICE

If specified, only the given services will be built. By default, all services are built.

#168 atc build Example
# Build only Traffic Ops
atc build trafficops

# Build all services
atc build

connect

Connect to a shell session inside a development container.

Note

Connecting to trafficrouter will result in connecting as a non-root user, so privileged access requires a more careful, manual use of docker(1).

exec

Run a command in a dev container.

#169 atc exec Usage
atc exec SERVICE CMD...
SERVICE

The service within which to execute commands.

CMD

An argv to pass to the service as a command.

#170 atc exec Example
# Check ping statistics for communications from Traffic Ops to Traffic Monitor.
atc exec trafficops ping -c 4 trafficmonitor

ready

Check if the development environment is ready. If it is ready the exit code is 0, and if it isn’t ready the exit code is non-zero. “Readiness” is defined by the availability of the Traffic Ops API.

#171 atc ready [-h] [-w] Usage
atc ready [SERVICE...]
-h, --help

Print usage information and exit.

-w, --wait

Wait for ATC to be ready, instead of just checking if it is ready.

#172 atc ready Example
# Print "ready" if ATC is ready, "not ready" if it isn't.
if atc ready; then
    echo "ready";
else
    echo "not ready";
fi

# Block until ATC is ready before getting a CDN Snapshot for the development CDN.
atc ready -w && toget -k cdns/dev/snapshot

restart

Restart the development environment. This is functionally equivalent to stop followed by start where the same arguments that would be passed to restart are instead given to each of those.

Warning

Restarting Traffic Ops also stops every service that either it depends on or that depends on it - which is all of them. However, it only starts the services that Traffic Ops depends on, which is only the database service. So atc restart trafficops stops everything and only starts Traffic Ops back up again.

Tip

The services automatically rebuild the ATC components they run when those components change, so usually restarting is only necessary if you’re making changes to the developer environment itself.

#173 atc restart Usage
atc restart [SERVICE...]
SERVICE

If specified, only the given services will be restarted. By default, all services are restarted.

#174 atc restart Example
# Restart only Traffic Router
atc restart trafficrouter

# Restart all services
atc restart

start

Start up the development environment.

Note

Starting Traffic Ops also starts the Traffic Ops database and Traffic Vault (which isn’t its own service).

#175 atc start Usage
atc start [SERVICE...]
SERVICE

If specified, only the given services will be started. By default, all services are started.

#176 atc start Example
# Start only Traffic Portal
atc start trafficportal

# Start all services
atc start

stop

Stop the development environment.

Note

Stopping Traffic Ops also stops every service that either it depends on or that depends on it - which is all of them.

#177 atc stop Usage
atc stop [SERVICE...]
SERVICE

If specified, only the given services will be built. By default, all services are built.

#178 atc stop Example
# Stop only Traffic Router
atc stop trafficrouter

# Stop all services
atc stop

t3c

The atc.dev.sh file also provides a way to run t3c-t3c commands with debugging enabled. While in most production deployments t3c-t3c runs on a cron(8) schedule, it is never run in the development environment, normally. One must manually trigger a run in order to run it and debug it.

The usage of this provided function is exactly as if one were simply calling t3c-t3c. A delve debugging session is automatically started when t3c-t3c is run, which listens on port 8081.