<commit_before>#+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<commit_msg>tools/docker: Update README.org<commit_after>#+TITLE:   tools/docker
#+DATE:    April 30, 2019
#+SINCE:   v2.0.9
#+STARTUP: inlineimages

* Table of Contents :TOC_3:noexport:
- [[#description][Description]]
  - [[#module-flags][Module Flags]]
  - [[#plugins][Plugins]]
- [[#prerequisites][Prerequisites]]
- [[#features][Features]]
  - [[#docker-control][Docker control]]
    - [[#supported-commands][Supported commands]]
  - [[#tramp][TRAMP]]
- [[#configuration][Configuration]]
  - [[#popups][Popups]]
    - [[#other-useful-variables][Other useful variables]]
  - [[#completion-in-dockerfiles][Completion in Dockerfiles]]
- [[#troubleshooting][Troubleshooting]]
  - [[#tramp-hangs-on-alpine-container][Tramp hangs on Alpine container]]

* Description
This module allows you to manipulate Docker images, containers & more from
Emacs.

Provides a major =dockerfile-mode= to edit =Dockerfiles=. Additional
convenience functions allow images to be built easily.

=docker-tramp.el= offers a [[https://www.gnu.org/software/tramp/][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 module assumes =docker=, =docker-compose= and =docker-machine= binaries
are installed and accessible from your PATH.

* Features
** Docker control
Use =M-x docker=, select a resource, and 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 [[https://www.gnu.org/software/tramp/][TRAMP]] method =docker= to access running containers.

#+BEGIN_EXAMPLE
C-x C-f /docker:user@container:/path/to/file
#+END_EXAMPLE

| =user=      | the user that you want to use (optional) |
| =container= | the id or name of the container          |

* Configuration
** Popups
Thanks to [[https://github.com/magit/magit-popup][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=.

*** Other useful variables
| 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")=     |

** Completion in Dockerfiles
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
also send escape sequences, which =tramp-wait-for-output= doesn't ignore
correctly. This was [[http://git.savannah.gnu.org/cgit/tramp.git/commit/?id=98a511248a9405848ed44de48a565b0b725af82c][fixed in TRAMP upstream]] and is available since TRAMP 2.3.

For older versions of TRAMP you can dump [[https://github.com/emacs-pe/docker-tramp.el/blob/master/docker-tramp-compat.el][docker-tramp-compat.el]] in your
=load-path= somewhere and add the following to your =init.el= to overwrite
=tramp-wait-for-output= with the patch applied:

#+BEGIN_SRC emacs-lisp
(require 'docker-tramp-compat)
#+END_SRC
{'fraction_non_alphanumeric': 0.159020288795467, 'fraction_numerical': 0.008133796380917565, 'mean_word_length': 2.8558844256518676, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 6, 'https://': 14, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3605067', 'n_tokens_mistral': 3602, 'n_tokens_neox': 3336, 'n_words': 977}