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.

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

DOCS-2046: Update install and agent docs #3243

Merged
merged 9 commits into from
Aug 16, 2024

Conversation

npentrel
Copy link
Collaborator

@npentrel npentrel commented Aug 13, 2024

  • installation: ready for review
    • the change from micro-RDK to viam-micro-server will happen separately to limit complexity
  • agent: ready for review
  • provisioning: ready for review

Currently missing and I am leaning towards doing that in a separate PR:

  • Offline/pre-installation
  • Test CLI Utility

@viambot viambot added the safe to build This pull request is marked safe to build from a trusted zone label Aug 13, 2024
@npentrel npentrel changed the title Update install and agent docs DOCS-2046: Update install and agent docs Aug 13, 2024
@npentrel npentrel force-pushed the viam-agent-full branch 9 times, most recently from abb4345 to 7b710fa Compare August 14, 2024 18:24
docs/configure/agent.md Outdated Show resolved Hide resolved
docs/configure/agent.md Outdated Show resolved Hide resolved
docs/configure/agent.md Outdated Show resolved Hide resolved
Currently, `viam-agent` is only supported on Linux, for amd64 (x86_64) and arm64 (aarch64) CPUs.
{{< /alert >}}

To see how to provision machines using `viam-agent`, see
Copy link
Collaborator

Choose a reason for hiding this comment

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

Suggested change
To see how to provision machines using `viam-agent`, see
To provision machines using `viam-agent`, see


1. Create a configuration file with the desired configuration for your machine. You can:

