Skip to content

Commit 311fc1c

Browse files
npentrelnpentrel
committed
Update
1 parent ff6fe87 commit 311fc1c

File tree

5 files changed

+221
-285
lines changed

5 files changed

+221
-285
lines changed

‎docs/operate/control/single-page-apps.md

Lines changed: 200 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,200 @@
1+
---
2+
title: "Create a custom web interface"
3+
linkTitle: "Create a custom web interface"
4+
weight: 11
5+
no_list: true
6+
type: docs
7+
description: "Create and deploy single page applications on the Viam platform."
8+
---
9+
10+
With single page apps you can create and deploy custom web interfaces for your machines that use a single HTML page.
11+
Single page apps are accessible from a dedicated URL (`appname.publicnamespace.viamapps.com`) and hosting and authentication is handled for you.
12+
13+
When opening an app, users log in and then select a machine they have access to.
14+
Then your app is rendered and ready for use.
15+
16+
TODO: Example GIF
17+
18+
## Requirements
19+
20+
{{< expand "Install the Viam CLI and authenticate." >}}
21+
Install the Viam CLI using the option below that matches your system architecture:
22+
23+
{{< readfile "/static/include/how-to/install-cli.md" >}}
24+
25+
Then authenticate your CLI session with Viam using one of the following options:
26+
27+
{{< readfile "/static/include/how-to/auth-cli.md" >}}
28+
29+
{{< /expand >}}
30+
31+
## Create a single page app
32+
33+
{{< table >}}
34+
{{% tablestep number=1 %}}
35+
36+
**Build your single page application** using your preferred framework like React, Vue, Angular, or others.
37+
Your application should be built and ready for deployment, with all assets compiled into a distributable format.
38+
39+
TODO: cover dev process
40+
TODO: how do you connect to the machine / how do you access the api key?
41+
42+
{{% /tablestep %}}
43+
{{% tablestep number=2 %}}
44+
45+
**Create a <FILE>meta.json</FILE>** file using this template:
46+
47+
{{< tabs >}}
48+
{{% tab name="Template" %}}
49+
50+
```json
51+
{
52+
"module_id": "your-namespace:your-module",
53+
"visibility": "public",
54+
"url": "https://github.com/your-org/your-repo",
55+
"description": "Your module description",
56+
"applications": [
57+
{
58+
"name": "your-app-name",
59+
"type": "web",
60+
"entrypoint": "dist/index.html"
61+
}
62+
]
63+
}
64+
```
65+
66+
{{% /tab %}}
67+
{{% tab name="Example" %}}
68+
69+
```json
70+
{
71+
"module_id": "acme:dashboard",
72+
"visibility": "public",
73+
"url": "https://github.com/acme/dashboard",
74+
"description": "An example dashboard for a fictitious company called Acme.",
75+
"applications": [
76+
{
77+
"name": "dashboard",
78+
"type": "web",
79+
"entrypoint": "dist/index.html"
80+
}
81+
]
82+
}
83+
```
84+
85+
{{% /tab %}}
86+
{{< /tabs >}}
87+
88+
{{% expand "Click to view" %}}
89+
90+
<!-- prettier-ignore -->
91+
| Name | Type | Inclusion | Description |
92+
|------|------|-----------|-------------|
93+
| `module_id` | string | **Required** | The module ID, which includes the organization name and the module name. `module_id` uniquely identifies your module. |
94+
| `visibility` | string | **Required** | Must be `"public"`. |
95+
| `description` | string | **Required** | A description of your module and what it provides. |
96+
| `url` | string | Optional | The URL of the GitHub repository containing the source code of the module. |
97+
| `applications` | array | Optional | Objects that provide information about the [single page apps](/operate/reference/single-page-apps/) associated with the module. |
98+
| `models` | array | Optional | Empty unless you are shipping the app alongside models. For information on how to add models, see [Integrate other hardware](/operate/get-started/other-hardware/). |
99+
100+
{{% /expand%}}
101+
102+
The `applications` field is an array of application objects with the following properties:
103+
104+
<!-- prettier-ignore -->
105+
| Property | Type | Description |
106+
| ------------ | ------ | ------------------------------------------------------------------------------------------------- |
107+
| `name` | string | The name of your application, which will be a part of the app's URL (`name.publicnamespace.viamapps.com`). For more information on valid names see [](/operate/reference/naming-modules). |
108+
| `type` | string | The type of application (currently only `"web"` is supported). |
109+
| `entrypoint` | string | The path to the HTML entry point for your application. The `entrypoint` field specifies the path to your application's entry point. For example: <ul><li><code>"dist/index.html"</code>: Static content rooted at the `dist` directory</li><li><code>"dist/foo.html"</code>: Static content rooted at the `dist` directory, with `foo.html` as the entry point</li><li><code>"dist/"</code>: Static content rooted at the `dist` directory (assumes `dist/index.html` exists)</li><li><code>"dist/bar/foo.html"</code>: Static content rooted at `dist/bar` with `foo.html` as the entry point</li></ul> |
110+
111+
{{% /tablestep %}}
112+
{{% tablestep number=3 %}}
113+
114+
**Package your app into a module and upload it** to the Viam Registry:
115+
116+
TODO: first command doesn't make sense
117+
118+
```sh {class="command-line" data-prompt="$" data-output="3-10"}
119+
viam module build local
120+
viam module upload module.tar.gz
121+
```
122+
123+
TODO: the upload command requires platform & version - is that no longer the case?
124+
125+
For subsequent updates you can use:
126+
127+
```sh {class="command-line" data-prompt="$" data-output="2-10"}
128+
viam module update
129+
```
130+
131+
{{% /tablestep %}}
132+
{{< /table >}}
133+
134+
## Accessing your Single Page App
135+
136+
Once your module with the application configuration is uploaded, your application will be available at:
137+
138+
TODO: any extra steps?
139+
140+
```
141+
https://your-app-name.your-public-namespace.viamapps.com
142+
```
143+
144+
Users will be prompted to authenticate with their Viam credentials before accessing your application:
145+
146+
1. User navigates to `your-app-name.your-public-namespace.viamapps.com`
147+
1. User authenticates with Viam credentials
148+
1. User selects an organization, location, and machine
149+
1. User is redirected to `your-app-name.your-public-namespace.viamapps.com/machine/{machine-id}`
150+
1. Your application is rendered with access to the selected machine
151+
152+
## Limitations
153+
154+
- Single page apps currently only support single-machine applications
155+
- All modules with apps must have public visibility
156+
- There is no versioning or separate deploy step; the page will always render the latest version
157+
- Browsers with cookies disabled are not supported
158+
159+
## Security Considerations
160+
161+
- Customer apps are stored in GCS buckets that are publicly available on the internet
162+
- Avoid uploading sensitive information in your application code or assets
163+
- API keys and secrets are stored in the browser's localStorage or sessionStorage
164+
- Single page apps authenticate users with FusionAuth
165+
166+
## Example
167+
168+
Here's a complete example of creating and uploading a simple React application as a Viam Single Page App:
169+
170+
```bash
171+
# Create a new React app
172+
npx create-react-app my-viam-app
173+
cd my-viam-app
174+
175+
# Build the app
176+
npm run build
177+
178+
# Create a module with the app
179+
viam module create --name my-viam-app --public-namespace your-namespace
180+
181+
# Edit meta.json to add the application configuration
182+
# Add the following to meta.json:
183+
# "visibility": "public",
184+
# "applications": [
185+
# {
186+
# "name": "my-app",
187+
# "type": "web",
188+
# "entrypoint": "build/index.html"
189+
# }
190+
# ]
191+
192+
# Copy the build directory to the module directory
193+
cp -r build/ path/to/module/
194+
195+
# Build and upload the module
196+
viam module build local
197+
viam module upload module.tar.gz
198+
```
199+
200+
After the module is approved, your application will be available at `https://my-app.your-public-namespace.viamapps.com`.

