viam-docker-manager

viam-docker-manager

Description

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

Usage

1. Configure a new Component in your robot using app.viam.com
2. Search for "docker" and click the "sensor/manage:docker" from "viam-soleng"
3. Click "Add module"
4. Name the component (ex: container0)
5. Click "Create"
6. Create the relevant attributes (see config)

Config

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

Root Config

RunOptions

ComposeOptions

Note: The image tag in the compose_file is required and must match the image_name and repo_digest provided in the attributes.

Credentials

Usage

docker run

Given the following docker run command examples, here is how they are translated to a component configuration for this module.

Basic Example

Command: docker run ubuntu echo hi
Attributes:

{
    "image_name": "ubuntu",
    "repo_digest": "sha256:04714a1bfbb2d8b5390b5cc0c055e48ebfabd4aa395821b860730ff3277ed74a",
    "run_options": {
        "entry_point_args": [
            "echo",
            "hi"
        ]
    }
}

Basic Examples with Options

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
      }
    }
}

Basic Example with Options and Credentials

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"
  }
}

Basic Example of Module Env Variable Setup

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

Sample Config

{
    "image_name": "ubuntu",
    "repo_digest": "sha256:04714a1bfbb2d8b5390b5cc0c055e48ebfabd4aa395821b860730ff3277ed74a",
    "compose_options": {
        "compose_file": [
            "services:",
            "    app:",
            "      image:ubuntu@sha256:04714a1bfbb2d8b5390b5cc0c055e48ebfabd4aa395821b860730ff3277ed74a",
            "      command: echo hi"
            "      working_dir: /root"
        ]
    }
}

FAQ

• Why does the image tag in the compose file have to match the image_name and repo_digest provided in the config?
  • If they don't, starting the compose file may fail, or cause an unexpected delay in robot startup while the required images are downloaded.
• Does this mean I can't use the compose option to start multiple containers?
  • No, in theory it should work as long as one of the image tags matches the image_name and repo_digest. Given the problem listed above, I discourage using compose files.