Matej Janežič
9d63233d9a
ahab guessed that the django service is called django and the postgres one db, falling back on AHAB_DJANGO_CONTAINER and AHAB_POSTGRES_CONTAINER. The standard project layout happens to agree, but nothing enforces it, and a stack naming them web and database could not use ahab without setting both variables. One `docker compose config --format json` call, roughly 120ms, resolves the stack even while it is down, and the services are identified from what they are rather than what they are called: - postgres is the service whose image is a postgres flavour, matching postg, timescale, pgvector or citus. Nothing else counts. - django is the service that both builds an image and has DJANGO_SETTINGS_MODULE in its environment. A celery worker sharing the same build and env_file matches too, so published ports break the tie: the service answering requests wins. Neither guess is allowed to be wrong quietly. No match, or two candidates that cannot be told apart, is an error naming the services it looked at. There is no variable to fall back on: both container variables are gone, along with the guessed defaults they backed up, so an ambiguous stack is fixed in the compose file rather than worked around per developer. Every service lookup goes through these rules, so `compose exec` and the whole django group agree on which container they mean. POSTGRES_USER and POSTGRES_DB come off the detected service, so dropdb, createdb, pg_restore and pg_dump stop assuming the role and database are both literally `db`, falling back to that only when the service declares neither. Note that env_file entries are merged into a service's environment, so POSTGRES_* is not safe for identifying the database service: one such line in a project's .env would make the django service match as well. That is why identification uses the image and only credentials use the environment. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
ahab
A wrapper around docker compose for our dockerized django projects, so the
same commands work in every repository.
installing
You will need rust installed. Clone repo and run:
cargo install --path .
To print the underlying docker commands as they run, build with debug assertions:
cargo install --path . --debug
shell completion
ahab completions <shell> writes a completion script to stdout, for bash,
elvish, fish, powershell or zsh:
ahab completions zsh > ~/.local/share/zsh/completions/_ahab
eval "$(ahab completions zsh)" # or one line in .zshrc, never goes stale
Completions are also generated during the build. They land in
target/*/build/*/out/ by default, and SHELL_COMPLETIONS_DIR_<SHELL>
installs a single shell's file straight into place:
SHELL_COMPLETIONS_DIR_ZSH=~/.local/share/zsh/completions \
SHELL_COMPLETIONS_DIR_FISH=~/.config/fish/completions \
cargo install --path .
SHELL_COMPLETIONS_DIR writes every shell into one directory instead.
the compose file
ahab does not pass -f. docker compose finds the file itself, so set
docker's own COMPOSE_FILE when it is not in the working directory, including
its base.yaml:override.yaml form. A project's .env is a good place for it,
since docker reads that too:
COMPOSE_FILE=docker/docker-compose.yaml
compose
Wrappers around the matching docker compose call, plus exec and bash
which default to the django service.
ahab compose up # also build, down, ps, start, stop
ahab compose rebuild # stop, build, up
ahab compose restart # stop, up, so containers are recreated
ahab compose bash # shell in the django service
ahab compose exec <cmd>
service detection
ahab finds the services it needs in docker compose config, so they can be
named anything:
- postgres: the service whose image is a postgres flavour, matching
postg,timescale,pgvectororcitus - django: the service that both builds an image and sets
DJANGO_SETTINGS_MODULE. A worker sharing the same build andenv_filematches too, so the one publishing ports wins
If nothing matches, or two candidates cannot be told apart, ahab says so and
lists the services it looked at rather than guessing.
POSTGRES_USER and POSTGRES_DB are read off the detected postgres service, so
dropdb, createdb, pg_restore and pg_dump use the role and database the
project declares, falling back to db when it declares neither.
django
ahab django manage <args> # manage.py in a fresh container
ahab django makemigrations
ahab django migrate <args>
ahab django shell
ahab django test
ahab django make-command <app> <name>
postgres
ahab postgres dump <path> # pg_dump, custom format
ahab postgres import <path> # drop, create, pg_restore
link
ahab link moves untracked paths out of the repository into an out-of-repo
store and symlinks them back, so a sandbox that mounts the repository sees a
dangling symlink instead of the contents, while the host resolves it as before.
ahab link add .env secrets/ # move out, leave symlinks behind
ahab link check # what a sandbox can still read
ahab link check --porcelain # `<code> <path>`, for scripts
The store lives under
${XDG_DATA_HOME:-$HOME/.local/share}/ahab/<host>/<owner>/<repo>/, derived
from the git origin remote.
configuration
Currently ahab respects the following environment variables.
AHAB_LINK_ROOT: root of the out-of-repo storeahab linkmoves paths into - defaults to${XDG_DATA_HOME:-$HOME/.local/share}/ahab