github.com/MichaelDarr/ahab@v0.0.0-20200528062404-c74c5106e605/README.md (about) 1 # Ahab 2 #### Configure, launch, and work in Dockerized environments 3   4 5 [](https://goreportcard.com/badge/github.com/MichaelDarr/ahab) [](https://godoc.org/github.com/MichaelDarr/ahab/internal) [](https://github.com/MichaelDarr/ahab/blob/master/LICENSE) 6 7 Containerization is awesome, but the upfront costs of project setup and steep learning curve can 8 make it a pain. Ahab is a CLI tool that jump-starts this process, avoiding frustration without 9 obfuscating your workflow. 10 11 When invoked at the command line, `ahab` searches the current directory (and its parents, 12 recursively) for a file `ahab.json`. Its contents describe the manner in which Ahab will create and 13 interact with a project's Docker container. The Ahab CLI supports all Docker container commands 14 without having to specify a container name or ID - the container described by `ahab.json` is 15 automatically targeted. For example, `docker rm [container_id]` becomes `ahab rm`. Additionally, 16 Ahab introduces new commands such as `bash`, `up`, and `status` - a full list can be found 17 [here](#commands). Ahab provides everything you need to quickly and effectively develop a 18 containerized project. 19 20 ## Table of Contents 21 * [Installation](#installation) 22 * [Commands](#commands) 23 * [Configuration Reference](#configuration-reference) 24 * [Key Features](#key-features) 25 * [FAQ](#faq) 26 27 ## Installation 28 29 ### Arch Linux 30 | AUR Package | Builds From 31 | :-- | :-- 32 | [](https://aur.archlinux.org/packages/ahab/) | Latest Release 33 | [](https://aur.archlinux.org/packages/ahab-git/) | Github Master Branch 34 35 ### Ubuntu (bionic, eoan, focal, groovy, xenial) 36 ```sh 37 $ sudo add-apt-repository ppa:michaeldarr/ppa 38 $ sudo apt update 39 $ sudo apt install ahab 40 ``` 41 42 ### Other (From Source) 43 44 **Prerequisites:** 45 * git 46 * go (tested on 1.13.7) 47 * make 48 49 ```sh 50 $ git clone git@github.com:MichaelDarr/ahab.git 51 $ cd ahab 52 $ make # or, `make self` to build ahab *with* ahab (prerequisites: Docker, Ahab) 53 $ make install 54 ``` 55 56 ## Commands 57 Ahab supports all Docker container commands as described [here](#Ahab). For more information, use 58 `ahab [command] --help` or visit the 59 [Docker CLI reference](https://docs.docker.com/engine/reference/commandline/cli/). Listed below are 60 supplemental commands introduced by Ahab. 61 62 | Command | Description 63 | :-------------------- | :-- 64 | `bash`, `sh`, `zsh` | Shell-specific container terminal access 65 | `cmd` | Execute an in-container command, attaching the input/output to your terminal 66 | `down` | Stop and remove the container 67 | `ls` | List all containers, images, and volumes on your machine 68 | `ls{c,i,v}` | List one Docker asset type, e.g. `lsc`ontainers 69 | `prune` | Remove all unused Docker assets on your machine 70 | `status` | Print a human-friendly container status report 71 | `up` | Create and start the container 72 73 ## Configuration Reference 74 **Note:** All string-type configuration fields support environment variable expansion in the forms 75 `${var}` and `$var`. 76 77 ### Project Configuration: `ahab.json` 78 79 | Field | Type | Default | Description 80 | :-------------------- | :------------ | :------------ | :-- 81 | `ahab` | string | **REQUIRED** | Minimum Ahab version required to launch a project 82 | `buildContext` | string | `ahab.json`'s directory | Docker build context (if using `dockerfile` instead of `image`) 83 | `command` | string | `top -b` | [See Docker Reference](https://docs.docker.com/engine/reference/run/#cmd-default-command-or-options) 84 | `dockerfile` | string | None | Dockerfile used to build container image (required if `image` not present) 85 | `entrypoint` | string | None | [See Docker Reference](https://docs.docker.com/engine/reference/run/#entrypoint-default-command-to-execute-at-runtime) 86 | `environment` | [string] | [] | List of `KEY=VALUE` environment variables to set in the container 87 | `hostname` | string | None | Container host name 88 | `image` | string | None | Docker image used by the container (required if `dockerfile` not present) 89 | `init` | [string] | [] | List of commands to be run as root immediately after container creation 90 | `name` | string | None | Manually assign a name to the container instead of generating it from the config path 91 | `options` | [string] | [] | List of options passed during container creation 92 | `permissions` | {[permissions](#permissions)} | {} | See [Permissions](#permissions) 93 | `restartAfterSetup` | boolean | false | If true, the container restarts after permissions are set up and `init` commands are run 94 | `shareDisplay` | boolean | false | If true, processes within the container can launch windows onto the host's display (supports wayland and X11) 95 | `user` | string | `ahab` | User for container commands after initial setup 96 | `volumes` | [string] | [] | List of volumes to mount during container creation 97 | `workdir` | string | None | [See Docker Reference](https://docs.docker.com/engine/reference/run/#workdir) 98 99 #### Permissions 100 101 | Field | Type | Default | Description 102 | :-------- | :-------- | :-------- | :-- 103 | `cmdSet` | string | None | Commands to use while setting permissions. If using a BusyBox-based image, set to `busybox` 104 | `disable` | boolean | false | If true, Ahab does not set up any user permissions or create the `ahab` user 105 | `groups` | [string] | [] | Groups the `ahab` user belongs to. If a group does not yet exist in-image, prefix it with a `!`, e.g. `"groups": ["!docker"]` 106 107 ### User Configuration: `~/.config/ahab/config.json` 108 109 | Field | Type | Default | Description 110 | :-------------------- | :------------ | :------------ | :-- 111 | `environment` | [string] | [] | List of extra `KEY=VALUE` environment variables to set in containers 112 | `hideCommands` | boolean | false | If true, Ahab will not print Docker commands before it runs them 113 | `options` | [string] | [] | List of extra options passed during container creation 114 | `volumes` | [string] | [] | List of extra of volumes to mount during container creation 115 116 ## Key Features 117 118 ### Container Permissions, Solved 119 Never worry about file permissions in your bind-mounted directories again. Ahab sets up a non-root 120 user inside your container with the proper credentials to create, remove, and edit bind-mounted 121 files while maintaining their existing permissions. It does this in a highly configurable and 122 transparent manner so you have complete control over your project. 123 124 ### Git-Style Configuration 125 Ahab looks for the `ahab.json` file like `git` looks for the `.git` folder. If there is no config 126 file in the current directory, Ahab searches its parent directories recursively until `ahab.json` 127 is found or the root of the file system is reached. With this system, it's easy to manage multiple 128 containers on a single machine, or even in a single project. Internally, Ahab leverages this 129 feature to run its test suite (`test/ahab.json`) and build distribution-specific packages 130 (`build/deb/ahab.json`). 131 132 ### Stateless Operation 133 Ahab has no internal state and never writes to any files. Each invocation is a blank slate, so you 134 never end up with a bad installation or inexplicable errors. Additionally, since Ahab is an 135 independent compiled binary instead of an interpreted python package (like `docker-compose`), you 136 don't have to worry about machine-specific interpreter/dependency issues. 137 138 ### Transparent Behavior 139 Ahab acts like a developer, only using Docker commands to interact with containers. The commands run 140 by Ahab are printed directly in the shell, so you know exactly what it's doing - there's no "magic" 141 here. This has two major benefits: 142 143 1. It's easy to replace Ahab with other tooling if needed 144 2. Your own Docker CLI skills improve as you use Ahab 145 146 ### Universal Image Support 147 With Ahab's robust configuration options, you don't need to manage custom images or Dockerfiles for 148 your containerized projects! You can set up users/groups, install new packages, and utilize arbitrary 149 container options all without a single Dockerfile or shell script. 150 151 ## FAQ 152 153 ### How is this different than docker-compose? 154 Ahab was created in response to frustration with docker-compose. One issue with docker-compose is 155 its lag time behind Docker itself. Since docker-compose is a python package which interfaces with 156 Docker via docker-py, the docker-compose team has to wait on docker-py for feature support. At the 157 time of writing, the `--gpus` option is unsupported by docker-compose 7 months after its release in 158 Docker CE. Ahab's arbitrary container options entirely avoid this issue. 159 160 A second concern over docker-compose is its distribution mechanism as a python package. For teams 161 of developers, this can be problematic due to inconsistent python package management and dependency 162 tree conflicts. Internal tooling to extend docker-compose further exacerbates these issues. In 163 contrast, Ahab is installed as a standalone binary executable. 164 165 Lastly, docker-compose and Ahab serve two very different project archetypes. The ability to run 166 multiple interdependent containers is needed only by a minority of projects; for most, only a 167 single well-configured environment is required. Here, Ahab thrives with its simpler config files, 168 development-ready environments, and gentler learning curves. New, volatile projects especially 169 benefit from Ahab's commitment to transparency and replaceability.