Skip to content

Commit

Permalink
DOCS-2705: Add username and env attributes for processes (#3649)
Browse files Browse the repository at this point in the history
  • Loading branch information
@npentrel
npentrel authored Nov 22, 2024
1 parent dae9017 commit 6e48b92
Show file tree
Hide file tree
Showing 2 changed files with 44 additions and 57 deletions.
6 changes: 1 addition & 5 deletions docs/appendix/glossary/process.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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/).
95 changes: 43 additions & 52 deletions docs/configure/processes.md
View file
Original file line number Diff line number Diff line change
@@ -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 <other-required-dependencies>
```

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 <file>robot</file> 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:

<!-- prettier-ignore -->
| 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 <command-name>`. |
| 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.<ul><li>If true, the process executes once at `viam-server` startup. Until the process completes, `viam-server` startup is blocked and the robot appears offline in the [Viam app](https://app.viam.com), so this should only be used for quick processes.</li><li>If false, the process continues to run. If the process crashes, it automatically restarts. It does not block `viam-server`. Default: `false`.</li></ul> |
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 <command-name>`. |
| 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<string, string> | 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. <br>Default: `false`. |
| Execute once (`one_shot`) | boolean | Optional | Toggle whether to execute the command just once or keep running the process indefinitely.<ul><li>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.</li><li>If `false`, the process continues to run and is restarted if the process crashes or is killed. The process does not block `viam-server`.</li></ul> 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 <file>/home/myName/project/</file> directory every time your machine boots, and keeps it executing indefinitely.
The following example executes the command `python3 my_cool_script.py` in your <file>/home/myName/project/</file> 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": [
Expand All @@ -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 <other-required-dependencies>
```

0 comments on commit 6e48b92

Please sign in to comment.