Update and manage modules you created

After you create and deploy a module, you may need to update or delete it.

For information on pinning module deployments to versions, see Module versioning.

Update an existing module

You can update an existing module in the Viam Registry in one of two ways:

• Upload new versions of your module manually using the Viam CLI.
• Automatically upload new versions of your module on release as part of a continuous integration (CI) workflow, using a GitHub action.

Updating your module manually is appropriate for smaller projects, especially those with only one contributor. Updating your module automatically using CI is better suited for larger, ongoing projects, especially those with multiple contributors.

Update an existing module using the Viam CLI

To update an existing module in the Viam Registry manually, you can use the Viam CLI.

1. Edit your custom module code with the changes you’d like to make.

2. Update your custom module’s meta.json file with any needed changes. For example, if you have altered your model’s description, or adjusted the endpoint name, you’ll need to update meta.json with these changes.

3. For modules written in Python, you should package your module files as an archive first, before uploading. Other languages can proceed to the next step to upload their module directly. To package a module written in Python, run the following command from the same directory as your meta.json file:

   • Packaged executable
   • Using venv

   tar -czf module.tar.gz <PATH-TO-EXECUTABLE>
   

   where <PATH-TO-EXECUTABLE> is the packaged executable.

   tar -czf module.tar.gz run.sh requirements.txt src
   

   Where run.sh is your executable file, requirements.txt is your pip dependency list file, and src is the directory that contains the source code of your module.

   Supply the path to the resulting archive file in the next step.

4. Run viam module upload to upload your custom module to the Viam Registry:

   viam module upload --version <version> --platform <platform> <module-path>
   

   For example, the following command uploads a module compressed as an archive named my-module.tar.gz to the Viam Registry, and increments the version of the module to version 1.0.1:

   viam module upload --version 1.0.1 --platform darwin/arm64 my-module.tar.gz
   

   When you upload a module, the command performs basic validation of your module to check for common errors.

For more information, see the viam module command.

Update an existing module using a GitHub action

To update an existing module in the Viam Registry using continuous integration (CI), you can use one of two GitHub actions. You can only use these GitHub actions if you have already created the module by running viam module create and viam module update. For most use cases, we recommend the build-action GitHub action which provides a simple cross-platform build setup for multiple platforms: x86, ARM Linux, and MacOS. However, if you already have your own CI with access to arm runners or only intend to build on x86 or mac, you may also use the upload-module GitHub action instead which allows you to define the exact build steps.

1. Edit your custom module with the changes you’d like to make.

2. Navigate to the Actions tab of the GitHub repository you are using for your module code. If you have already created GitHub actions for this repository, click the New workflow button to create a new one. If you have not yet created any GitHub actions, click the Set up a workflow yourself link. See the GitHub actions documentation for more information.

3. Paste one of the following action templates into the edit window, depending on whether you are using the build-action or upload-module action:

# see https://github.com/viamrobotics/build-action for help
on:
  push:
    tags:
      - "[0-9]+.[0-9]+.[0-9]+" # the build-action will trigger on tags with the format 1.0.0

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: viamrobotics/build-action@v1
        with:
          # note: you can replace this line with 'version: ""' if
          # you want to test the build process without deploying
          version: ${{ github.ref_name }}
          ref: ${{ github.sha }}
          key-id: ${{ secrets.viam_key_id }}
          key-value: ${{ secrets.viam_key_value }}
          token: ${{ github.token }} # only required for private git repos

{
  "module_id": "example-module",
  ...
  "build": {
    "setup": "./setup.sh", // optional - command to install your build dependencies
    "build": "./build.sh", // command that will build your module
    "path" : "dist/archive.tar.gz", // optional - path to your built module
    "arch" : ["linux/amd64", "linux/arm64"] // architecture(s) to build for
  }
}

#!/bin/bash
set -e
UNAME=$(uname -s)
if [ "$UNAME" = "Linux" ]
then
echo "Installing venv on Linux"
sudo apt-get install -y python3-venv
fi
if [ "$UNAME" = "Darwin" ]
then
echo "Installing venv on Darwin"
brew install python3-venv
fi
python3 -m venv .venv
. .venv/bin/activate
pip3 install -r requirements.txt

#!/bin/bash
pip3 install -r requirements.txt
python3 -m PyInstaller --onefile --hidden-import="googleapiclient" src/main.py
tar -czvf dist/archive.tar.gz <PATH-TO-EXECUTABLE>

