https://github.com/abe-winter/python-container-module
Example repo for bundling a Viam module using docker / podman containers
https://github.com/abe-winter/python-container-module
Last synced: 6 months ago
JSON representation
Example repo for bundling a Viam module using docker / podman containers
- Host: GitHub
- URL: https://github.com/abe-winter/python-container-module
- Owner: abe-winter
- License: apache-2.0
- Created: 2023-08-23T12:58:02.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-04-11T17:29:12.000Z (over 1 year ago)
- Last Synced: 2025-03-11T04:23:47.232Z (10 months ago)
- Language: Python
- Size: 53.7 KB
- Stars: 0
- Watchers: 2
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# `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](https://podman.io/), 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:
```sh
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](https://github.com/viamrobotics/upload-module#setting-up-auth). Follow the [fork instructions](https://github.com/viam-labs/python-example-module#forking-this-repo) from the Python example repo for guidance
### Include credentials
To host your module on `ghcr.io` as demonstrated in this repo, include your [GitHub](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) or [Docker](https://docs.docker.com/security/for-developers/access-tokens/) 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](https://docs.semaphoreci.com/ci-cd-environment/docker-layer-caching/#:~:text=Docker%20uses%20a%20layer%20cache,explained%20in%20more%20detail%20next.) 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](https://docs.viam.com/fleet/machines/#add-a-new-machine).
Navigate to the **Config** tab of your machine's page in [the Viam app](https://app.viam.com/). 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](https://docs.viam.com/manage/configuration/).
### 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.
```json
{
"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](https://app.viam.com/data/view?view=sensors) in the Viam app, under the **Sensors** subtab.
- For more information, refer to the Python example module's [Learning resources](https://github.com/viam-labs/python-example-module?tab=readme-ov-file#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](https://docs.github.com/en/packages/learn-github-packages/configuring-a-packages-access-control-and-visibility#configuring-visibility-of-packages-for-your-personal-account)
- Include your [GHCR credentials](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry#authenticating-to-the-container-registry) in your in the your smart machine's [JSON configuration as an environment variable](https://docs.viam.com/registry/configure/#use-environment-variables-with-a-registry-module)
- [Log in to GHCR](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-container-registry#authenticating-with-a-personal-access-token-classic) on your smart machine