‎docs/operate/get-started/other-hardware/_index.md

Lines changed: 11 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -990,16 +990,16 @@ Do not change the <code>module_id</code>.</p>
990990
</tr>
991991
<tr>
992992
<td><code>models</code></td>
993-
<td>object</td>
994-
<td><strong>Required</strong></td>
995-
<td><p>A list of one or more {{< glossary_tooltip term_id="model" text="models" >}} provided by your custom module. You must provide at least one model, which consists of an <code>api</code> and <code>model</code> key pair. If you are publishing a public module (<code>"visibility": "public"</code>), the namespace of your model must match the <a href="/operate/reference/naming-modules/#create-a-namespace-for-your-organization">namespace of your organization</a>.</p>
993+
<td>array</td>
994+
<td>Optional</td>
995+
<td><p>A list of one or more {{< glossary_tooltip term_id="model" text="models" >}} provided by your custom module. You must provide at least one model in the models array or one application in the applications array. A model consists of an <code>api</code> and <code>model</code> key pair. If you are publishing a public module (<code>"visibility": "public"</code>), the namespace of your model must match the <a href="/operate/reference/naming-modules/#create-a-namespace-for-your-organization">namespace of your organization</a>.</p>
996996
<p>You are strongly encouraged to include a <code>markdown_link</code> to the section of the README containing configuration information about each model, so that the section will be displayed alongside the configuration panel when configuring the model. For example, <code>"README.md#configure-your-meteo_pm-sensor"</code>. Please also include a <code>short_description</code> describing what hardware the model supports.</p></td>
997997
</tr>
998998
<tr>
999999
<td><code>entrypoint</code></td>
10001000
<td>string</td>
1001-
<td><strong>Required</strong></td>
1002-
<td>The name of the file that starts your module program. This can be a compiled executable, a script, or an invocation of another program. If you are providing your module as a single file to the <code>upload</code> command, provide the path to that single file. If you are providing a directory containing your module to the <code>upload</code> command, provide the path to the entry point file contained within that directory.</td>
1001+
<td>Optional</td>
1002+
<td>The name of the file that starts your module program. This can be a compiled executable, a script, or an invocation of another program. If you are providing your module as a single file to the <code>upload</code> command, provide the path to that single file. If you are providing a directory containing your module to the <code>upload</code> command, provide the path to the entry point file contained within that directory. Required if you are shipping a model.</td>
10031003
</tr>
10041004
<tr>
10051005
<td><code>build</code></td>
@@ -1019,6 +1019,12 @@ Do not change the <code>module_id</code>.</p>
10191019
<td>Optional</td>
10201020
<td>Enables VS Code hover and autocomplete as you edit your module code. Gets auto-generated when you run <code>viam module generate</code> or <code>viam module create</code>. Has no impact on the module's function.</td>
10211021
</tr>
1022+
<tr>
1023+
<td><code>applications</code></td>
1024+
<td>array</td>
1025+
<td>Optional</td>
1026+
<td>Objects that provide information about the [Single Page Apps](/operate/reference/single-page-apps/) associated with the module.</td>
1027+
</tr>
10221028

