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.
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.
atc build [SERVICE...]
- SERVICE
If specified, only the given services will be built. By default, all services are built.
# 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.
atc exec SERVICE CMD...
- SERVICE
The service within which to execute commands.
- CMD
An argv to pass to the service as a command.
# 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.
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.
# 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.
atc restart [SERVICE...]
- SERVICE
If specified, only the given services will be restarted. By default, all services are restarted.
# 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).
atc start [SERVICE...]
- SERVICE
If specified, only the given services will be started. By default, all services are started.
# 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.
atc stop [SERVICE...]
- SERVICE
If specified, only the given services will be built. By default, all services are built.
# 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.