{"id":13542490,"url":"https://github.com/gportay/dosh","last_synced_at":"2025-04-02T10:30:52.778Z","repository":{"id":76935721,"uuid":"100751305","full_name":"gportay/dosh","owner":"gportay","description":"Docker Shell CLI plugin","archived":false,"fork":false,"pushed_at":"2024-05-07T14:41:57.000Z","size":417,"stargazers_count":6,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"master","last_synced_at":"2024-05-07T15:34:55.969Z","etag":null,"topics":["cli","docker","docker-scripts","dosh","plugin","podman"],"latest_commit_sha":null,"homepage":"https://gportay.github.io/dosh","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gportay.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":"support/cqfd","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-08-18T21:26:14.000Z","updated_at":"2024-05-07T15:34:58.184Z","dependencies_parsed_at":"2023-11-16T20:54:29.751Z","dependency_job_id":"1fa29166-786c-4f59-a533-fe5655c82e29","html_url":"https://github.com/gportay/dosh","commit_stats":null,"previous_names":[],"tags_count":32,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gportay%2Fdosh","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gportay%2Fdosh/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gportay%2Fdosh/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gportay%2Fdosh/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gportay","download_url":"https://codeload.github.com/gportay/dosh/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246796814,"owners_count":20835448,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cli","docker","docker-scripts","dosh","plugin","podman"],"created_at":"2024-08-01T10:01:08.803Z","updated_at":"2025-04-02T10:30:52.766Z","avatar_url":"https://github.com/gportay.png","language":"Shell","funding_links":[],"categories":["Shell","docker"],"sub_categories":[],"readme":"# Docker Shell\n\n[![Packaging status](https://repology.org/badge/vertical-allrepos/dosh.svg)](https://repology.org/project/dosh/versions)\n\n## TL;DR;\n\n[dosh][dosh(1)] is a bash script providing a shell CLI to *docker-run(1)*.\n\nIt runs a user shell with cwd bind mounted to the container built using the\nDockerfile.\n\nOne think `dosh` does...\n\n\tdocker run --rm [--tty] [--interactive] \"--volume=$PWD:$PWD:rw\" \"--user=$USER\" \"--entry-point=$SHELL\" IMAGE [SHELL_ARGS]\n\n... with a few more magic!\n\n## NAME\n\n[dosh][dosh(1)] - run a user shell in a container with cwd bind mounted\n\n## DESCRIPTION\n\n[dosh(1)] is an _sh-compatible_ frontend for [docker] that runs commands in a\nnew container; using the current _user_, with _cwd_ bind mounted.\n\nCommands are read either from the standard input or from a file or from command\nline using one of the standard shell invocations (i.e. thanks to options `-c`,\n`-i`, `-s` or without arguments).\n\n## TUNING\n\n### DEFAULT SHELL INTERPRETER\n\n[dosh(1)] uses `/bin/sh` as default interpreter as it is the only reliable Shell\navailable. The default interpreter can be set by option `--shell SHELL`; but it\nneeds to be set to every call to *dosh*.\n\n\tdosh --shell /bin/bash\n\nInstead, the default interpreter can be set using the `DOSHELL` environment\nvariable. When this variable is exported, there is no need to override the Shell\ninterpreter through the command-line.\n\nAdding these two following lines to the Shell `~/.profile` to tell *dosh* to\nuse `/bin/bash` as Shell interpreter.\n\n\tDOSHELL=\"/bin/bash\"\n\texport DOSHELL\n\n### MANAGE DOSH AS A NON-ROOT USER\n\n[dosh(1)] relies on the setup of Docker. See its documentation to run Docker as\n[non-root-user].\n\nIt is not recommended to run [dosh(1)] using `sudo` in case the user does not\nhave permission to send the context to the Docker daemon. Instead, consider\nusing the option `--sudo` as it will only run the `docker` commands with the\nsuperuser privileges.\n\nOn Linux, if you are not a member of the `docker` group, please consider to run\n`dosh` as below:\n\n\tdosh --sudo\n\n### DOCKER EXTRA OPTIONS\n\nEvery [docker(1)][docker] command performed in [dosh(1)] can be customized by\npassing extra arguments thanks its corresponding **DOSH_DOCKER_xxx_EXTRA_OPTS**\nenvironment variable. **xxx** represents one of the *docker* commands used in\n*dosh* (*build*, *rmi*, *run*, *exec*, *attach*, *kill* and *rm*).\n\n_Note:_ Only `DOSH_DOCKER_RUN_EXTRA_OPTS` is relevant for interactive usage.\n\nAs an example, consider mapping extra personal *dot-files* to feel at home in\nthe container.\n\nAdding these two following lines to the Shell `~/.profile` automatically binds\nthe `~/.ssh` directory to the container.\n\n\tDOSH_DOCKER_RUN_EXTRA_OPTS=\"--volume $HOME/.ssh:$HOME/.ssh\"\n\texport DOSH_DOCKER_RUN_EXTRA_OPTS\n\n### INITIALIZATION FILES\n\n[dosh(1)] reads and executes commands from initialization files when it is\ninvoked.\n\nUnlike the standard shells, [dosh(1)] uses files from *personal* and *local*\nlocations instead of files from *system* and *personal* locations. The *system*\ninitialization file is replaced by a *local* file; and that *local* file is run\nafter the *personal* file.\n\nIn short, the *personal* file `~/.dosh_profile` is read first, and the *local*\nfile `./doshrc` is read then. The former file is hidden to avoid polutting the\n*personal* directory (as `.profile`, `.bash_profile`, `.bashrc`...) while the\nlater is not (like `Makefile`, `Dockerfile`...).\n\nThe Shell initialization files (`.profile`, `.bash_profile`, `.bashrc`...) are\nread by the host shell. The *dosh* specific [environment-variables] are string\nvariables, and they have to be exported to be part of the environment of the\n*dosh(1)* sub-process.\n\nBoth *dosh* initialization files aim to override the *dosh* specific variables.\nThe extra options [environment-variables] are converted to *bash(1)* arrays\nbefore the initialization files are read by *dosh(1)*. They have to remain\n*bash(1)* arrays.\n\n### SHELL PROFILE EXAMPLES\n\nHere are some examples of code to copy/paste in the `~/.profile`.\n\nThey significantly improve the *dosh* experience.\n\n#### REUSE SAME SHELL INTERPRETER\n\nThis asks *dosh* to use the same Shell interpreter as the one which is currently\nin use.\n\n\t# Not sh?\n\tif [ \"$SHELL\" != \"/bin/sh\" ]\n\tthen\n\t\texport DOSHELL=\"$SHELL\"\n\tfi\n\n_Important:_ Be aware that when the Shell interpreter is not installed in the\ncontainer, *dosh* ends with the following error:\n\n\tdocker: Error response from daemon: oci runtime error: container_linux.go:265: starting container process caused \"exec: \\\"/bin/zsh\\\": stat /bin/zsh: no such file or directory\".\n\n#### EXPORT ENVIRONMENT\n\nThese following lines export some useful environment variables to the container.\n\n\t# Export some environment variables\n\tfor env in TERM EDITOR\n\tdo\n\t\t[ -n \"$env\" ] || continue\n\t\tDOSH_DOCKER_RUN_EXTRA_OPTS+=\" --env $env\"\n\tdone\n\n#### MAP DOT-FILES\n\nThese following lines map some useful *dot-files* to the container.\n\n\t# Map some home dot-files\n\tfor vol in $HOME/.config $HOME/.local $HOME/.profile\n\tdo\n\t\t[ -e \"$vol\" ] || continue\n\t\tDOSH_DOCKER_RUN_EXTRA_OPTS+=\" --volume $vol:$vol\"\n\tdone\n\n\t# Map extra home dot-files\n\tfor vol in $HOME/.inputrc $HOME/.gnupg $HOME/.screenrc\n\tdo\n\t\t[ -e \"$vol\" ] || continue\n\t\tDOSH_DOCKER_RUN_EXTRA_OPTS+=\" --volume $vol:$vol\"\n\tdone\n\n*bash(1)* invocation files is a *must-have* to feel like home.\n\n\t# Map bash dot-files\n\tfor vol in $HOME/.bash{_profile,rc,login,logout}\n\tdo\n\t\t[ -e \"$vol\" ] || continue\n\t\tDOSH_DOCKER_RUN_EXTRA_OPTS+=\" --volume $vol:$vol\"\n\tdone\n\n*zsh(1)* too.\n\n\t# Map zsh dot-files\n\tzdotdir=\"${ZDOTDIR:-$HOME}\"\n\tfor vol in $zdotdir/.zshenv $zdotdir/.zprofile $zdotdir/.zshrc $HOME/.zlogin $HOME/.zlogout\n\tdo\n\t\t[ -e \"$vol\" ] || continue\n\t\tDOSH_DOCKER_RUN_EXTRA_OPTS+=\" --volume $vol:$vol\"\n\tdone\n\n#### SSH HANDLING\n\nFor a better experience with *SSH*, these following lines should be considered.\n\n\t# Map and export ssh things?\n\tif [ -d \"$HOME/.ssh\" ]\n\tthen\n\t\tDOSH_DOCKER_RUN_EXTRA_OPTS+=\" --volume $HOME/.ssh:$HOME/.ssh\"\n\tfi\n\tif [ -n \"$SSH_AUTH_SOCK\" ]\n\tthen\n\t\tDOSH_DOCKER_RUN_EXTRA_OPTS+=\" --env SSH_AUTH_SOCK\"\n\t\tDOSH_DOCKER_RUN_EXTRA_OPTS+=\" --volume $SSH_AUTH_SOCK:$SSH_AUTH_SOCK\"\n\tfi\n\n#### X\n\nTo enable *X* in docker, these following lines should be considered.\n\n\t# Map and export X things?\n\tif [ -n \"$DISPLAY\" ]\n\tthen\n\t\tfor env in DISPLAY XAUTHORITY XSOCK\n\t\tdo\n\t\t\t[ -n \"$env\" ] || continue\n\t\t\tDOSH_DOCKER_RUN_EXTRA_OPTS+=\" --env $env\"\n\t\tdone\n\t\tdotxauthority=\"${XAUTHORITY:-$HOME/.Xauthority}\"\n\t\tif [ -e \"$dotxauthority\" ]\n\t\tthen\n\t\t\tDOSH_DOCKER_RUN_EXTRA_OPTS+=\" --volume $dotxauthority:$HOME/.Xauthority\"\n\t\tfi\n\t\tunset dotxauthority\n\t\txsock=\"${XSOCK:-/tmp/.X11-unix}\"\n\t\tif [ -e \"$xsock\" ]\n\t\tthen\n\t\t\tDOSH_DOCKER_RUN_EXTRA_OPTS+=\" --volume $xsock:/tmp/.X11-unix:ro\"\n\t\tfi\n\t\tunset xsock\n\tfi\n\n_Note_: To enable *X* through *SSH*, please have a look to the excellent post\nof Jean-Tiare Le Bigot on its blog [yadutaf].\n\n#### MAKE THE PROMPT SLIGHTLY DIFFERENT\n\nColorize the prompt from the container in a different way to distinguish *dosh*\nsessions.\n\n\t# In dosh?\n\tif [ -z \"$DOSHLVL\" ]\n\tthen\n\t\treturn\n\tfi\n\n\t# Colorize prompt color differently\n\tPS1=\"${PS1//32/33}\"\n\tPROMPT=\"${PROMPT//blue/green}\"\n\n_Note_: Put these lines to the end of the file.\n\nLines after the if statement are applied in the container.\n\n## USE PODMAN\n\n[podman] is a daemonless alternative to [docker] providing the same command\nline interface, and it can replace [docker] without any troubles.\n\nAdding these two following lines to the Shell `~/.profile` to tell *dosh* to\nuse `/usr/bin/podman` to run `docker` commands:\n\n\tDOSH_DOCKER=\"/usr/bin/podman\"\n\texport DOSH_DOCKER\n\nAlso, disable the context using option `--no-auto-context`.\n\nAdditionally, for Rootless containers, consider adding the two following extra\nrun options to map host UID and GIDs to the container and run it inside a user\nnamespace.\n\nAdd either the following line to the Shell `~/.profile`:\n\n\tDOSH_DOCKER_RUN_EXTRA_OPTS=\"--userns keep-id --group-add keep-groups\"\n\nOr the following line to the dosh `~/.dosh_profile`:\n\n\tDOSH_DOCKER_RUN_EXTRA_OPTS+=(--userns keep-id --group-add keep-groups`)\n\nAlternatively, use the convenient wrapper script [posh](support/posh) to run\n[dosh] using [podman] underneath without touching the Shell and *dosh* files.\n\n### USE AS INTERPRETER FOR SHELL SCRIPT\n\n[dosh(1)] is usable as an interpreter for shell script.\n\nAccording to [execve(2)]:\n\n\u003e Interpreter scripts\n\u003e\n\u003e An interpreter script is a text file that has execute permission enabled and\n\u003e whose first line is of the form:\n\u003e\n\u003e\t#!interpreter [optional-arg]\n\u003e\n\u003e The interpreter must be a valid pathname for an executable file.\n\u003e\n\u003e If the pathname argument of execve() specifies an interpreter script, then\n\u003e interpreter will be invoked with the following arguments:\n\u003e\n\u003e\tinterpreter [optional-arg] pathname arg...\n\u003e\n\u003e where pathname is the pathname of the file specified as the first argument of\n\u003e execve(), and arg... is the series of words pointed to by the argv argument\n\u003e of execve(), starting at argv[1]. Note that there is no way to get the\n\u003e argv[0] that was passed to the execve() call.\n\u003e\n\u003e For portable use, optional-arg should either be absent, or be specified as a\n\u003e single word (i.e., it should not contain white space); see NOTES below.\n\u003e\n\u003e Since Linux 2.6.28, the kernel permits the interpreter of a script to itself\n\u003e be a script. This permission is recursive, up to a limit of four recursions,\n\u003e so that the interpreter may be a script which is interpreted by a script, and\n\u003e so on.\n\u003e\n\u003e Notes\n\u003e\n\u003e Linux ignores the set-user-ID and set-group-ID bits on scripts. \n\u003e\n\u003e A maximum line length of 127 characters is allowed for the first line in a #!\n\u003e executable shell script. \n\u003e\n\u003e The semantics of the optional-arg argument of an interpreter script vary\n\u003e across implementations. On Linux, the entire string following the interpreter\n\u003e name is passed as a single argument to the interpreter, and this string can\n\u003e include white space. However, behavior differs on some other systems. Some\n\u003e systems use the first white space to terminate optional-arg. On some systems,\n\u003e an interpreter script can have multiple arguments, and white spaces in\n\u003e optional-arg are used to delimit the arguments. \n\nA typical shebang to run a shell script via *dosh* is `#!/usr/bin/dosh`.\n\nHowever, the abosulte path to *dosh* is unpredictable since it may be installed\nin `/bin`, `/usr/bin`, `/usr/local/bin`, or in the user home `~/.local/bin`, or\neven in `/opt`.\n\nTherefore, the most appropriate shebang to run *dosh* is `#!/usr/bin/env dosh`.\n\nAdditionally, consider using the [env(1)] split option `-S` (since [coreutils\n8.30]) if using *dosh* arguments such as `#!/usr/bin/env -S dosh --home`.\n\n_Important_: *dosh* warns and splits the list of arguments itself if using the\nabsolute path (i.e. `#!/usr/bin/dosh --docker support/Dockerfile`) instead of\nusing *env* and its split option (i.e. `#!/usr/bin/env -S dosh --dockerfile\nsupport/Dockerfile`). This feature is unportable; it is deprecated in version 7\nand it is going for removal in a next release. Consider moving the shebang to\n[env(1)] and its `-S` since the half of [2018][coreutils 8.30].\n\n## DOCUMENTATION\n\nBuild the documentation using *make(1)*\n\n\t$ make doc\n\tasciidoctor -b manpage -o dosh.1 dosh.1.adoc\n\tgzip -c dosh.1 \u003edosh.1.gz\n\trm dosh.1\n\n## INSTALL\n\nRun the following command to install *dosh(1)*\n\nTo your home directory\n\n\t$ make user-install\n\nOr, to your system\n\n\t$ sudo make install\n\nTraditional variables *DESTDIR* and *PREFIX* can be overridden\n\n\t$ sudo make install PREFIX=/opt/dosh\n\nOr\n\n\t$ make install DESTDIR=$PWD/pkg PREFIX=/usr\n\n## LINKS\n\nCheck for [man-pages][dosh(1)] and its [examples].\n\nAlso, here is an extra example that builds the documentation\n\n\t$ echo FROM ubuntu \u003eDockerfile\n\t$ echo RUN apt-get update \u0026\u0026 apt-get install -y asciidoctor \u003e\u003eDockerfile\n\n\t$ cat Dockerfile\n\tFROM ubuntu\n\tRUN apt-get update \u0026\u0026 apt-get install -y asciidoctor\n\n\t$ dosh -c asciidoctor -b manpage -o - dosh.1.adoc | gzip -c - \u003edosh.1.gz\n\tsha256:ced062433e33\n\n\t$ man ./dosh.1.gz\n\nEnjoy!\n\n## PATCHES\n\nSumbit patches at *https://github.com/gportay/dosh/pulls*\n\n## BUGS\n\nReport bugs at *https://github.com/gportay/dosh/issues*\n\n## AUTHOR\n\nWritten by Gaël PORTAY *gael.portay@gmail.com*\n\n## COPYRIGHT\n\nCopyright 2017-2020,2023-2025 Gaël PORTAY\n\nThis program is free software: you can redistribute it and/or modify it under\nthe terms of the GNU Lesser General Public License as published by the Free\nSoftware Foundation, either version 2.1 of the License, or (at your option) any\nlater version.\n\n[coreutils 8.30]: https://github.com/coreutils/coreutils/commit/668306ed86c8c79b0af0db8b9c882654ebb66db2\n[docker]: https://github.com/docker/docker\n[dosh(1)]: dosh.1.adoc\n[dosh]: dosh\n[env(1)]: https://linux.die.net/man/1/env\n[environment-variables]: https://github.com/gportay/dosh/blob/master/dosh.1.adoc#environment-variables\n[examples]: dosh.1.adoc#examples\n[execve(2)]: https://linux.die.net/man/2/execve\n[non-root-user]: https://docs.docker.com/install/linux/linux-postinstall/#manage-docker-as-a-non-root-user\n[podman]: https://github.com/containers/podman\n[posh]: support/posh\n[yadutaf]: https://blog.yadutaf.fr/2017/09/10/running-a-graphical-app-in-a-docker-container-on-a-remote-server/\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgportay%2Fdosh","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgportay%2Fdosh","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgportay%2Fdosh/lists"}