From b39188406db763ad0717bf5cfb7196e39a206912 Mon Sep 17 00:00:00 2001 From: Paulo Casaretto Date: Tue, 30 Apr 2019 17:34:40 -0300 Subject: [PATCH 1/3] Add a draft for docker module documentation --- modules/tools/docker/README.org | 143 ++++++++++++++++++++++++++++++++ 1 file changed, 143 insertions(+) create mode 100644 modules/tools/docker/README.org diff --git a/modules/tools/docker/README.org b/modules/tools/docker/README.org new file mode 100644 index 000000000..b7c7875f8 --- /dev/null +++ b/modules/tools/docker/README.org @@ -0,0 +1,143 @@ +#+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]] +- [[#features][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. + +* Features +An in-depth list of features, how to use them, and their dependencies. + +** 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 From 48b1276ee619607463bfc03f552573a7d6b64902 Mon Sep 17 00:00:00 2001 From: Paulo Casaretto Date: Sun, 5 May 2019 19:03:11 -0300 Subject: [PATCH 2/3] Add TODO tag to Features heading --- modules/tools/docker/README.org | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/modules/tools/docker/README.org b/modules/tools/docker/README.org index b7c7875f8..4ffc12537 100644 --- a/modules/tools/docker/README.org +++ b/modules/tools/docker/README.org @@ -8,7 +8,7 @@ - [[#module-flags][Module Flags]] - [[#plugins][Plugins]] - [[#prerequisites][Prerequisites]] -- [[#features][Features]] +- [[#todo-features][TODO: Features]] - [[#docker-control][Docker control]] - [[#supported-commands][Supported commands]] - [[#tramp][TRAMP]] @@ -40,9 +40,7 @@ This module provides no flags. This modules assumes `docker`, `docker-compose` and `docker-machine` binaries are installed and accessible from your PATH. -* Features -An in-depth list of features, how to use them, and their dependencies. - +* TODO: Features ** Docker control Use =M-x docker=, select a resource then then mark or unmark items using the following keybindings (for more From 37f799c4e509751feb2d0dd76d5f375d8c9b751c Mon Sep 17 00:00:00 2001 From: Paulo Casaretto Date: Sun, 5 May 2019 19:17:02 -0300 Subject: [PATCH 3/3] Make plugins a simple list --- modules/tools/docker/README.org | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/modules/tools/docker/README.org b/modules/tools/docker/README.org index 4ffc12537..98f541756 100644 --- a/modules/tools/docker/README.org +++ b/modules/tools/docker/README.org @@ -32,9 +32,9 @@ docker-tramp.el offers a TRAMP method for Docker containers. 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]] + + [[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