10231029
</table>
10241030

‎docs/operate/reference/module-configuration.md

Lines changed: 2 additions & 60 deletions
Original file line numberDiff line numberDiff line change
@@ -179,7 +179,7 @@ The model is configured as a component with the name `myRealsenseCamera1`.
179179
```
180180

181181
{{% /tab %}}
182-
{{< /tabs %}}
182+
{{% /tabs %}}
183183

184184
{{% /tab %}}
185185
{{< /tabs >}}
@@ -227,64 +227,6 @@ For any version type other than **Patch (X.Y.Z)**, the module will upgrade as so
227227
If, for example, the module provides a motor component, and the motor is running, it will stop while the module upgrades.
228228
{{% /alert %}}
229229

230-
#### Module meta.json configuration
231-
232-
When creating a module, you'll need to configure a `meta.json` file that defines the module's properties. This file includes information about the module's ID, visibility, models, and other features.
233-
234-
Here's an example of a `meta.json` file:
235-
236-
```json
237-
{
238-
"module_id": "your-namespace:your-module",
239-
"visibility": "public",
240-
"url": "https://github.com/your-org/your-repo",
241-
"description": "Your module description",
242-
"models": [
243-
{
244-
"api": "rdk:component:base",
245-
"model": "your-namespace:your-module:your-model"
246-
}
247-
],
248-
"entrypoint": "run.sh",
249-
"first_run": "setup.sh"
250-
}
251-
```
252-
253-
For modules that include [Single Page Apps](/operate/reference/single-page-apps/), you can add the `applications` field:
254-
255-
```json
256-
{
257-
"module_id": "your-namespace:your-module",
258-
"visibility": "public",
259-
"url": "https://github.com/your-org/your-repo",
260-
"description": "Your module description",
261-
"models": [
262-
{
263-
"api": "rdk:component:base",
264-
"model": "your-namespace:your-module:your-model"
265-
}
266-
],
267-
"entrypoint": "run.sh",
268-
"applications": [
269-
{
270-
"name": "your-app-name",
271-
"type": "web",
272-
"entrypoint": "dist/index.html"
273-
}
274-
]
275-
}
276-
```
277-
278-
The `applications` field is an array of application objects with the following properties:
279-
280-
| Property | Type | Description |
281-
| --- | --- | --- |
282-
| `name` | string | The name of your application, which will be used in the URL (`name.publicnamespace.viamapps.com`) |
283-
| `type` | string | The type of application (currently only `"web"` is supported) |
284-
| `entrypoint` | string | The path to the HTML entry point for your application |
285-
286-
For more information about Single Page Apps, see the [Single Page Apps documentation](/operate/reference/single-page-apps/).
287-
288230
#### Environment variables
289231

290232
Each module has access to the following default environment variables.
@@ -348,4 +290,4 @@ To set the path to a program or library on a machine, you can set a system varia
348290
}
349291
```
350292