- [create a new machine in the Viam app](/cloud/machines/#add-a-new-machine) and configure it as desired or use an existing deployed machine, then switch to **Raw JSON** mode and copy the configuration shown into a new file on your machine.
Copy link
Collaborator

Choose a reason for hiding this comment

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

Suggested change
- [create a new machine in the Viam app](/cloud/machines/#add-a-new-machine) and configure it as desired or use an existing deployed machine, then switch to **Raw JSON** mode and copy the configuration shown into a new file on your machine.
- [create a new machine in the Viam app](/cloud/machines/#add-a-new-machine) and configure it as desired or use an existing deployed machine, then switch to **Builder** mode and copy the configuration shown into a new file on your machine.

You can configure update behavior for the Agent and `viam-server` using the [Viam app](https://app.viam.com/).

{{< alert title="Important" color="note" >}}
When `viam-agent` updates either itself or `viam-server`, you must [restart these services](/installation/manage-viam-agent/) in order to use the new version.
Copy link
Collaborator

Choose a reason for hiding this comment

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

Suggested change
When `viam-agent` updates either itself or `viam-server`, you must [restart these services](/installation/manage-viam-agent/) in order to use the new version.
When `viam-agent` updates either itself or `viam-server`, you must [restart these system services](/installation/manage-viam-agent/) in order to use the new version.

(opt) maybe to distinguish from resource services?

You can find these messages on the [**LOGS** tab](/cloud/machines/#logs) of your machine's page.

`viam-agent` only sends messages when your machine is online and connected to the internet.
If your machine is offline, log messages are queued, and are sent to the Viam app once your machine reconnects to the internet.
Copy link
Collaborator

Choose a reason for hiding this comment

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

Suggested change
If your machine is offline, log messages are queued, and are sent to the Viam app once your machine reconnects to the internet.
If your machine is offline, log messages are queued and are sent to the Viam app once your machine reconnects to the internet.

thinmk this is oxford comma so feel free to ignore

docs/configure/agent.md Outdated Show resolved Hide resolved
docs/fleet/provision.md Outdated Show resolved Hide resolved
docs/fleet/provision.md Outdated Show resolved Hide resolved
@npentrel npentrel force-pushed the viam-agent-full branch 10 times, most recently from 53fec63 to 6ddd704 Compare August 15, 2024 18:20
@npentrel npentrel requested review from Otterverse and ale7714 August 15, 2024 18:21
Copy link
Member

@Otterverse Otterverse left a comment

Choose a reason for hiding this comment

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

Okay, finished reading through these new/updated pages. Sorry there are so many notes. Lots are duplicates though. Feel free to slack me with questions or if you need clarifications.


1. Go to the [Viam app](https://app.viam.com).
Create an account if you haven't already.
- `manual`: installs `viam-server` directly on your machine.
Copy link
Member

Choose a reason for hiding this comment

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

This isn't very clear. What does "directly" mean in this context? "Manual" actually points to the AppImage install instructions for most drop-down combinations. Might be better worded as "Installs only viam-server"

1. Go to the [Viam app](https://app.viam.com).
Create an account if you haven't already.
- `manual`: installs `viam-server` directly on your machine.
- `viam-agent`: installs [`viam-agent`](/configure/agent/) which provisions a machine as it first comes online with a pre-defined configuration.
Copy link
Member

Choose a reason for hiding this comment

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

This doesn't make sense to me, in the context of the steps below for this option, nor how it contrasts with the "manual" option above. Would reword as something like "Installs viam-agent, which will automatically install/updated viam-server, AND provide additional functions such as provisioning (link_to_provisioning) and OS update configuration."


1. Once you have followed the steps on the setup instructions, `viam-server` is installed and running.
Wait for confirmation that your computer has successfully connected.
On your machine's page on [the Viam app](https://app.viam.com), your machine will show that it's **Live**.
Copy link
Member

Choose a reason for hiding this comment

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

Both these tabs show almost identical information, which could be summerized as "follow the instructions, and wait for it to come online." I also find it slightly confusing to switch tabs ONLY for steps 6-7 of a multi-step process. I thought the box glitched at first and wasn't showing earlier steps (as a box feels "separate" from the content outside of it.)


{{% /tab %}}
{{< /tabs >}}

{{<youtube embed_url="https://www.youtube-nocookie.com/embed/gmIW9JoWStA">}}
{{< alert title="Linux: Automatic startup" color="note" >}}
On Linux installs, `viam-server` will start automatically when your system boots by default, but you can [change this behavior](/installation/manage-viam-server/) if desired.
Copy link
Member

Choose a reason for hiding this comment

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

This links to docs that only work for the "manual" (aka the AppImage) install method.


### Manage `viam-server`

To learn how to run, update, or uninstall `viam-server`, see [Manage `viam-server`](/installation/manage/).
To learn how to run, update, or uninstall `viam-server`, see [Manage `viam-server`](/installation/manage-viam-server/).
Copy link
Member

Choose a reason for hiding this comment

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

Same as above, only applies to AppImage install method.

| ---------- | ------ | --------- | ----------- |
| `manufacturer` | string | Optional | Purely informative. May be displayed on captive portal and/or mobile app. Default: `"viam"`. |
| `model` | string | Optional | Purely informative. May be displayed on captive portal and/or mobile app. Default: `"custom"`. |
| `fragment_id` | string | Optional | The `fragment_id` of the fragment to configure machines with. If present, the Viam mobile app can pre-configure a robot for a user by using this [TODO: and otherwise it can't??]. |
Copy link
Member

Choose a reason for hiding this comment

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

Currently, we expect a fragment with our Mobile App experience. The mobile app is responsible for adding said fragment to the newly created machine's configuration.

docs/fleet/provision.md Outdated Show resolved Hide resolved
| `hotspot_prefix` | string | Optional | Viam agent will prepend this to the hostname of the device append and use the resulting string for the provisioning hotspot SSID. Default: `"viam-setup"`. |
| `disable_dns_redirect` | boolean | Optional | By default, ALL DNS lookups using the provisioning hotspot will redirect to the device. This causes most phones/mobile devices to automatically redirect the user to the captive portal as a "sign in" screen. When disabled, only domains ending in .setup (ex: viam.setup) will be redirected. This generally avoids displaying the portal to users and is mainly used in conjunction with a mobile provisioning application workflow. Default: `false`. |
| `hotspot_password` | string | Optional | The Wifi password for provisioning hotspot. Default: `"viamsetup"`. |
| `roaming_mode` | boolean | Optional | By default, the device will only attempt to connect to a single wifi network (the one with the highest priority), usually provided during initial provisioning/setup using the Viam app or the Viam mobile app. Wifi connection alone is enough to consider the device as "online" even if the global internet is not reachable. When enabled, the device will attempt connections to all configured networks, and only considers the device online if the internet is reachable. See [roaming mode](#how-an-end-user-would-use-it). Default: `false`. |
Copy link
Member

@Otterverse Otterverse Aug 15, 2024

Choose a reason for hiding this comment

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

Suggested change
| `roaming_mode` | boolean | Optional | By default, the device will only attempt to connect to a single wifi network (the one with the highest priority), usually provided during initial provisioning/setup using the Viam app or the Viam mobile app. Wifi connection alone is enough to consider the device as "online" even if the global internet is not reachable. When enabled, the device will attempt connections to all configured networks, and only considers the device online if the internet is reachable. See [roaming mode](#how-an-end-user-would-use-it). Default: `false`. |
| `roaming_mode` | boolean | Optional | By default, the device will only attempt to connect to a single wifi network (the one with the highest priority), usually provided during initial setup using the Viam mobile app or captive web portal. Wifi connection alone is enough to consider the device as "online" even if the global internet is not reachable. When enabled, the device will instead attempt connections to all configured networks, and only considers the device online if the internet is reachable. See [roaming mode](#how-an-end-user-would-use-it). Default: `false`. |

docs/fleet/provision.md Outdated Show resolved Hide resolved
| `offline_timeout` | boolean | Optional | Will only enter provisioning mode (hotspot) after being disconnected longer than this time. Useful on flaky connections, or when part of a system where the device may start quickly, but the wifi/router may take longer to be available. Default: `"2m"` (2 minutes). |
| `user_timeout` | boolean | Optional | Amount of time before considering a user (using the provisioning portal using web or mobile app) idle, and resuming normal behavior. Used to avoid interrupting provisioning mode (for example for network tests/retries) when a user might be busy entering details. Default: `"5m"` (5 minutes). |
| `fallback_timeout` | boolean | Optional | Provisioning mode will exit after this time, to allow other unmanaged (for example wired) or manually configured connections to be tried. Provisioning mode will restart if the connection/online status doesn't change. Default: `"10m"` (10 minutes). |
| `networks` | boolean | Optional | The type of the network. See [Networks](/configure/agent/#networks). Default: `[]`. |
Copy link
Member

Choose a reason for hiding this comment

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

This is a complex structure, (same as in attributes.) It's not just "the type of the network." While it CAN be set here, it's advised/preferred that manufacturers instead directly enter wifi settings in the OS (e.g. directly in NetworkManager.)

docs/configure/agent.md Outdated Show resolved Hide resolved
@npentrel npentrel force-pushed the viam-agent-full branch 5 times, most recently from 0c603b8 to d6137c4 Compare August 16, 2024 14:23
<!-- prettier-ignore -->
| Option | Type | Required? | Description |
| ------ | ---- | --------- | ----------- |
| `attributes` | object | Optional | <ul><li>`logging`: parameters for logging<ul>`disable`: when set to `true`, removes any prior tweaks to the logging config and disables the use of defaults??.<li>`system_max_use`: sets the maximum disk space journald will user for persistent log storage. Numeric values are in bytes, with optional single letter suffix for larger units, for example. K, M, or G. Default: `512M`.</li><li>`runtime_max_use`: sets the runtime/temporary limit. Numeric values are in bytes, with optional single letter suffix for larger units, for example. K, M, or G. Default: `512M`.</li></ul></li><li>`upgrades`: Using `upgrades` installs the `unattended-upgrades` package, and replace `20auto-upgrades` and `50unattended-upgrades` in <FILE>/etc/apt/apt.conf.d/</FILE>, with the latter's Origins-Pattern list being generated automatically from configured repositories on the system, so custom repos (at the time the setting is enabled) will be included.<ul><li>`type`: Configured unattended upgrades for Debian bullseye and bookworm. Options: `""` (no effect), `"disable"` (disables automatic upgrades), `"security"` (only enables updates from sources with security in their codename, ex: bookworm-security), `"all"` (enable updates from all configured sources).</li></ul></li></ul> |
Copy link
Collaborator Author

Choose a reason for hiding this comment

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

@Otterverse I don't understand the disable option. It disables the use of defaults? What does that mean?

@npentrel npentrel force-pushed the viam-agent-full branch 2 times, most recently from d704175 to 9432ade Compare August 16, 2024 16:15
@npentrel npentrel requested a review from Otterverse August 16, 2024 16:18
@npentrel npentrel force-pushed the viam-agent-full branch 2 times, most recently from 6ff5ae1 to 162df2c Compare August 16, 2024 16:38
Co-authored-by: Sierra Guequierre <[email protected]>
Co-authored-by: James Otting <[email protected]>
Copy link
Member

@Otterverse Otterverse left a comment

Choose a reason for hiding this comment

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

Only a few more things it looks like. Much better overall, IMHO! Thanks for dealing with all my suggestions from yesterday.

docs/fleet/provision.md Show resolved Hide resolved
docs/fleet/provision.md Outdated Show resolved Hide resolved

### View Viam Agent logs
- The [`agent-provisioning` configuration](#configuration) is at <file>/etc/viam-provisioning.json</file.
- The [`viam-agent` configuration](/configure/agent/#configuration), if provided, is at <file>/etc/viam.json</file> alongside the rest of the machine configuration, including which fragments to use (if any).
Copy link
Member

Choose a reason for hiding this comment

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

This is not correct. The machine configuration (including fragments) is in the cloud/App. /etc/viam.json contains the machine credentials to connect TO the cloud.

If your machine is offline, log messages are queued, and are sent to the Viam app once your machine reconnects to the internet.
- By default, the hotspot network is named `viam-setup-HOSTNAME`, where `HOSTNAME` is replaced with the hostname of your machine.
The WiFi password for this hotspot network is `viamsetup` by default.
You can customize these values in the machine's or fragment's [`viam-agent` configuration](/configure/agent/#configuration).
Copy link
Member

Choose a reason for hiding this comment

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

These are mostly meant to be customized in the provisioning configuration (/etc/viam-provisioning.json), not the Cloud configuration, as only that can be read/used when offline (e.g. before the user has first provisioned the machine.)

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

that makes sense but why is it configurable in the agent config as well then?

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

maybe it isn't

Copy link
Collaborator Author

Choose a reason for hiding this comment

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


The Viam Agent writes log messages to the [Viam app](https://app.viam.com/).
You can find these messages on the [**LOGS** tab](/cloud/machines/#logs) of your machine's page.
1. The end user uses their mobile device or computer and connects to the WiFi hotspot.
Copy link
Member

Choose a reason for hiding this comment

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

If they're using the mobile app, they should open that first (while still on the internet) and follow the instructions there. (It needs to do stuff BEFORE connecting to the hotspot, and will then tell the user when to switch networks to the hotspot.)

docs/fleet/provision.md Outdated Show resolved Hide resolved
docs/fleet/provision.md Outdated Show resolved Hide resolved
docs/installation/_index.md Outdated Show resolved Hide resolved
Comment on lines 115 to 118
{{< alert title="Linux: Automatic startup" color="note" >}}
On manual Linux installs, `viam-server` will start automatically when your system boots.
You can [change this behavior](/installation/manage-viam-server/) if desired.
{{< /alert >}}
Copy link
Member

Choose a reason for hiding this comment

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

This happens for agent too, just how you manage it is slightly different (e.g. it's the viam-agent service, instead of the viam-server service.)

```sh {class="command-line" data-prompt="$"}
sudo systemctl restart viam-agent
```

Copy link
Member

Choose a reason for hiding this comment

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

This should probably also include the enable and disable commands (similar to what's on the viam-server version of this page) The commands are almost the same, "viam-server" just becomes "viam-agent" in each.

Copy link
Member

Choose a reason for hiding this comment

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

Still think this would be good to add, especially as this is now linked from the alert about "Automatic Startup"

<!-- prettier-ignore -->
| Option | Type | Required? | Description |
| ------ | ---- | --------- | ----------- |
| `attributes` | object | Optional | <ul><li>`hotspot_password`: Set a password for the WiFi hotspot a machine creates during provisioning.</li><li>`networks`: Networks a machine can automatically connect to when roaming mode is enabled in the [`agent-provision`](/fleet/provision/#configuration) and either no primary network was configured by the end user in the provisioning app or the primary network cannot be connected to. See [#networks].</li><li>`roaming_mode`: If enabled, lets the machine connect to additional configured netowrks. See [Networks](#networks).</li></ul> |
Copy link
Collaborator Author

Choose a reason for hiding this comment

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

@Otterverse can you check these? Is hotspot_password meant to be configurable here? Maybe I put that here wrong.

Copy link
Member

Choose a reason for hiding this comment

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

Under the hood, everything in provisioning's "attributes" is/can be identical to that in "/etc/viam-provisioning.json" The on-machine file is meant to be customized by the manufacturer, to provide "out of the box" settings. The attributes (in the cloud config) can let the user override those if they wish, but (as it's in the cloud) only after the machine gets online. Most of the initial stuff (like manufactuer, model, fragment_id, etc) the user generally shouldn't change, but the hotspot_password is one they can/should (for security), along with roaming_mode and any additional networks they want to configure. Anything here overrides what is set by the manufacturer in "/etc/viam-provisioning.json"

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

Ok, I'll add that it overrides those settings and add the rest of the settings I guess.

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

done.

Copy link
Member

Choose a reason for hiding this comment

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

Sorry, wasn't saying you need to add that specifically. Was clarifying for YOUR understanding primarily. The reason for only listing SOME of the available options here is that it's only recommended to change these (for the end user.)

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

I understand - I think if I didn't understand it other might not either, so I think adding it might be good

@npentrel npentrel requested a review from Otterverse August 16, 2024 19:57
docs/installation/_index.md Outdated Show resolved Hide resolved
Copy link
Member

@Otterverse Otterverse left a comment

Choose a reason for hiding this comment

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

A couple small notes, but nothing critical, so I'll approve this for now. As mentioned though, I think it would be nice (but not required) to clean up the mobile app provisioning description, and to add the enable/disable commands to the "manage viam-agent" page.

docs/configure/agent.md Outdated Show resolved Hide resolved
<!-- prettier-ignore -->
| Option | Type | Required? | Description |
| ------ | ---- | --------- | ----------- |
| `attributes` | object | Optional | <ul><li>`hotspot_password`: Set a password for the WiFi hotspot a machine creates during provisioning.</li><li>`networks`: Networks a machine can automatically connect to when roaming mode is enabled in the [`agent-provision`](/fleet/provision/#configuration) and either no primary network was configured by the end user in the provisioning app or the primary network cannot be connected to. See [#networks].</li><li>`roaming_mode`: If enabled, lets the machine connect to additional configured netowrks. See [Networks](#networks).</li></ul> |
Copy link
Member

Choose a reason for hiding this comment

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

Sorry, wasn't saying you need to add that specifically. Was clarifying for YOUR understanding primarily. The reason for only listing SOME of the available options here is that it's only recommended to change these (for the end user.)


### Manage the Viam Agent
{{< tabs >}}
{{% tab name="Mobile app" min-height="703px" %}}
Copy link
Member

Choose a reason for hiding this comment

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

I'm unclear on the mobile app flow. Previously (when I last used it) you could only use it to provision NEW machines. If that's still the case, then the reference below to where configuration is for machines that already exist is pointless (but also unlikely to be harmful.) I'm fine with it either way, so I'll leave this section for @ale7714 to sign off on.

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

I'll remove it.

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

for now, will actually test this in the next week

<!-- prettier-ignore -->
| Option | Type | Required? | Description |
| ------ | ---- | --------- | ----------- |
| `attributes` | object | Optional | <ul><li>`hotspot_password`: Set a password for the WiFi hotspot a machine creates during provisioning.</li><li>`networks`: Networks a machine can automatically connect to when roaming mode is enabled in the [`agent-provision`](/fleet/provision/#configuration) and either no primary network was configured by the end user in the provisioning app or the primary network cannot be connected to. See [#networks].</li><li>`roaming_mode`: If enabled, lets the machine connect to additional configured netowrks. See [Networks](#networks).</li></ul> |
Copy link
Collaborator Author

Choose a reason for hiding this comment

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

Suggested change
| `attributes` | object | Optional | <ul><li>`hotspot_password`: Set a password for the WiFi hotspot a machine creates during provisioning.</li><li>`networks`: Networks a machine can automatically connect to when roaming mode is enabled in the [`agent-provision`](/fleet/provision/#configuration) and either no primary network was configured by the end user in the provisioning app or the primary network cannot be connected to. See [#networks].</li><li>`roaming_mode`: If enabled, lets the machine connect to additional configured netowrks. See [Networks](#networks).</li></ul> |
| `attributes` | object | Optional | <ul><li>`hotspot_password`: Set a password for the WiFi hotspot a machine creates during provisioning.</li><li>`networks`: Networks a machine can automatically connect to when roaming mode is enabled in the [`agent-provision`](/fleet/provision/#configuration) and either no primary network was configured by the end user in the provisioning app or the primary network cannot be connected to. See [networks](#networks).</li><li>`roaming_mode`: If enabled, lets the machine connect to additional configured netowrks. See [Networks](#networks).</li></ul> |

docs/fleet/provision.md Outdated Show resolved Hide resolved
@viambot
Copy link
Member

viambot commented Aug 16, 2024

You can view a rendered version of the docs from this PR at https://docs-test.viam.dev/3243

@npentrel npentrel merged commit 4194100 into viamrobotics:main Aug 16, 2024
9 checks passed
@npentrel npentrel deleted the viam-agent-full branch August 16, 2024 21:07
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
safe to build This pull request is marked safe to build from a trusted zone
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants