Docker
This page will show you how to create API models when your service lives in a Docker container, or is started by Docker Compose. Docker networking can be difficult to get working correctly; we will show a few different options that allow Akita to see your API traffic. By default, one container cannot see traffic destined for another container, so special configuration is needed in Docker.
If you are running your application in Kubernetes, see Capturing Packet Traces in Kubernetes.
Windows support
We do not yet have official Windows support for the Akita CLI. While our users have gotten Akita to work as a container within the Windows Subsystem for Linux (WSL), it does not currently work to trace Windows APIs from a Docker container in WSL.
Attach the Akita CLI to a running container
This method is the most straightforward way of capturing a single container's network traffic. However, because it involves a separate "docker run" step, it cannot be used as part of a Docker Compose script. It will also not work if your container is connected only to an internal network.
Start your service first; this can be done through docker run
or docker-compose
as usual. Find the name of the container you want to monitor. Then, start the Akita CLI and specify that it should attach to that container's network stack:
docker run --rm --network container:your-container-name \
-e AKITA_API_KEY_ID=... \
-e AKITA_API_KEY_SECRET=... \
akitasoftware/cli:latest apidump \
--service your-service-name
--filter "port 80"
This will cause the Akita CLI to be able to see all the traffic to and from the service running in the specified container. You should switch "port 80" to be the port number that your service is using (inside the container), or the filter can be omitted to capture outgoing traffic from your service as well.


As shown in the diagram above, Akita will use the same network device as the service being monitored. It will not have visibility into other containers.
Attaching to a container in Docker Compose
This configuration can be created in Docker Compose by specifying the container network as the network_mode
version'3'
services:
...
akita:
container_name: akita
image: akitasoftware/cli:latest
environment:
- AKITA_API_KEY_ID=apk_xxxxxxxx
- AKITA_API_KEY_SECRET=xxxxxxx
network_mode: "container:your-container-name"
entrypoint: /akita apidump --service your-service
Attach the Akita CLI to the host network
If you wish to monitor multiple containers simultaneously, or if the container you want to monitor is connected only to an internal network, you can attach the Akita CLI to the host network. This works with either docker run
or docker-compose
. Here's an example command line for the former:
docker run --rm --network host \
-e AKITA_API_KEY_ID=... \
-e AKITA_API_KEY_SECRET=... \
akitasoftware/cli:latest apidump \
--service your-service-name
--filter "port 80"
You should still use the port number from "inside" your service's container; Akita's packet capture sees the untranslated port instead of the externally-visible port number. In this mode, Akita can capture any container's external network traffic, and even traffic on internal networks.


Host mode is only available for Linux-based Docker.
To use host networking the Akita CLI in Docker Compose, specify network_mode: "host"
in the YAML definition, as in this example:
version'3'
services:
...
akita:
container_name: akita
image: akitasoftware/cli:0.17.0
environment:
- AKITA_API_KEY_ID=apk_xxxxxxxx
- AKITA_API_KEY_SECRET=xxxxxxx
network_mode: "host"
entrypoint: /akita apidump --service your-service
Use the Akita CLI as a wrapper for your server process
The Akita CLI can start a child process while collecting traces. You can use this feature to change the entry point of your container to the Akita CLI, have Akita start your main server process, and then capture a trace for the entire lifetime of that server process. This is a more intrusive change that requires changes to your container build process, but will work for any way that the container is run.
To capture traces this way:
- Install the Akita CLI binary in your container at build time, for example in its usual location at
/usr/local/bin/akita
. - Change the entry point of the container to call the
akita apidump
command, with the normal server command line specified using the-c
option:
...
ENTRYPOINT ["/usr/local/bin/akita", "apidump",
"-c", "normal server command line here",
"-u", "root", "--service", "your service here" ]
Separating different deployments
You may want to split the models you've created based on which cluster or environment they've come from. You can use the --deployment
flag or the AKITA_DEPLOYMENT
environment variable to attach a tag to the traces, identifying their context. All traces with the same deployment name will be combined into a single model.
The default deployment name is "default".
Running the Akita Daemon on an internal network
When running the Akita CLI in daemon mode (see Staging and Production Express.js via Middleware), it is necessary that the middleware have access to the Akita daemon, and that the Akita daemon is able to access the Akita cloud services. You can use Docker-compose to ensure that the service being monitored and the Akita CLI are connected to the same network.
If the service's network is internal, then the Akita CLI must be connected to an additional external networks. Here is an example Docker Compose file that shows how this can be done:
version: '3'
services:
test:
container_name: test
image: test-middleware:latest
networks:
- int-network
akita_daemon:
container_name: akita_daemon
image: akitasoftware/cli:0.16.2
environment:
- AKITA_API_KEY_ID=apk_xxxxxxxx
- AKITA_API_KEY_SECRET=xxxxxxx
networks:
- int-network
- ext-network
entrypoint: /akita --debug daemon --port 50080 --name my-daemon-name
networks:
ext-network:
driver: bridge
int-network:
driver: bridge
internal: true
In the Express.js middleware configuration, the daemon host would be set to akita_daemon:50080
. Docker's DNS setup ensures that the correct IP address is used.


Providing the Akita credentials in a volume
Many of the examples above specify the Akita credentials for the container as environment variables. Because the environment variables are set up on the command line, they may be exposed. A better approach is to mount the file containing your Akita credentials into the container. You can do this by using the following flag on the Docker command line:
docker run ... \
--volume ~/.akita/credentials.yaml:/root/.akita/credentials.yaml:ro
...
This maps your current user's credentials.yaml file, created with "akita login", into the container.
You can also use docker's --env-file
argument to specify environment variables in a file instead of on the command line.
Updated about 18 hours ago