351-
{{% /expand%}}
293+
{{% /expand %}}

‎docs/operate/reference/naming-modules.md

Lines changed: 8 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -9,7 +9,7 @@ description: "Add support for a new component or service model by writing a modu
99
languages: ["c++"]
1010
viamresources: []
1111
platformarea: ["registry"]
12-
toc_hide: true
12+
toc_hide: false
1313
---
1414

1515
Each modular resource has two associated triplets: an API namespace triplet to indicate which [API](/dev/reference/apis/) it implements, and a model namespace triplet to uniquely identify the modular resource {{< glossary_tooltip term_id="model" text="model" >}}.
@@ -97,15 +97,17 @@ Determine the model name you want to use based on these requirements, then proce
9797

9898
## Valid application identifiers
9999

100-
If your module includes [Single Page Apps](/operate/reference/single-page-apps/), you'll need to define application names in your module's `meta.json` file. Application names have the following requirements:
100+
If your module includes a [single page app](/operate/reference/single-page-apps/), you need to define the application name in your module's `meta.json` file.
101+
Application names have the following requirements:
101102

102103
- Application names must be all-lowercase.
103-
- Application names may only use alphanumeric (`a-z` and `0-9`), hyphen (`-`), and underscore (`_`) characters.
104+
- Application names may only use alphanumeric (`a-z` and `0-9`) and hyphen (`-`) characters.
105+
- Application names may not start or end with a hyphen.
104106
- Application names must be unique within your organization's namespace.
105107

106-
The application name will be used in the URL for accessing your application:
108+
The URL for accessing your single page app will contain your application name:
107109

108-
```
110+
```txt
109111
https://app-name.your-public-namespace.viamapps.com
110112
```
111113

@@ -115,22 +117,6 @@ For example, if your organization namespace is `acme` and your application name
115117
https://dashboard.acme.viamapps.com
116118
```
117119

118-
Here's an example of how to define applications in your module's `meta.json` file:
119-
120-
```json
121-
{
122-
"module_id": "acme:my-module",
123-
"visibility": "public",
124-
"applications": [
125-
{
126-
"name": "dashboard",
127-
"type": "web",
128-
"entrypoint": "dist/index.html"
129-
}
130-
]
131-
}
132-
```
133-
134120
For more information about Single Page Apps, see the [Single Page Apps documentation](/operate/reference/single-page-apps/).
135121

136122
## Create a namespace for your organization
@@ -139,4 +125,4 @@ When uploading modules to the Viam Registry, you must set a unique namespace for
139125

140126
To create a new namespace for your organization, click on the org's **Settings** in the top right of the navigation bar, then click the **Set a public namespace** button.
141127
Enter a name or use the suggested name for your namespace, and then click **Set namespace**.
142-
A namespace may only contain letters, numbers, and the dash (`-`) character.
128+
A namespace may only contain letters, numbers, and the dash (`-`) character.

0 commit comments

Comments
 (0)