Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

DOCS-2705: Add username and env attributes for processes #3649

Merged
merged 5 commits into from
Nov 22, 2024
+44 −57
Merged

DOCS-2705: Add username and env attributes for processes #3649

Changes from 1 commit
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
0b4671e
DOCS-2705: Add username and env attributes for processes
npentrel Nov 1, 2024
63f0518
Update glossary
npentrel Nov 1, 2024
7711368
Apply suggestions from code review
npentrel Nov 22, 2024
adb1555
Update docs/configure/processes.md
npentrel Nov 22, 2024
37ec0df
Update docs/configure/processes.md
npentrel Nov 22, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
95 changes: 43 additions & 52 deletions docs/configure/processes.md
View file
Open in desktop
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. |
npentrel marked this conversation as resolved.
Show resolved Hide resolved
| 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 | Example: `"username": "ubuntu"`. |
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@zaporter-work I was not able to confirm that the username attribute does anything. My assumption is that it would allow us to run the process as a user?

On my pi I added a process with this config:

{
      "env": {
        "SVC_API_KEY": "VALUE"
      },
      "username": "pi",
      "id": "process-2",
      "name": "python",
      "args": [
        "username.py"
      ],
      "cwd": "/home/pi",
      "log": true,
      "one_shot": false
    }

and this little python program:

import os
import getpass
import time

while True:
  print(1)
  print(time.sleep(1))
  raise ValueError(getpass.getuser())

I can't see anytihng printed at all and what gets raised always indicates that the process runs as root.

Does username do somethign else?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you so much for testing this!

I have just confirmed that with the newest RDK, this now works.

A slightly easier way to test that this works is via the whoami command:

  "processes": [
    {
      "username": "pi",
      "id": "process-1",
      "name": "whoami",
      "log": true
    }
  ],

npentrel marked this conversation as resolved.
Show resolved Hide resolved
| `env` (not available in builder mode) | string | Optional | Environment variables for the process. Example: `"environment": { "SVC_API_KEY":"VALUE" }`. |
Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@zaporter-work could you confirm for me how the config for a machine reaches the machine? That's all e2e encrypted right? I think we should probably mention that here.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Talked offline -- this is not e2e encrypted. The config is encrypted in transit, but is not encrypted at rest (on the robot or in our db).

That implies that you should exercise some caution when putting api keys in here as you are trusting the security of the viam database and viam employees.

npentrel marked this conversation as resolved.
Show resolved Hide resolved
| 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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Seems better down here +1


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>
```
Loading