Docker¶

This guide covers running imbi-automations in Docker containers.

Pre-built images are available from Docker Hub and GitHub Container Registry:

aweber/imbi-automations:latest
ghcr.io/aweber-imbi/imbi-automations:latest

Running Workflows¶

docker run --rm \
    -v $(pwd)/config.toml:/opt/config/config.toml:ro \
    -v $(pwd)/workflows:/opt/workflows:ro \
    -v ~/.ssh:/home/imbi-automations/.ssh:ro \
    -e ANTHROPIC_API_KEY="$ANTHROPIC_API_KEY" \
    -e IMBI_API_KEY="$IMBI_API_KEY" \
    -e GH_TOKEN="$GH_TOKEN" \
    aweber/imbi-automations:latest \
    /opt/config/config.toml \
    /opt/workflows/my-workflow \
    --all-projects

Volume Mounts¶

Path	Purpose	Notes
`/opt/config/config.toml`	Configuration file	Mount as read-only
`/opt/workflows`	Workflow definitions	Mount as read-only
`/home/imbi-automations/.ssh`	SSH keys	Mount as read-only; enables commit signing
`/opt/dry-runs`	Dry-run artifacts	Mount if using `--dry-run`
`/opt/errors`	Error preservation	Mount if using `--preserve-on-error`
`/docker-entrypoint-init.d`	Initialization scripts	See Initialization Directory

Environment Variables¶

Required Variables¶

The following environment variables must be set when running the container. The entrypoint will exit with an error if any are missing:

Variable	Description
`ANTHROPIC_API_KEY`	Anthropic API key for Claude
`IMBI_API_KEY`	Imbi API key
`GH_TOKEN`	GitHub personal access token

Note

These variables are required even if the same values are specified in the configuration file. When running in Docker, the configuration file does not need to include anthropic.api_key, imbi.api_key, or github.token - they are automatically loaded from environment variables via pydantic-settings.

Optional Variables¶

Variable	Default	Description
`GIT_USER_NAME`	`Imbi Automations`	Git commit author name
`GIT_USER_EMAIL`	`imbi-automations@aweber.com`	Git commit author email
`GH_HOST`	`github.com`	GitHub hostname (for GitHub Enterprise)

SSH Commit Signing¶

When SSH keys are mounted to /home/imbi-automations/.ssh, the entrypoint automatically configures git commit signing:

Searches for keys in order: id_ed25519, id_rsa, id_ecdsa
Configures gpg.format ssh and commit.gpgsign true
Creates an allowed_signers file for verification

Ensure your SSH key permissions are correct before mounting:

chmod 600 ~/.ssh/id_ed25519
chmod 700 ~/.ssh

Note

For GitHub to verify signed commits, add the same SSH key as a "Signing Key" in your GitHub account settings (separate from authentication keys).

GitHub CLI Authentication¶

The gh CLI is pre-installed. Authentication is configured automatically using one of these methods (in order of precedence):

Environment variable: Set GH_TOKEN when running the container
Token file: Mount a file containing the token to /config/gh-token or ~/.config/gh/token

Using Environment Variable¶

docker run --rm \
    -e GH_TOKEN="ghp_your_personal_access_token" \
    aweber/imbi-automations:latest ...

Using Token File¶

# Create token file
echo "ghp_your_token" > gh-token

# Mount it
docker run --rm \
    -v $(pwd)/gh-token:/config/gh-token:ro \
    aweber/imbi-automations:latest ...

Required Token Scopes¶

For full functionality, your token needs:

repo - Repository access
read:org - Organization membership (for org repos)
workflow - GitHub Actions (if syncing workflows)

Initialization Directory¶

The container supports an initialization directory at /docker-entrypoint-init.d/ for installing additional packages or running setup scripts at container startup. This pattern is similar to database images like PostgreSQL's /docker-entrypoint-initdb.d.

Files are processed in sorted order (use numeric prefixes for ordering) and support three extensions:

Extension	Purpose	Processing
`.apt`	System packages	Installed via `apt-get install`
`.pip`	Python packages	Installed via `pip install -r`
`.sh`	Shell scripts	Executed with `bash`

Example Files¶

10-system.apt - System packages (one per line, comments supported):

# Build dependencies
build-essential
libpq-dev

# Other tools
jq

20-python.pip - Python packages (standard requirements format):

pandas>=2.0
sqlalchemy
requests

30-custom.sh - Custom setup script:

