docker-run is a CLI tool for simplified interaction with Docker images. Use it to easily start and attach to Docker containers with useful predefined arguments.
Important
This repository is open-sourced and maintained by the Institute for Automotive Engineering (ika) at RWTH Aachen University.
DevOps, Containerization and Orchestration of Software-Defined Vehicles are some of many research topics within our Vehicle Intelligence & Automated Driving domain.
If you would like to learn more about how we can support your advanced driver assistance and automated driving efforts, feel free to reach out to us!
📧 [email protected]
While docker-run can be used with any Docker image, we recommend to also check out our other tools for Docker and ROS.
- docker-ros automatically builds minimal container images of ROS applications
- docker-ros-ml-images provides machine learning-enabled ROS Docker images
The following quickly launches the GUI application xeyes
to demonstrate how docker-run
takes care of X11 forwarding from container to host. The --verbose
flag prints the underlying docker run
command that is run under the hood.
docker-run --verbose 607qwq/xeyes
docker-run
is designed to be used the same way as the official docker run
and docker exec
commands.
In general, you can pass the same arguments to docker-run
as you would pass to docker run
, e.g.
docker-run --volume $(pwd):/volume ubuntu ls /volume
In addition to the arguments you are passing, docker-run
however also enables the following features by default. Most of these default features can be disabled, see Usage.
- container removal after exit (
--rm
) - interactive tty (
--interactive --tty
) - current directory name as container name (
--name
) - relative bind mounts (
--volume [./RELATIVE_PATH>]:[TARGET_PATH]
) - GPU support (
--gpus all
/--runtime nvidia
) - X11 GUI forwarding
If a container with matching name is already running, docker-run
will execute a command in that container via docker exec
instead. This lets you quickly attach to a running container without passing any command, e.g.
docker-run --name my-running-container
Unlike with docker run
, you can also set the Docker image via the --image
arguments, see Usage. This may be required for more complex use cases.
pip install docker-run-cli
# (optional) shell auto-completion
source $(activate-python-docker-run-shell-completion 2> /dev/null)
Warning
Outside of a virtual environment, pip may default to a user-site installation of executables to~/.local/bin
, which may not be present in your shell'sPATH
. If runningdocker-run
errors withdocker-run: command not found
, add the directory to your path. (More information)echo "export PATH=\$HOME/.local/bin:\$PATH" >> ~/.bashrc source ~/.bashrc
usage: docker-run [--help] [--image IMAGE] [--mwd] [--name NAME] [--no-gpu]
[--no-it] [--no-loc] [--no-name] [--no-rm] [--no-tz]
[--no-x11] [--verbose] [--version]
Executes `docker run` with the following features enabled by default, each of
which can be disabled individually: container removal after exit, interactive
tty, current directory name as container name, GPU support, X11 GUI
forwarding. Passes any additional arguments to `docker run`. Executes `docker
exec` instead if a container with the specified name (`--name`) is already
running.
optional arguments:
--help show this help message and exit
--image IMAGE image name (may also be specified without --image as last
argument before command)
--mwd mount current directory at same path
--name NAME container name; generates `docker exec` command if already
running
--no-gpu disable automatic GPU support
--no-it disable automatic interactive tty
--no-loc disable automatic locale
--no-name disable automatic container name (current directory)
--no-rm disable automatic container removal
--no-tz disable automatic timezone
--no-x11 disable automatic X11 GUI forwarding
--verbose print generated command
--version show program's version number and exit
docker-run
can be extended through plugins. Plugins are installed as optional dependencies.
# install specific plugin <PLUGIN_NAME>
pip install docker-run-cli[<PLUGIN_NAME>]
# install all plugins
pip install docker-run-cli[plugins]
Plugin | Description |
---|---|
docker-ros |
extra functionality for Docker images built by docker-ros |