diff --git a/modules/tools/docker/README.org b/modules/tools/docker/README.org index 98f541756..b3153322c 100644 --- a/modules/tools/docker/README.org +++ b/modules/tools/docker/README.org @@ -1,6 +1,6 @@ #+TITLE: tools/docker #+DATE: April 30, 2019 -#+SINCE: {replace with next tagged release version} +#+SINCE: v2.0.9 #+STARTUP: inlineimages * Table of Contents :TOC_3:noexport: @@ -8,25 +8,25 @@ - [[#module-flags][Module Flags]] - [[#plugins][Plugins]] - [[#prerequisites][Prerequisites]] -- [[#todo-features][TODO: Features]] +- [[#features][Features]] - [[#docker-control][Docker control]] - [[#supported-commands][Supported commands]] - [[#tramp][TRAMP]] - [[#configuration][Configuration]] - [[#popups][Popups]] - - [[#dockerfile-mode][dockerfile-mode]] + - [[#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. -This package 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. -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. +=docker-tramp.el= offers a [[https://www.gnu.org/software/tramp/][TRAMP]] method for Docker containers. ** Module Flags This module provides no flags. @@ -37,14 +37,14 @@ This module provides no flags. + [[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. +This module assumes =docker=, =docker-compose= and =docker-machine= binaries +are installed and accessible from your PATH. -* TODO: Features +* 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): +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 | |-----------+----------------------| @@ -61,41 +61,40 @@ marking possibilities, check out https://github.com/politza/tablist): | =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 +- =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. + 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. -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 +#+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 [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`: +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: +or inside a =use-package= declaration: #+BEGIN_SRC emacs-lisp -(use-package docker +(use-package! docker :ensure t :bind ("C-c d" . docker) :custom (docker-image-run-arguments '("-i" "-t" "--rm"))) @@ -103,39 +102,35 @@ or inside a use-package declaration: You can also customize these using =M-x customize-variable=. -### Others +*** 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")= | -| 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. -** 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 +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. -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 [[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: -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 +#+BEGIN_SRC emacs-lisp +(require 'docker-tramp-compat) +#+END_SRC