#!/bin/bash
set -e
UNAME=$(uname -s)
if [ "$UNAME" = "Linux" ]
then
echo "Installing venv on Linux"
sudo apt-get install -y python3-venv
fi
if [ "$UNAME" = "Darwin" ]
then
echo "Installing venv on Darwin"
brew install python3-venv
fi
python3 -m venv .venv
. .venv/bin/activate
pip3 install -r requirements.txt
python3 -m PyInstaller –onefile –hidden-import="googleapiclient" src/main.py
tar -czvf dist/archive.tar.gz <PATH-TO-EXECUTABLE>

viam module build local

on:
  push:
  release:
    types: [released]

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: build
        run: echo "your build command goes here" && false # <-- replace this with the command that builds your module's tar.gz
      - uses: viamrobotics/upload-module@v1
        # if: github.event_name == 'release' # <-- once the action is working, uncomment this so you only upload on release
        with:
          module-path: module.tar.gz
          platform: linux/amd64 # <-- replace with your target architecture, or your module will not deploy
          version: ${{ github.event_name == 'release' && github.ref_name || format('0.0.0-{0}.{1}', github.ref_name, github.run_number) }} # <-- see 'Versioning' section below for explanation
          key-id: ${{ secrets.viam_key_id }}
          key-value: ${{ secrets.viam_key_value }}

4. Create an organization API key with the owner role, which the GitHub action will use to authenticate to the Viam platform, using one of the following methods:

   • Use the Viam CLI to create an organization API key, which includes the owner role by default:

     viam organizations api-key create --org-id <org-id> --name <key-name>
     

   • Use the organizations page on the Viam app to generate a new organization API key. Make sure your organization API key is set to Role: Owner, or the GitHub action will not be able to successfully authenticate during runs. If you are using an existing organization API key which is not set to Role: Owner, you can change an API key’s permissions from the Viam app on the organizations page by clicking the Show details link next to your API key. The operator role cannot be used to authenticate GitHub action runs. For more information see Manage organizations.

   Both methods return a key id and a key value which together comprise your organization API key.

5. Then, configure your GitHub repository to use your organization API key to authenticate during GitHub action runs, following the steps below:

   1. In the GitHub repository for your project, select Settings, then Secrets and variables, then Actions.

   2. Click the green New repository secret button, enter viam_key_id as the NAME, paste the value for key id from above into the Secret text field, then click Add secret.

   3. Then, click the green New repository secret button, enter viam_key_value as the NAME, paste the value for key value from above into the Secret text field, then click Add secret.

   For more information on GitHub secrets, see the GitHub documentation for creating secrets for a repository.

6. Push a tag to your repo or create a new release. The specific step to take to release your software depends on your CI workflow, your GitHub configuration, and the run step you defined earlier. Once complete, your module will upload to the Viam Registry with the appropriate version automatically.

For more details, see the upload-module GitHub Action documentation, or take a look through one of the following example repositories that show how to package and deploy modules using the Viam SDKs:

• Python with virtualenv
• Python with docker
• Golang
• C++

Change a module from public to private

You can change the visibility of a module from public to private if:

• you are an owner in the organization that owns the module, AND
• no machines outside of the organization that owns the module have the module configured (no other orgs are using it).

To change the visibility, navigate to its page in the REGISTRY section of the Viam app, hover to the right of the visibility indicator near the right side of the page until an Edit button appears, and click it to make changes.

You can also edit the visibility by editing the meta.json file and then running the following CLI command:

viam module update

Delete a module

You can delete a module if:

• you are an owner in the organization that owns the module, AND
• no machines have the module configured.

To delete a module, navigate to its page in the REGISTRY section of the Viam app, click the … menu in the upper-right corner of the page, and click Delete.

Delete just one version of a module

Deleting a version of a module requires the same org owner permissions as deleting the entire module, and similarly, you cannot delete a version if any machines are using it. To delete just one version of a module:

1. Navigate to its page in the REGISTRY section of the Viam app
2. Click Show previous versions under the Latest version heading.
3. Click the trash can icon next to the version you’d like to delete.

Versions are immutable, meaning that you cannot upload a new file with the same version number as the deleted one. To upload another version, you must increment the version number to a later version number.

Next steps

Pin a version

Configure version update management for a registry module on your machine.