docker-launch¶

Create and launch docker containers on multiple hosts.

Features¶

This library provides:

SSH public key authentication checker and its set-up command
Launch multiple Docker containers on arbitrary host(s), via command line or Python script

Installation¶

pip install docker-launch

Usage¶

To check if SSH public key authentication to user@192.168.1.1 is enabled or not, run

>>> from docker_launch import check_connection
>>> check_connection("user@192.168.1.1")
True

or from command line,

$ docker-launch check user@192.168.1.1
OK

If the authentication hasn’t been set-up, you can configure it via

docker-launch check user@192.168.1.1 --setup

Once the authentication is set-up, let’s prepare configuration file path/to/config.toml

[ros_topics]
baseimg = "ros:humble-ros-core"
command = "env ROS_DOMAIN_ID=1 ros2 topic pub {a} std_msgs/msg/Float64 '{{data: 123.45}}'"
targets = [
    { a = "first", __machine__ = "localhost" },
    { a = "/second", __machine__ = "user@172.29.1.2" },
]

This will spawn

ros:humble-ros-core container on the host machine, executing command env ROS_DOMAIN_ID=1 ros2 topic pub first std_msgs/msg/Float64 '{data: 123.45}'
ros:humble-ros-core container on user@172.29.1.2, executing command env ROS_DOMAIN_ID=1 ros2 topic pub /second std_msgs/msg/Float64 '{data: 123.45}'

by running

>>> from docker_launch import launch_containers
>>> launch_containers("path/to/config.toml", remove=True)

docker-launch up path/to/config.toml --rm

For the details of the options, see docker run documentation and Docker SDK’s documentation.

Options of docker run command which docker-launch command and docker_launch.launch_containers() function doesn't support

--attach, -a
--cgroupns
--cidfile
--detach, -d (always True)
--detach-keys
--disable-content-trust
--env-file
--expose
--gpus
-h (use --hostname instead)
--interactive, -i
--ip
--ip6
--label-file
--link-local-ip
--log-driver
--log-opt
--mount
--net (only bridge, none, host, and container:<name|id> are supported)
--net-alias
--network (only bridge, none, host, and container:<name|id> are supported)
--network-alias
--no-healthcheck
--pull
--sig-proxy
--stop-timeout
--ulimit
-v (use --volume instead)

Options of Docker SDK's docker.containers.run function which docker-launch command doesn't support (docker_launch.launch_containers() function supports them)

auto_remove
device_requests
init_path
log_config
lxc_conf
mounts
nano_cpus
network
network_disabled
stdin_open
stdout
stderr
stream
ulimits
use_config_proxy
version

Configuration File Spec¶

The configuration is described in TOML format. Required fields are:

baseimg (string) - Name of the image from which the containers are created
command (string) - Command template to execute in each containers, with Python style placeholder (positional placeholder e.g. {0} isn’t supported)
targets (array of table) - List of parameter tables for each containers, and special parameter __machine__

The fields above must be grouped in a table.

[table-name]
baseimg = "docker:image-name"
command = "command template with {placeholder}"
targets = [
    { placeholder = "this", __machine__ = "user@172.29.1.2" },
    { placeholder = "that" },
]

A configuration file can have multiple tables

[table-1]
baseimg = "docker:image-name"
command = "command template with {placeholder}"
targets = [
    { placeholder = "this", __machine__ = "user@172.29.1.2" },
    { placeholder = "that" },
]

[table-2]
baseimg = "docker:other-image"
command = "other command {parameter} with curly braces {{escaped}}"
targets = [
    { parameter = 100, __machine__ = "user@172.29.1.2" },
    { parameter = 200 },
]

Optional field:

include (array of string) - Paths to additional configuration files

The instruction must be declared at top level (not inside tables).

include = ["path/to/other/config.toml", "/path/to/another/config.toml"]

[table-name]
baseimg = "docker:image-name"
command = "command template with {placeholder}"
targets = [
    { placeholder = "this", __machine__ = "user@172.29.1.2" },
    { placeholder = "that" },
]

This library is using Semantic Versioning.

docker_launch