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.
.. toctree::
:maxdepth: 1
api_guidelines
environment_variables
building
debugging
documentation_guidelines
godocs
traffic_monitor
traffic_ops
traffic_portal
traffic_router
traffic_stats
A development environment is available in :atc-file:`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 :ref:`dev-debugging-ciab`, 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 :atc-file:`infrastructure/cdn-in-a-box/docker-compose.expose-ports.yml` Compose file is included, so the two cannot be used at the same time.
The command atc is made available by sourcing :atc-file:`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 :envvar:`TO_URL`, :envvar:`TO_USER`, and :envvar:`TO_PASSWORD` to the values appropriate for the default setup of the development environment, such that :ref:`toaccess` may be used to access the development Traffic Ops instance without any extra steps.
.. program:: atc
atc [-h] OPERATION.. option:: -h, --help
Print usage information and exit.
Each valid OPERATION is outlined in its corresponding section.
Build Docker images for the environment, but do not start it.
atc build [SERVICE...].. option:: 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 buildConnect 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 :manpage:`docker(1)`.
Run a command in a dev container.
atc exec SERVICE CMD..... option:: SERVICE
The service within which to execute commands.
.. option:: 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 trafficmonitorCheck 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...].. option:: -h, --help
Print usage information and exit.
.. option:: -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/snapshotRestart 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...].. option:: 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 restartStart 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...].. option:: 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 startStop 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...].. option:: 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 stopThe atc.dev.sh file also provides a way to run :ref:`t3c-t3c` commands with debugging enabled. While in most production deployments :ref:`t3c-t3c` runs on a :manpage:`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 :ref:`t3c-t3c`. A delve debugging session is automatically started when :ref:`t3c-t3c` is run, which listens on port 8081.