Home

Awesome

<img src="https://github.com/ika-rwth-aachen/docker-run/raw/main/assets/logo.png" height=130 align="right">

docker-rundocker run and docker exec with useful defaults

<p align="center"> <img src="https://img.shields.io/github/license/ika-rwth-aachen/docker-run"/> <a href="https://pypi.org/project/docker-run-cli/"><img src="https://img.shields.io/pypi/v/docker-run-cli?label=PyPI"/></a> <a href="https://pypi.org/project/docker-run-cli/"><img src="https://img.shields.io/pypi/dm/docker-run-cli?color=blue&label=PyPI%20downloads"/></a> </p>

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: opensource@ika.rwth-aachen.de

<p align="center"> <img src="https://github.com/ika-rwth-aachen/docker-run/raw/main/assets/teaser.png" width=550> </p>

While docker-run can be used with any Docker image, we recommend to also check out our other tools for Docker and ROS.

Quick Demo

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

Functionality

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.

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.

Installation

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's PATH. If running docker-run errors with docker-run: command not found, add the directory to your path. (More information)

echo "export PATH=\$HOME/.local/bin:\$PATH" >> ~/.bashrc
source ~/.bashrc

Usage

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

Plugins

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]
PluginDescription
docker-rosextra functionality for Docker images built by docker-ros