Deploy a module using Docker

In rare cases, you may need to package and deploy a module using Docker. Use cases for this include:

• Your module has complex system dependencies that cannot be easily installed on a machine.
• You use a large container image and some layers are already used by your machine which means layer caching can reduce the size of the download.
• You have specific security requirements that are difficult to meet with the default module deployment.

If you choose to deploy your module using Docker, we recommend creating a “first run” script or binary to run any necessary setup steps. Note this is not recommended for modules that do not use Docker, as it adds unnecessary complexity.

Use a first_run script or binary

1. Create a tarball that contains:

   • The module’s entrypoint script or binary, for example:

     #!/bin/bash
     exec docker run <YOUR_CONTAINER_IMAGE> <YOUR_CONTAINER_OPTIONS>
     

   • A meta.json

   • A first run script or binary that will be executed during the setup phase, for example:

     #!/usr/bin/env bash
     
     docker pull mongo:6
     
     cat << EOF
     -------------------------------------
     The setup script ran successfully!
     -------------------------------------
     EOF
     
     exit 0
     

   This example Makefile on GitHub builds a module binary and bundles it along with a meta.json and first run script.
   
   

2. Edit the meta.json to include a first_run field that points to the first run script or binary.

   {
     ...
     "first_run": "first_run.sh"
   }
   

3. Configure your module on your machine in the same way you would configure a regular module. The first run script will execute once when viam-server receives a new configuration. It will only execute once per module or per version of the module.
   
   

4. (Optional) After a first run script runs successfully, Viam adds a marker file in the module’s data directory. The marker file path format is of the form unpackedModDir + FirstRunSuccessSuffix. For example, .viam/packages/data/module/abcd1234-abcd-abcd-abcd-abcd12345678-viam-rtsp-0_1_0-linux-amd64/bin.first_run_succeeded.

   If you want to force a first run script to run again without changing the configured module or module version, you can do so by deleting this file.
   
   

5. (Optional) By default, a first run script will timeout after 1 hour. This can be adjusted by adding a first_run_timeout to the module’s configuration. For example, "first_run_timeout": "5m" will lower the script timeout to 5 minutes.