#!/bin/bash
npm install -g some-tool

Usage¶

Mount individual files:

docker run --rm \
    -v ./my-packages.apt:/docker-entrypoint-init.d/10-packages.apt:ro \
    -v ./requirements.pip:/docker-entrypoint-init.d/20-python.pip:ro \
    aweber/imbi-automations:latest ...

Or mount a directory containing multiple init files:

docker run --rm \
    -v ./init.d:/docker-entrypoint-init.d:ro \
    aweber/imbi-automations:latest ...

Docker Compose Example¶

services:
  imbi-automations:
    image: aweber/imbi-automations:latest
    volumes:
      - ./config.toml:/opt/config/config.toml:ro
      - ./workflows:/opt/workflows:ro
      - ./init.d:/docker-entrypoint-init.d:ro

Note

Initialization runs on every container start. For production workflows with many dependencies, consider building a custom image instead.

Debugging¶

Interactive Shell¶

docker run --rm -it \
    -v $(pwd)/config.toml:/opt/config/config.toml:ro \
    -v $(pwd)/workflows:/opt/workflows:ro \
    --entrypoint /bin/bash \
    aweber/imbi-automations:latest

View Entrypoint Output¶

The entrypoint logs configuration steps to stderr:

Configuring git commit signing with SSH key: /home/imbi-automations/.ssh/id_ed25519
Loaded GitHub token from /config/gh-token

Verify Configuration¶

Inside the container:

# Check git signing config
git config --global --list | grep -E "(gpg|sign)"

# Verify gh authentication
gh auth status

# Test SSH connection
ssh -T git@github.com

Wrapper Script Example¶

For repeated use, create a wrapper script that handles image updates, authentication, and volume mounts:

#!/bin/bash
set -e

WORKFLOW=$1
shift

# Always ensure the latest image is pulled
docker pull aweber/imbi-automations:latest

# Refresh AWS SSO credentials if using AWS Bedrock
aws sts get-caller-identity --profile my-profile > /dev/null
export $(aws configure export-credentials --format env --profile my-profile)

docker run --rm -t --group-add staff \
    -v $(pwd)/.ssh:/home/imbi-automations/.ssh:ro \
    -v $(pwd)/config.toml:/opt/config/config.toml:ro \
    -v $(pwd)/docker-entrypoint-init.d:/docker-entrypoint-init.d:ro \
    -v $(pwd)/dry-runs:/opt/dry-runs \
    -v $(pwd)/errors:/opt/errors \
    -v $(pwd):/opt/workflows:ro \
    -v /var/run/docker.sock:/var/run/docker.sock:rw \
    -e AWS_ACCESS_KEY_ID \
    -e AWS_SECRET_ACCESS_KEY \
    -e AWS_SESSION_TOKEN \
    -e GH_HOST=github.example.com \
    -e GIT_USER_NAME="Your Name" \
    -e GIT_USER_EMAIL="you@example.com" \
    --env-file .env \
    aweber/imbi-automations:latest \
    /opt/config/config.toml \
    /opt/workflows/${WORKFLOW} \
    "$@"

Key features of this script:

Pulls the latest image before each run
Refreshes AWS SSO credentials for Bedrock access
Uses --env-file .env to load secrets (containing ANTHROPIC_API_KEY, IMBI_API_KEY, GH_TOKEN)
Mounts Docker socket for workflows that use Docker actions
Passes additional arguments to the workflow via "$@"

Usage:

./run-workflow.sh my-workflow --all-projects
./run-workflow.sh my-workflow --project-id 123

Docker Compose Example¶

services:
  imbi-automations:
    image: aweber/imbi-automations:latest
    volumes:
      - ./config.toml:/opt/config/config.toml:ro
      - ./workflows:/opt/workflows:ro
      - ./.ssh:/home/imbi-automations/.ssh:ro
      - ./docker-entrypoint-init.d:/docker-entrypoint-init.d:ro
      - ./dry-runs:/opt/dry-runs
      - ./errors:/opt/errors
      - /var/run/docker.sock:/var/run/docker.sock:rw
    env_file:
      - .env
    environment:
      # Optional overrides
      - GIT_USER_NAME=Imbi Automations
      - GIT_USER_EMAIL=imbi-automations@example.com

Run with:

docker compose run --rm imbi-automations \
    /opt/config/config.toml \
    /opt/workflows/my-workflow \
    --all-projects