{"id":24324575,"url":"https://github.com/abe-winter/python-container-module","last_synced_at":"2025-06-11T17:03:32.935Z","repository":{"id":190298383,"uuid":"682103995","full_name":"abe-winter/python-container-module","owner":"abe-winter","description":"Example repo for bundling a Viam module using docker / podman containers","archived":false,"fork":false,"pushed_at":"2024-04-11T17:29:12.000Z","size":55,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-11T04:23:47.232Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/abe-winter.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-08-23T12:58:02.000Z","updated_at":"2024-08-26T19:37:43.000Z","dependencies_parsed_at":"2025-01-17T19:48:34.279Z","dependency_job_id":"b1d44e81-ef80-47c6-9290-8c14e5939575","html_url":"https://github.com/abe-winter/python-container-module","commit_stats":null,"previous_names":["viamrobotics/python-container-module","abe-winter/python-container-module"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/abe-winter/python-container-module","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abe-winter%2Fpython-container-module","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abe-winter%2Fpython-container-module/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abe-winter%2Fpython-container-module/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abe-winter%2Fpython-container-module/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/abe-winter","download_url":"https://codeload.github.com/abe-winter/python-container-module/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/abe-winter%2Fpython-container-module/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259301677,"owners_count":22836976,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-01-17T19:40:54.305Z","updated_at":"2025-06-11T17:03:32.915Z","avatar_url":"https://github.com/abe-winter.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# `python container` example modular resource\n\nThis 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. \n\nThis 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.\n\n You can use this repo as a reference for: \n- Shipping complex Python dependencies\n- Other Docker bundling techniques\n\n\u003e [!TIP]\n\u003e This example repo uses `ghcr.io` as a package registry using `docker pull` and `docker push`.\n\u003e 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.\n\n## Requirements\n\n- Podman or Docker (Install on the Raspberry Pi/Debian based system), you can run:\n\n    ```sh\n    sudo apt-get install podman\n    ```\n    \n- 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\n\n\n### Include credentials\n\nTo 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:\n\n- Run `docker login` on your machine to authenticate to ensure that all Docker commands run through Viam can access your container images\n- Alternatively, you can include your PAT in the `run.sh` script in your Viam module's configuration as an environment variable\n\n\u003e [!IMPORTANT]\n\u003e To use a PAT for this process securely, configure the key with read-only permissions.\n\u003e Also ensure that it is not stored or uploaded to the container registry to safeguard against unauthorized access.\n\nBy hosting your module on `ghcr.io`, you:\n- 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\n- Gain access to the lightweight `docker pull` and `docker push`  commands necessary to upload your module to Viam\n\n## Configure your Python module container\n\n\u003e [!NOTE]\n\u003e Before configuring your `disk_sensor:linux` component, you must [create a machine](https://docs.viam.com/fleet/machines/#add-a-new-machine).\n\nNavigate 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**.\n\n\u003e [!NOTE]\n\u003e For more information, see [Configure a Robot](https://docs.viam.com/manage/configuration/).\n\n### Attributes\n\nThere are no attributes available for configuration with this service.\n\n### Example configuration\n\nReplace `module_id` and `model` with the values you choose for your module.\n\n```json\n{\n  \"modules\": [\n    {\n      \"type\": \"registry\",\n      \"version\": \"latest\",\n      \"name\": \"disk\",\n      \"module_id\": \"viam:python-container-example\"\n    }\n  ],\n  \"components\": [\n    {\n      \"depends_on\": [],\n      \"name\": \"my-sensor\",\n      \"type\": \"sensor\",\n      \"attributes\": {},\n      \"model\": \"viam:disk_sensor:linux\"\n    }\n  ]\n}\n```\n\n## Repository Contents\n\n| File/Directory  | Description |\n| ------------- | ------------- |\n| `module/`     | Python code for the Viam module. |\n| `Dockerfile`  | Container configuration. You can build the container locally using `docker build -t whatever .` on your laptop. |\n| `Pipfile` and `Pipfile.lock`   | Dependency information. These are used in Dockerfile to bundle dependencies. |\n| `.github/workflows` | CI logic to upload the module upon the creation of a GitHub release. |\n\n## Next Steps \n\n- 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.\n- 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).\n\n## Troubleshooting\n\n- 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:\n    - 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)\n    - 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)\n    - [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\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fabe-winter%2Fpython-container-module","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fabe-winter%2Fpython-container-module","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fabe-winter%2Fpython-container-module/lists"}