DOCS-2930: Add first_run flow for Docker modules

docs/operate/reference/advanced-modules/_index.md

@@ -11,7 +11,7 @@ tags:
     "components",
     "services",
   ]
-description: "Some usage may require you to define new APIs or deploy custom components using a server on a remote part"
+description: "Some usage may require you to define new APIs or deploy custom components in non-standard ways."
 aliases:
   - /program/extend/
   - /modular-resources/advanced/
@@ -46,6 +46,65 @@ Running {{< glossary_tooltip term_id="modular-resource" text="modular resources"
 
 However, if you are unable to use modular resources because you need to host `viam-server` on a non-Linux system or have an issue with compilation, you may need to [implement a custom component and register it on a server configured as a remote](/operate/reference/advanced-modules/custom-components-remotes/) on your machine.
 
+## Package and deploy 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, it adds unnecessary complexity.
+
+{{% expand "Click for first run script instructions" %}}
+
+1. Create a tarball that contains:
+
+   - The module's entrypoint script or binary
+   - A <file>meta.json</file>
+   - A first run script or binary that will be executed during the setup phase, for example:
+
+     ```sh {id="terminal-prompt" class="command-line" data-prompt="$"}
+     #!/usr/bin/env bash
+
+     docker pull mongo:6
+
+     cat << EOF
+     -------------------------------------
+     The setup script ran successfully!
+     -------------------------------------
+     EOF
+
+     exit 0
+     ```
+
+   [This example Makefile on GitHub](https://github.com/viam-labs/wifi-sensor/blob/7823b6ad3edcbbbf20b06c34b3181453f5f3f078/Makefile) builds a module binary and bundles it along with a <file>meta.json</file> and first run script.<br><br>
+
+1. Edit the <file>meta.json</file> to include a `first_run` field that points to the first run script or binary.
+
+   ```json
+   {
+     ...
+     "first_run": "first_run.sh"
+   }
+   ```
+
+1. Configure your module on your machine in the same way as you would for 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.
+
+1. (Optional) After a first run script runs successfully, Viam adds a marker file with a `.first_run_succeeded` suffix in the module’s data directory on disk.
+   It has the location and form: `/root/.viam/packages/data/module/<MODULE_ID>-<VERSION>-<ARCH>.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.
+
+1. (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.
+
+{{% /expand %}}
+
 ## Design a custom ML model
 
 When working with the [ML model service](/dev/reference/apis/services/ml/), you can deploy an [existing model](/data-ai/ai/deploy/) or [train your own model](/data-ai/ai/train/).