#+TITLE:   tools/docker
#+DATE:    April 30, 2019
#+SINCE:   {replace with next tagged release version}
#+STARTUP: inlineimages

* Table of Contents :TOC_3:noexport:
- [[#description][Description]]
  - [[#module-flags][Module Flags]]
  - [[#plugins][Plugins]]
- [[#prerequisites][Prerequisites]]
- [[#todo-features][TODO: Features]]
  - [[#docker-control][Docker control]]
    - [[#supported-commands][Supported commands]]
  - [[#tramp][TRAMP]]
- [[#configuration][Configuration]]
  - [[#popups][Popups]]
  - [[#dockerfile-mode][dockerfile-mode]]
- [[#troubleshooting][Troubleshooting]]
  - [[#tramp-hangs-on-alpine-container][Tramp hangs on Alpine container]]

* Description

This package allows you to manipulate docker images, containers & more from Emacs.

Provides a major mode `dockerfile-mode' for use with the standard
`Dockerfile' file format.  Additional convenience functions allow
images to be built easily.

docker-tramp.el offers a TRAMP method for Docker containers.

** Module Flags
This module provides no flags.

** Plugins
 + [[https://github.com/Silex/docker.el][docker]]
 + [[https://github.com/emacs-pe/docker-tramp.el][docker-tramp]]
 + [[https://github.com/spotify/dockerfile-mode][dockerfile-mode]]

* Prerequisites
This modules assumes `docker`, `docker-compose` and `docker-machine` binaries are
installed and accessible from your PATH.

* TODO: Features
** Docker control

Use =M-x docker=, select a resource then then mark or unmark items using the following keybindings (for more
marking possibilities, check out https://github.com/politza/tablist):

| Binding   | Description          |
|-----------+----------------------|
| =?=       | List actions         |
| =l=       | Configure listing    |
| =m=       | Mark item            |
| =u=       | Unmark item          |
| =t=       | Toggle marks         |
| =U=       | Unmark all           |
| =s=       | Sort                 |
| =* r=     | Mark items by regexp |
| =<=       | Shrink column        |
| =>=       | Enlarge column       |
| =C-c C-e= | Export to csv        |

*** Supported commands
- docker container: attach, cp, diff, inspect, kill, logs, pause, rename, restart, rm, start, stop, unpause
- docker image: inspect, pull, push, rm, run, tag
- docker network: rm
- docker volume: rm
- docker-machine: create, env, restart, rm, start, stop
- docker-compose: build, config, create, down, exec, logs, pull, push, remove,
  restart, run, start, stop, up

  You can also enter `dired` or open a file inside a container or volume.

** TRAMP

Offers the TRAMP method `docker` to access running containers

    C-x C-f /docker:user@container:/path/to/file

    where
      user           is the user that you want to use (optional)
      container      is the id or name of the container


* Configuration
** Popups

Thanks to [magit-popup](https://github.com/magit/magit-popup), all the popups default arguments can be customized. For
example, here is how to customize the arguments for `docker-image-run-popup`:

#+BEGIN_SRC emacs-lisp
(setq docker-image-run-arguments '("-i" "-t" "--rm"))
#+END_SRC

or inside a use-package declaration:

#+BEGIN_SRC emacs-lisp
(use-package docker
  :ensure t
  :bind ("C-c d" . docker)
  :custom (docker-image-run-arguments '("-i" "-t" "--rm")))
#+END_SRC

You can also customize these using =M-x customize-variable=.

### Others

| Variable                          | Description                           | Default          |
|-----------------------------------+---------------------------------------+------------------|
| docker-command                    | The docker binary to use              | `docker`         |
| docker-container-default-sort-key | Sort key for docker containers        | `("Image")`      |
| docker-container-shell-file-name  | Shell to use when entering containers | `/bin/bash`      |
| docker-image-default-sort-key     | Sort key for docker images            | `("Repository")` |
| docker-machine-default-sort-key   | Sort key for docker machines          | `("Name")`       |
| docker-network-default-sort-key   | Sort key for docker networks          | `("Name")`       |
| docker-run-as-root                | Run docker as root                    | `nil`            |
| docker-volume-default-sort-key    | Sort key for docker volumes           | `("Driver")`     |

** dockerfile-mode

By default, the keyword completion function detects the docker-compose version of the current buffer and suggests the appropriate keywords.

You can change the candidates offered by the backend by customizing docker-compose-keywords

* Troubleshooting

** Tramp hangs on Alpine container

Busyboxes built with the `ENABLE_FEATURE_EDITING_ASK_TERMINAL' config option
send also escape sequences, which `tramp-wait-for-output' doesn't ignores
correctly.  Tramp upstream fixed in [98a5112][] and is available since
Tramp>=2.3.

For older versions of Tramp you can dump [docker-tramp-compat.el][] in your
`load-path' somewhere and add the following to your `init.el', which
overwrites `tramp-wait-for-output' with the patch applied:

    (require 'docker-tramp-compat)

[98a5112]: http://git.savannah.gnu.org/cgit/tramp.git/commit/?id=98a511248a9405848ed44de48a565b0b725af82c
[docker-tramp-compat.el]: https://github.com/emacs-pe/docker-tramp.el/raw/master/docker-tramp-compat.el