Antithesis logomark
Docs

Docker Compose setup guide

This is a step-by-step guide to setting up your software to run in Antithesis.

This guide will walk you through orchestrating your software with Docker Compose and pushing it to the Antithesis registry.

If you’re running your software with Kubernetes, follow the Kubernetes setup guide instead.

Requirements

  1. Make sure you have an Antithesis API key, or SSO enabled in Snouty CLI. Contact us to request one.

  2. Make sure your software is packaged as Linux container images ready to run without internet access. See Containerizing your software for details.

If you run into trouble, or simply want to make sure your testing is as thorough as possible, our solutions engineering team would be happy to help — email us at support@antithesis.com or join our Discord.

Set up container orchestration

We expect you to deliver a container image that contains a specific directory structure of what to run. We call this the config image.

In this image, include:

  • Any configuration files expected by the containers: license files, settings, environment variables file, or other resources.
  • A container orchestration file, docker-compose.yaml.

The docker-compose.yaml file in this directory lists each of the services you want to have running, the container image that the service should be started from, any external volumes that should be mounted into that container, and other options.

Here’s an example docker-compose.yaml which uses a .env file to declare environment variables. Docker Compose offers multiple ways to set environment variables within your containers.

# env variables
POSTGRES_ROOT_PASSWORD=your_root_password
POSTGRES_DATABASE_NAME=your_database_name
POSTGRES_USERNAME=your_user_name
POSTGRES_PASSWORD=your_user_password
version: '3.0'
services:
application1:
container_name: application1
hostname: application1
image: mycompany/my_app_1:my_tag
application2:
container_name: application2
hostname: application2
image: mycompany/my_app_2:my_tag
database:
container_name: database
hostname: database
image: docker.io/library/postgres:17.2
environment:
POSTGRES_ROOT_PASSWORD: ${POSTGRES_ROOT_PASSWORD}
POSTGRES_DATABASE: ${POSTGRES_DATABASE_NAME}
POSTGRES_USER: ${POSTGRES_USERNAME}
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
volumes:
- ./volumes/database:/usr/bin/database/data

This is often the trickiest part of the process for users who don’t already deploy software in containers. If you simply follow the example above, you should be on solid ground, but if you run into trouble, here are a few resources you might find helpful:

To build your config image, copy all configuration files and add them to a scratch image:

FROM scratch
COPY docker-compose.yaml /docker-compose.yaml

Here are the contents of our example config directory:

$ ls -a config/
.
..
docker-compose.yaml
license

Add a ready signal for fuzzing

Before running any tests, Antithesis initializes your software and its dependencies. Once your system is up and running, it should emit a setup_complete message to initiate testing.

Our SDKs provide pre-built ways to emit this message. If you cannot use our SDKs, write the following JSONL message to $ANTITHESIS_OUTPUT_DIR/sdk.jsonl — in our environment, we’ll ensure that this variable and the directory it points to always exist.

{"antithesis_setup": { "status": "complete", "details": {"message": "Set up complete - ready for testing!" }}}

Test your setup locally

To test your container orchestration locally, from inside your config directory, run:

$ docker-compose up

This should produce a running system.

However, we want to test that this all still works without any access to the internet. If you’re on a Linux machine, first enter a network namespace before running the command:

$ pwd
/home/user/config
$ unshare -n
[2] $ docker-compose up
...
[Lots of output]
...

If everything still comes up and works, and your services all find each other, then the hardest part is done. Now you’re ready to deploy to the Antithesis environment for testing!

Push your images

Push your custom and non-public images, including your config image, to your tenant’s registry. You don’t need to copy public images, such as docker.io/library/postgres:17.2, to the Antithesis registry. Use them directly in your config files.

Starting with Antithesis v67, your registry is at registry.$TENANT_NAME.antithesis.com. You log in to it with your Antithesis API key or with SSO via Snouty, so you no longer need a separate key file.

Keep using your key file, $TENANT_NAME.key.json, and your old registry. To log in, run:

$ cat $TENANT_NAME.key.json | docker login -u _json_key https://us-central1-docker.pkg.dev --password-stdin

Then tag and push your images to us-central1-docker.pkg.dev/molten-verve-216720/$TENANT_NAME-repository/. For example:

