TracebagContainer diagnosticsView on GitHub

Install Tracebag with Docker

These commands are complete and ordered. They install a pinned release, create the required secrets, keep the console on localhost, and connect one application explicitly.

1. Download the release configuration

Choose a released version instead of relying on a moving image tag.

mkdir tracebag && cd tracebag
export TRACEBAG_VERSION=0.1.0
curl -fsSLo compose.yaml \
  https://raw.githubusercontent.com/poodlelab/tracebag/v${TRACEBAG_VERSION}/deploy/compose.release.yaml
curl -fsSLo .env.example \
  https://raw.githubusercontent.com/poodlelab/tracebag/v${TRACEBAG_VERSION}/deploy/.env.release.example
cp .env.example .env

2. Generate the required secrets

Set a random PostgreSQL password, then use the published Tracebag image to create an ASP.NET Core password hash. The administrator password itself is not stored in .env.

POSTGRES_PASSWORD=$(openssl rand -hex 32)
sed -i.bak "s|^TRACEBAG_POSTGRES_PASSWORD=.*|TRACEBAG_POSTGRES_PASSWORD=${POSTGRES_PASSWORD}|" .env

read -rsp "Tracebag admin password: " ADMIN_PASSWORD; echo
PASSWORD_HASH=$(printf '%s\n' "${ADMIN_PASSWORD}" | \
  docker run --rm -i ghcr.io/poodlelab/tracebag:${TRACEBAG_VERSION} hash-password admin)
unset ADMIN_PASSWORD
sed -i.bak "s|^TRACEBAG_ADMIN_PASSWORD_HASH=.*|TRACEBAG_ADMIN_PASSWORD_HASH=${PASSWORD_HASH}|" .env
rm -f .env.bak
chmod 600 .env

3. Pull and launch

docker compose --env-file .env -f compose.yaml --profile runners pull
docker compose --env-file .env -f compose.yaml \
  up -d --wait tracebag-postgres tracebag

Open http://localhost:9090 and sign in as admin.

Docker socket warning: Tracebag needs Docker API access to inspect opted-in workloads and start fixed diagnostic runners. Keep it on a host you control, bind it to localhost, and read the security model.

4. Opt in an application

Tracebag ignores containers without the explicit enablement label.

services:
  api:
    labels:
      tracebag.enabled: "true"
      tracebag.logs.persist: "true"

Enable .NET diagnostics

Share a named /tmp volume so Tracebag's temporary runner can reach the runtime diagnostic socket. The label value must be the actual Docker volume name.

services:
  api:
    environment:
      DOTNET_EnableDiagnostics: "1"
    volumes:
      - tracebag-dotnet-tmp:/tmp
    labels:
      tracebag.enabled: "true"
      tracebag.kind: dotnet
      tracebag.dotnet.runtime: "8"
      tracebag.dotnet.tmpVolume: my-api-tracebag-dotnet-tmp

volumes:
  tracebag-dotnet-tmp:
    name: my-api-tracebag-dotnet-tmp

5. Verify and operate

curl --fail http://localhost:9090/health/ready
docker compose --env-file .env -f compose.yaml logs -f tracebag

# Stop while retaining data
docker compose --env-file .env -f compose.yaml down

Never add --volumes to the final command unless you intend to delete Tracebag's database and stored evidence.

Run the demoDetailed operations guide