doomemacs/modules/tools/docker/README.org

#+title:    :tools docker
#+subtitle: Yo dawg, I heard you like OSes, so I…
#+created:  September 06, 2018
#+since:    21.12.0

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

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

[[doom-package:][docker-tramp]] offers [[https://www.gnu.org/software/tramp/][TRAMP]] support for Docker containers.

** Maintainers
/This module has no dedicated maintainers./ [[doom-contrib-maintainer:][Become a maintainer?]]

** Module flags
- +lsp ::
  Enable integration for the Dockerfile Language Server.

** Packages
- [[doom-package:][docker]]
- [[doom-package:][docker-tramp]]
- [[doom-package:][dockerfile-mode]]

** Hacks
/No hacks documented for this module./

** TODO Changelog
# This section will be machine generated. Don't edit it by hand.
/This module does not have a changelog yet./

* Installation
[[id:01cffea4-3329-45e2-a892-95a384ab2338][Enable this module in your ~doom!~ block.]]

This module assumes =docker=, =docker-compose= and =docker-machine= binaries are
installed and accessible from your PATH.

Optionally, this module also uses the following programs:
- =docker-langserver= (for LSP users): ~$ npm install -g
  dockerfile-language-server-nodejs~

* TODO Usage
#+begin_quote
 🔨 /This module's usage documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote

** 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
[[github:politza/tablist][politza/tablist]]):
| Binding   | Description          |
|-----------+----------------------|
| [[kbd:][?]]       | List actions         |
| [[kbd:][l]]       | Configure listing    |
| [[kbd:][m]]       | Mark item            |
| [[kbd:][u]]       | Unmark item          |
| [[kbd:][t]]       | Toggle marks         |
| [[kbd:][U]]       | Unmark all           |
| [[kbd:][s]]       | Sort                 |
| [[kbd:][* r]]     | Mark items by regexp |
| [[kbd:][<]]       | Shrink column        |
| [[kbd:][>]]       | Enlarge column       |
| [[kbd:][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          |

* TODO Configuration
#+begin_quote
 🔨 /This module's configuration documentation is incomplete./ [[doom-contrib-module:][Complete it?]]
#+end_quote

** 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
  :bind ("C-c d" . docker)
  :custom (docker-image-run-arguments '("-i" "-t" "--rm")))
#+end_src

*** 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
[[doom-report:][Report an issue?]]

** 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 =$DOOMDIR/config.el= to overwrite
~tramp-wait-for-output~ with the patch applied:
#+begin_src emacs-lisp
(after! tramp
  (require 'docker-tramp-compat))
#+end_src

* Frequently asked questions
/This module has no FAQs yet./ [[doom-suggest-faq:][Ask one?]]

* TODO Appendix
#+begin_quote
 🔨 This module has no appendix yet. [[doom-contrib-module:][Write one?]]
#+end_quote