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)

or

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

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

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.