106 lines
3.1 KiB
Markdown
106 lines
3.1 KiB
Markdown
# 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:
|
|
```bash
|
|
cargo install --path .
|
|
```
|
|
|
|
To print the underlying docker commands as they run, build with debug
|
|
assertions:
|
|
```bash
|
|
cargo install --path . --debug
|
|
```
|
|
|
|
## shell completion
|
|
|
|
`ahab completions <shell>` writes a completion script to stdout, for bash,
|
|
elvish, fish, powershell or zsh:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
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>
|
|
```
|
|
|
|
## django
|
|
|
|
```bash
|
|
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
|
|
|
|
```bash
|
|
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.
|
|
|
|
```bash
|
|
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_DJANGO_CONTAINER`: control which compose service is used for sending django commands - defaults to `django`
|
|
- `AHAB_POSTGRES_CONTAINER`: control which compose service is used for sending postgres commands - defaults to `db`
|
|
- `AHAB_LINK_ROOT`: root of the out-of-repo store `ahab link` moves paths into - defaults to `${XDG_DATA_HOME:-$HOME/.local/share}/ahab`
|