$ docker tag my_app:my_tag us-central1-docker.pkg.dev/molten-verve-216720/$TENANT_NAME-repository/my_app:my_tag
$ docker push us-central1-docker.pkg.dev/molten-verve-216720/$TENANT_NAME-repository/my_app:my_tag

Push with Snouty

You need Snouty 0.11 or later.

  1. Run snouty login and sign in with an API key or SSO.
  2. Build your images on your machine. Snouty doesn’t build or pull images. It uses the ones you already have.
  3. Run snouty validate to start your system locally and check your setup.
  4. Run snouty launch. It pushes your images and starts the run.

For example:

$ snouty login
$ snouty validate ./config
$ snouty launch --launcher basic_test --config ./config \
--test-name "my-test" \
--description "first test run" \
--duration 30m

You don’t need to tag your images with the registry address. Keep the image names in your docker-compose.yaml as they are. When you launch, Snouty:

  • Tags each of your images with your registry address and pushes it.
  • Pins each image to its exact digest, e.g., mycompany/my_app_1:my_tag@sha256:…. Antithesis runs exactly the images that snouty validate ran on your machine.
  • Builds your config image from the ./config directory and pushes it.

With Docker 28.3.0 or later, or any version of Podman, that’s all. Snouty gives Docker the password itself and doesn’t change your Docker config.

With an older version of Docker, you need to tell Docker to get the password from Snouty. Add this to ~/.docker/config.json:

{
"credHelpers": {
"registry.$TENANT_NAME.antithesis.com": "snouty"
}
}

Push by hand

Log in with Docker and enter your API key when asked for a password:

$ docker login registry.$TENANT_NAME.antithesis.com -u antithesis

Then tag and push your images. Tag each image with the name your docker-compose.yaml uses. For example, for a local image named my_app:

$ docker tag my_app:my_tag registry.$TENANT_NAME.antithesis.com/my_app:my_tag
$ docker push registry.$TENANT_NAME.antithesis.com/my_app:my_tag

The same commands work with podman.

Push from CI

Set these environment variables in your CI. Store the API key as a secret.

ANTITHESIS_TENANT=$TENANT_NAME
ANTITHESIS_API_KEY=<your_api_key>

snouty launch reads them and logs in for you. You don’t need a login step or key files.

What you can’t do

Your registry only accepts pushes. You can push images and check which images and tags are there. You can’t pull images back out or delete them. For example, docker pull fails with a 405 error.

Run in Antithesis

Your software is now ready to run in Antithesis!

To check your setup is working correctly, launch a first test run in the web app in setup mode. Go to the Test launchers page at https://$TENANT_NAME.antithesis.com/test-launchers, and select Basic Test with the Setup mode option checked. Enter a duration of 15 minutes and click Launch the setup run.

Setup mode streams your build and setup logs, and lets you iterate on your config files until you’re ready to launch a full test.

Once you’re happy with your setup, you can either:

  • Launch a full test run straight away and learn how to view test results
  • Write your first test to exercise your system and start finding bugs, then launch a test run

Launch a test run

To launch a full run, go back to the Test launchers page and launch another Basic Test with Setup mode unchecked. Select Launch the test run.

You can also launch tests through Snouty CLI or through your CI. See Launching tests for more details.

You can view results stream in to the Logs Explorer. When your run is finished, you can view the full results in the triage report.

Write your first test

To test your system and find bugs, Antithesis needs to exercise your software. We do this using a test template — code that makes your software do something.

As a first test of your setup, you can take one of your existing integration tests and run it as a singleton test (a test that runs once in a given test timeline). To do this, use the following naming conventions to enable Antithesis to detect and run your test. These conventions should be followed exactly.

  1. Create a directory called /opt/antithesis/test/v1/quickstart in any of your containers.

  2. Paste an existing integration test into an executable named singleton_driver_<your_test_name>.<extension> in the directory you just created. Make sure your executable has an appropriate shebang in the first line, e.g. #!/usr/bin/env bash

Now you’ll need to validate that your system can find the test template you just defined — details here. The easiest way to do this is to call docker compose exec on your test command and see if it runs.

$ docker compose exec <your_service_name> /opt/antithesis/test/v1/quickstart/singleton_driver_<your_test_name>

Once you’ve written a test, run setup mode again and then launch a full test run.

See Writing tests for more advanced testing practices, like using parallel tests or adding assertions.