python container example modular resource

This repo contains an example of packaging a Python module into a Docker container and running it on a smart machine using Podman, a lightweight Docker alternative.

This example module implements the rdk:sensor API in the disk_sensor:linux model. You can modify the forked repo to implement a different model and use an available API to meet your module's requirements.

You can use this repo as a reference for:

• Shipping complex Python dependencies
• Other Docker bundling techniques

Tip

This example repo uses ghcr.io as a package registry using docker pull and docker push. An alternative is to use docker / podman save and load commands to bundle the container image with the module and restore it on the target machine.

Requirements

• Podman or Docker (Install on the Raspberry Pi/Debian based system), you can run:

  sudo apt-get install podman

• If you fork this repo and deploy to a machine, you'll need to replace all instances of the viam namespace with the namespace of your organization on Viam. You may also want to set up secrets for CI. Follow the fork instructions from the Python example repo for guidance

Include credentials

To host your module on ghcr.io as demonstrated in this repo, include your GitHub or Docker PAT (personal access token) securely. You can use one of the following methods:

• Run docker login on your machine to authenticate to ensure that all Docker commands run through Viam can access your container images
• Alternatively, you can include your PAT in the run.sh script in your Viam module's configuration as an environment variable

Important

To use a PAT for this process securely, configure the key with read-only permissions. Also ensure that it is not stored or uploaded to the container registry to safeguard against unauthorized access.

By hosting your module on ghcr.io, you:

• Equip your development environment with Docker layer caching for quicker Viam uploads
• Gain access to the lightweight docker pull and docker push commands necessary to upload your module to Viam

Configure your Python module container

Note

Before configuring your disk_sensor:linux component, you must create a machine.

Navigate to the Config tab of your machine's page in the Viam app. Click on the Components subtab and click Create component. Select the sensor type, then select the disk_sensor:linux model. Enter a name for your sensor and click Create.

Note

For more information, see Configure a Robot.

Attributes

There are no attributes available for configuration with this service.

Example configuration

Replace module_id and model with the values you choose for your module.

{
  "modules": [
    {
      "type": "registry",
      "version": "latest",
      "name": "disk",
      "module_id": "viam:python-container-example"
    }
  ],
  "components": [
    {
      "depends_on": [],
      "name": "my-sensor",
      "type": "sensor",
      "attributes": {},
      "model": "viam:disk_sensor:linux"
    }
  ]
}

Repository Contents

File/Directory	Description
module/	Python code for the Viam module.
Dockerfile	Container configuration. You can build the container locally using docker build -t whatever . on your laptop.
Pipfile and Pipfile.lock	Dependency information. These are used in Dockerfile to bundle dependencies.
.github/workflows	CI logic to upload the module upon the creation of a GitHub release.

Next Steps

• Once the disk_sensor has started collected data, you can view reported readings from the Data tab in the Viam app, under the Sensors subtab.
• For more information, refer to the Python example module's Learning resources.

Troubleshooting

• If you run into module startup errors after forking this repo, it may be because GitHub packages made your container private. There are three options for troubleshooting:
  • Follow the instructions to configure the visibility of your GitHub packages
  • Include your GHCR credentials in your in the your smart machine's JSON configuration as an environment variable
  • Log in to GHCR on your smart machine