From 6e48b9279dabe314f05dde77f91c7155a8804150 Mon Sep 17 00:00:00 2001 From: Naomi Pentrel <5212232+npentrel@users.noreply.github.com> Date: Fri, 22 Nov 2024 11:33:33 +0100 Subject: [PATCH] DOCS-2705: Add username and env attributes for processes (#3649) --- docs/appendix/glossary/process.md | 6 +- docs/configure/processes.md | 95 ++++++++++++++----------------- 2 files changed, 44 insertions(+), 57 deletions(-) diff --git a/docs/appendix/glossary/process.md b/docs/appendix/glossary/process.md index 8bc01f9984..4f38391e68 100644 --- a/docs/appendix/glossary/process.md +++ b/docs/appendix/glossary/process.md @@ -2,13 +2,9 @@ title: Process id: process full_link: -short_description: You can configure instances of programs or scripts to run on your machine part. +short_description: Managed instances of programs or scripts running on a machine part. --- Processes are instances of programs, invoked by commands running binaries or scripts on a {{< glossary_tooltip term_id="part" text="part" >}}. -You can use processes to create a new local instance of `viam-server` to implement drivers for custom {{< glossary_tooltip term_id="component" text="components" >}}, or to run a client application, for example. -They provide an OS-specific process managed by `viam-server` to either run once or indefinitely. -For example, you could use a process to run a camera server. - Find more information in [Configure a Process to Run on Your Machine](/configure/processes/). diff --git a/docs/configure/processes.md b/docs/configure/processes.md index 25dd30b9d1..b9c0d2618c 100644 --- a/docs/configure/processes.md +++ b/docs/configure/processes.md @@ -1,78 +1,55 @@ --- -title: "Configure a Process to Run on Your Machine" -linkTitle: "Automatic Processes" +title: "Configure a managed process" +linkTitle: "Managed Processes" weight: 50 type: "docs" -description: "Configure a process to automatically run a command such as a script automatically when your machine boots." +description: "Configure a process to run a program when your machine is online." tags: ["processes"] aliases: - /build/configure/processes/ date: "2022-01-01" -# updated: "" # When the content was last entirely checked +updated: "2024-11-01" --- -To automatically run a specified command when your machine boots, configure a _{{< glossary_tooltip term_id="process" text="process" >}}_. -A process can be any command, for example one that executes a binary or a script. -You can configure a process to run once when the machine first starts, or to run continuously alongside `viam-server`. +To run a program or control code when your machine is online, configure a _{{< glossary_tooltip term_id="process" text="process" >}}_. +The process is managed by `viam-server`. +You can configure processes to run once upon startup or indefinitely. -## Set up dependencies for control code to run as a process - -If you are configuring a process to run a script that does not use Viam SDKs, skip this section and continue to [Configure a process](#configure-a-process). -Due to the way processes are designed for stability, if you are configuring a process to run a [Viam SDK](/sdks/) script, you need to install the relevant SDK as well as other required dependencies in a specific way on your SBC: - -{{< tabs >}} -{{% tab name="Python" %}} - -1. [`ssh` into your board](/installation/prepare/rpi-setup/#connect-with-ssh) and install `pip`: - - ```sh {class="command-line" data-prompt="$"} - sudo apt install -y python3-pip - ``` - -2. Install the Viam Python SDK (and other dependencies if required) into a new folder called `robot`: - - ```sh {class="command-line" data-prompt="$"} - pip3 install --target=robot viam-sdk - ``` - -3. Display the full path of the current directory you are working in on your board. Make a note of this output for the next step. - - ```sh {class="command-line" data-prompt="$"} - pwd - ``` - -4. Add your code to the robot folder. - -{{% /tab %}} -{{< /tabs >}} +{{< alert title="In this page" color="note" >}} +{{% toc %}} +{{< /alert >}} ## Configure a process Navigate to the **CONFIGURE** tab of your machine's page in the [Viam app](https://app.viam.com). -Click the **+** icon next to your machine {{< glossary_tooltip term_id="part" text="part" >}} in the left-hand menu and select **Process**. -Your process is automatically created with a name (`id` in JSON) like **process-1** and a card matching that name on the **CONFIGURE** tab. -Navigate to that card. +Click the **+** icon next to your machine part in the left-hand menu and select **Process**. -Then fill in the following fields: +In the process configuration panel, configure the attributes for your process: -| Attribute (Builder Mode) | Attribute (JSON) | Type | Required? | Description | -| ------------------------ | ---------------- | ------- | --------- | ----------- | -| Executable | `name` | string | **Required** | The command you want to execute when your machine connects to the server. On many operating systems, you can find the executable path of commands by running with `which `. | -| Arguments | `args` | string | Optional | Arguments to follow the command. | -| Working directory | `cwd` | string | Optional | Where you want the process to execute. Defaults to the directory where `viam-server` executes. | -| Logging | `log` | boolean | Optional | Toggle logging of errors and other messages on or off. Default: `false`. | -| Execute once | `one_shot` | boolean | Optional | Toggle whether to execute the command just once or keep running the process indefinitely. | - -Click **Save** in the upper right corner of the screen to save your config. +| Attribute | Type | Required? | Description | +| --------- | ---- | --------- | ----------- | +| Executable (`name`) | string | **Required** | The command you want to execute when your machine connects to the server. On many operating systems, you can find the executable path of commands by running `which `. | +| Arguments (`args`) | string[] | Optional | Arguments to follow the command. | +| Working directory (`cwd`) | string | Optional | Where you want the process to execute. Defaults to the directory where `viam-server` executes. | +| `username` (not available in builder mode) | string | Optional | Run this process as a different user. Example: `"username": "ubuntu"`. | +| `env` (not available in builder mode) | Map | Optional | Environment variables for the process. Environment variables are encrypted in transit but are stored in plain text in the configuration file that resides on the machine. Example: `"environment": { "SVC_API_KEY":"VALUE" }`. | +| Logging (`log`) | boolean | Optional | Toggle logging of errors and other messages on or off.
Default: `false`. | +| Execute once (`one_shot`) | boolean | Optional | Toggle whether to execute the command just once or keep running the process indefinitely.
  • If `true`, the process executes once at `viam-server` startup. Until the process completes, `viam-server` startup is blocked and the machine appears offline in the [Viam app](https://app.viam.com). This machine should only be used for quick processes.
  • If `false`, the process continues to run and is restarted if the process crashes or is killed. The process does not block `viam-server`.
Default: `false`. | + +Click **Save** in the upper right corner of the screen. ### Example -The following example configuration executes the command `python3 my_cool_script.py` in your /home/myName/project/ directory every time your machine boots, and keeps it executing indefinitely. +The following example executes the command `python3 my_cool_script.py` in your /home/myName/project/ directory every time a machine boots, and restarts the process if it stops running. + +{{< tabs >}} +{{% tab name="Builder mode" %}} ![The CONFIGURE tab with a process called run-my-code configured. The executable is python3, the argument is my_cool_script.py, and the working directory is /home/myName/project. Logging is turned on and execute once is turned off.](/build/configure/process-fancy.png) -The corresponding JSON looks like this: +{{% /tab %}} +{{% tab name="JSON" %}} ```json "processes": [ @@ -87,3 +64,17 @@ The corresponding JSON looks like this: } ] ``` + +{{% /tab %}} +{{< /tabs >}} + +## Set up dependencies + +If you are configuring a process that requires dependencies, such as the Viam SDKs, you must install those dependencies so `viam-server` has access to them. + +For Python scripts, we recommend you install dependencies into the folder that contains the code you want to execute: + +```sh {class="command-line" data-prompt="$"} +sudo apt install -y python3-pip +pip3 install --target=machine viam-sdk +```