This is a module for Viam Robotics to manage docker containers, on your robot, with the RDK. You can find this module in the Viam Registry
container0
)You can find the entire config in config.go.
This module can start containers in one of two ways (per-component), using docker run
or using docker compose ... up
Attribute | Required | Type | Description |
---|---|---|---|
run_options | N | RunOptions | Options for starting a container with the equivalent of docker run |
compose_options | N | ComposeOptions | Options for starting a container (or containers) with the equivalent of docker compose |
image_name | Y | string | The name of the image on Docker Hub or the full name of the image and registry if not using Docker Hub |
repo_digest | Y | string | The digest hash of the image on the repository |
run_once | N | bool | Only run the container once |
download_only | N | bool | Only download the container, don't attempt to start it |
credentials | N | Credentials | Credentials to use for pulling images from a private repository |
Attribute | Required | Type | Description |
---|---|---|---|
entry_point_args | N | []string | The command to pass as the entrypoint to the container |
options | N | []string | Any options to also pass to the container |
host_options | N | []string | Any options to also pass to the container |
Attribute | Required | Type | Description |
---|---|---|---|
compose_file | Y | []string | The contents of the docker compose file, each line of the file is a single entry in the array, whitespace is preserved |
_Note: The image tag in the compose_file
is required and must match the image_name
and repo_digest
provided in the attributes._
Attribute | Required | Type | Description |
---|---|---|---|
username | Y | string | The username to use |
password | Y | string | The password to use |
docker run
Given the following docker run
command examples, here is how they are translated to a component configuration for this module.
Command: docker run ubuntu echo hi
Attributes:
{
"image_name": "ubuntu",
"repo_digest": "sha256:04714a1bfbb2d8b5390b5cc0c055e48ebfabd4aa395821b860730ff3277ed74a",
"run_options": {
"entry_point_args": [
"echo",
"hi"
]
}
}
Command: docker run --rm ubuntu echo hi
Attributes:
{
"image_name": "ubuntu",
"repo_digest": "sha256:04714a1bfbb2d8b5390b5cc0c055e48ebfabd4aa395821b860730ff3277ed74a",
"run_options": {
"entry_point_args": [
"echo",
"hi"
],
"host_options": {
"AutoRemove": true
}
}
}
Command: docker run --rm --volume viam:/opt/ws/install --network host ubuntu echo hi
Attributes:
{
"image_name": "ubuntu",
"repo_digest": "sha256:04714a1bfbb2d8b5390b5cc0c055e48ebfabd4aa395821b860730ff3277ed74a",
"run_options": {
"entry_point_args": [
"echo",
"hi"
],
"host_options": {
"Binds": "viam:/opt/ws/install",
"NetworkMode": "host",
"AutoRemove": true
}
}
}
Command: docker run --rm --env ghcr.io/PATH/TO/PRIVATE/REPO:YOURTAGHERE sleep 15
Attributes:
{
"image_name": "ghcr.io/PATH/TO/PRIVATE/REPO:YOURTAGHERE",
"repo_digest": "sha256:DIGEST_HERE",
"run_options": {
"host_options": {
"AutoRemove": true
}
"entry_point_args": [
"sleep",
"15"
]
},
"credentials": {
"password": "PASSCODE HERE",
"username": "USERNAME HERE"
}
}
Command: DOCKER_API_VERSION="1.41" docker run ubuntu echo hi
Component Attributes:
{
"image_name": "ubuntu",
"repo_digest": "sha256:04714a1bfbb2d8b5390b5cc0c055e48ebfabd4aa395821b860730ff3277ed74a",
"run_options": {
"entry_point_args": [
"echo",
"hi"
]
}
}
Module Attributes:
"modules": [
{
"version": "0.0.5",
"type": "registry",
"name": "viam-soleng_viam-docker-manager",
"module_id": "viam-soleng:viam-docker-manager",
"env": {
"DOCKER_API_VERSION": "1.41"
}
}
]
docker compose
{
"image_name": "ubuntu",
"repo_digest": "sha256:04714a1bfbb2d8b5390b5cc0c055e48ebfabd4aa395821b860730ff3277ed74a",
"compose_options": {
"compose_file": [
"services:",
" app:",
" image:ubuntu@sha256:04714a1bfbb2d8b5390b5cc0c055e48ebfabd4aa395821b860730ff3277ed74a",
" command: echo hi"
" working_dir: /root"
]
}
}
image
tag in the compose file have to match the image_name
and repo_digest
provided in the config?
image
tags matches the image_name
and repo_digest
. Given the problem listed above, I discourage using compose files.