diff --git a/docs/_config.yml b/docs/_config.yml index e5f0f7d..c1034ad 100644 --- a/docs/_config.yml +++ b/docs/_config.yml @@ -22,7 +22,7 @@ permalink: pretty exclude: ["vendor/bundle", "node_modules/", "*.gemspec", "*.gem", "Gemfile", "Gemfile.lock", "package.json", "package-lock.json", "script/", "LICENSE.txt", "lib/", "bin/", "README.md", "Rakefile"] # Set a path/url to a logo that will be displayed instead of the title -#logo: "/assets/images/just-the-docs.png" +logo: "/assets/img/nuvladocs-logo.png" # Enable or disable the site search # Supports true (default) or false diff --git a/docs/_includes/api/group-response.md b/docs/_includes/api/group-response.md new file mode 100644 index 0000000..006790d --- /dev/null +++ b/docs/_includes/api/group-response.md @@ -0,0 +1,7 @@ +```json +{ + "status" : 201, + "message" : "group/dev created", + "resource-id" : "group/dev" +} +``` \ No newline at end of file diff --git a/docs/_includes/api/group.sh b/docs/_includes/api/group.sh new file mode 100644 index 0000000..d4839fc --- /dev/null +++ b/docs/_includes/api/group.sh @@ -0,0 +1,10 @@ +curl -XPOST https://nuvla.io/api/group -H 'content-type:application/json' -b cookies -d ''' + { + "template": { + "href": "group-template/generic", + "group-identifier": "dev", + "name": "Dev", + "description": "Development group" + } + } +''' diff --git a/docs/_includes/api/invite-response.md b/docs/_includes/api/invite-response.md new file mode 100644 index 0000000..c7d149c --- /dev/null +++ b/docs/_includes/api/invite-response.md @@ -0,0 +1,7 @@ +```json +{ + "status" : 200, + "message" : "successfully invited to group/dev", + "resource-id" : "group/dev" +} +``` \ No newline at end of file diff --git a/docs/_includes/api/invite.sh b/docs/_includes/api/invite.sh new file mode 100644 index 0000000..4044921 --- /dev/null +++ b/docs/_includes/api/invite.sh @@ -0,0 +1,3 @@ +curl -XPOST https://nuvla.io/api/group/dev/invite -H 'content-type:application/json' -b cookies -d ''' + {"username": "foobar@example.com"} +''' diff --git a/docs/_includes/api/login_apikey.sh b/docs/_includes/api/login-apikey.sh similarity index 88% rename from docs/_includes/api/login_apikey.sh rename to docs/_includes/api/login-apikey.sh index 4e44317..2fa8981 100644 --- a/docs/_includes/api/login_apikey.sh +++ b/docs/_includes/api/login-apikey.sh @@ -1,4 +1,4 @@ -curl -XPOST https://nuvla.io/api/session -H 'content-type:application/json' -b cookies -d ''' +curl -XPOST https://nuvla.io/api/session -H 'content-type:application/json' -c cookies -d ''' { "template": { "href": "session-template/api-key", diff --git a/docs/_includes/api/logout-response.md b/docs/_includes/api/logout-response.md new file mode 100644 index 0000000..f38acf5 --- /dev/null +++ b/docs/_includes/api/logout-response.md @@ -0,0 +1,7 @@ +```json +{ + "status" : 200, + "message" : "session/689df57a-b217-43eb-bf94-85a0ab638e2c deleted", + "resource-id" : "session/689df57a-b217-43eb-bf94-85a0ab638e2c" +} +``` \ No newline at end of file diff --git a/docs/_includes/api/session-get-peers-response.md b/docs/_includes/api/session-get-peers-response.md new file mode 100644 index 0000000..275ce21 --- /dev/null +++ b/docs/_includes/api/session-get-peers-response.md @@ -0,0 +1,7 @@ +```json +{ + "user/41d08575-77c2-45fb-9174-9b34bca81dc5" : "titi@other.example.com", + "user/55366c0f-d1d4-4c15-bf04-4dfb35c23ea2" : "tata@exmaple.com", + "user/d5c54236-94a3-49be-8013-128ead0b5836" : "toto@example.com +} +``` \ No newline at end of file diff --git a/docs/_includes/api/session-switch-group-response.md b/docs/_includes/api/session-switch-group-response.md new file mode 100644 index 0000000..d2ddc9e --- /dev/null +++ b/docs/_includes/api/session-switch-group-response.md @@ -0,0 +1,32 @@ +```json +{ + "active-claim" : "user/d5c54236-94a3-49be-8013-128ead0b5836", + "client-ip" : "172.17.0.1", + "expiry" : "2021-12-29T12:44:55.000Z", + "method" : "password", + "updated" : "2021-12-22T12:44:55.150Z", + "roles" : "group/nuvla-anon group/nuvla-user session/51179a6b-f9e2-4ae9-af16-a0955baf78c8 user/d5c54236-94a3-49be-8013-128ead0b5836", + "created" : "2021-12-20T13:52:08.789Z", + "template" : { + "href" : "session-template/password" + }, + "updated-by" : "user/d5c54236-94a3-49be-8013-128ead0b5836", + "created-by" : "group/nuvla-anon", + "id" : "session/51179a6b-f9e2-4ae9-af16-a0955baf78c8", + "resource-type" : "session", + "identifier" : "toto@example.com", + "acl" : { + "edit-data" : [ "group/nuvla-admin" ], + "owners" : [ "session/51179a6b-f9e2-4ae9-af16-a0955baf78c8" ], + "view-acl" : [ "group/nuvla-admin" ], + "delete" : [ "group/nuvla-admin" ], + "view-meta" : [ "group/nuvla-admin" ], + "edit-acl" : [ "group/nuvla-admin" ], + "view-data" : [ "group/nuvla-admin" ], + "manage" : [ "group/nuvla-admin" ], + "edit-meta" : [ "group/nuvla-admin" ] + }, + "groups" : "group/eo", + "user" : "user/d5c54236-94a3-49be-8013-128ead0b5836" +} +``` \ No newline at end of file diff --git a/docs/_includes/api/sessions-response.md b/docs/_includes/api/sessions-response.md new file mode 100644 index 0000000..6a8dc60 --- /dev/null +++ b/docs/_includes/api/sessions-response.md @@ -0,0 +1,53 @@ +```json +{ + "count" : 1, + "acl" : { + "query" : [ "group/nuvla-anon" ], + "add" : [ "group/nuvla-anon" ] + }, + "resource-type" : "session-collection", + "id" : "session", + "resources" : [ { + "client-ip" : "172.17.0.1", + "expiry" : "2021-12-29T12:57:54.000Z", + "method" : "password", + "updated" : "2021-12-22T12:57:55.002Z", + "roles" : "group/nuvla-anon group/nuvla-user user/d5c54236-94a3-49be-8013-128ead0b5836 session/8ed0f0cc-ea54-4e07-9e11-4ba68bb7113b", + "created" : "2021-12-22T12:57:55.002Z", + "template" : { + "href" : "session-template/password" + }, + "created-by" : "group/nuvla-anon", + "id" : "session/8ed0f0cc-ea54-4e07-9e11-4ba68bb7113b", + "resource-type" : "session", + "identifier" : "toto@example.com", + "acl" : { + "edit-data" : [ "group/nuvla-admin" ], + "owners" : [ "session/8ed0f0cc-ea54-4e07-9e11-4ba68bb7113b" ], + "view-acl" : [ "group/nuvla-admin" ], + "delete" : [ "group/nuvla-admin" ], + "view-meta" : [ "group/nuvla-admin" ], + "edit-acl" : [ "group/nuvla-admin" ], + "view-data" : [ "group/nuvla-admin" ], + "manage" : [ "group/nuvla-admin" ], + "edit-meta" : [ "group/nuvla-admin" ] + }, + "operations" : [ { + "rel" : "delete", + "href" : "session/8ed0f0cc-ea54-4e07-9e11-4ba68bb7113b" + }, { + "rel" : "get-peers", + "href" : "session/8ed0f0cc-ea54-4e07-9e11-4ba68bb7113b/get-peers" + }, { + "rel" : "switch-group", + "href" : "session/8ed0f0cc-ea54-4e07-9e11-4ba68bb7113b/switch-group" + } ], + "groups" : "group/eo", + "user" : "user/d5c54236-94a3-49be-8013-128ead0b5836" + } ], + "operations" : [ { + "rel" : "add", + "href" : "session" + } ] +} +``` \ No newline at end of file diff --git a/docs/_includes/api/switch-group.sh b/docs/_includes/api/switch-group.sh new file mode 100644 index 0000000..4656ee0 --- /dev/null +++ b/docs/_includes/api/switch-group.sh @@ -0,0 +1,3 @@ +curl -XPOST https://nuvla.io/api/session/51179a6b-f9e2-4ae9-af16-a0955baf78c8/switch-group -H 'content-type:application/json' -b cookies -c cookies -d ''' + {"claim": "group/x"} +''' diff --git a/docs/_includes/old_nuvlabox_warning.html b/docs/_includes/old_nuvlabox_warning.html index 6e29b49..8c82d02 100644 --- a/docs/_includes/old_nuvlabox_warning.html +++ b/docs/_includes/old_nuvlabox_warning.html @@ -1 +1 @@ -
Warning: this is not the documentation of the latest version of the NuvlaBox. Go here to access the latest version.
+
Warning: this is not the documentation of the latest version of the NuvlaBox. Go here to access the latest version.
diff --git a/docs/assets/img/nuvlabox-os-arch-detail.png b/docs/assets/img/nuvlabox-engine-arch-v1.png similarity index 100% rename from docs/assets/img/nuvlabox-os-arch-detail.png rename to docs/assets/img/nuvlabox-engine-arch-v1.png diff --git a/docs/assets/img/nuvlabox-engine-arch-v2.png b/docs/assets/img/nuvlabox-engine-arch-v2.png new file mode 100644 index 0000000..ca45a49 Binary files /dev/null and b/docs/assets/img/nuvlabox-engine-arch-v2.png differ diff --git a/docs/assets/img/nuvladocs-logo.png b/docs/assets/img/nuvladocs-logo.png new file mode 100644 index 0000000..633a58b Binary files /dev/null and b/docs/assets/img/nuvladocs-logo.png differ diff --git a/docs/nuvla/advanced-usage/api/cloud-entry-point.md b/docs/nuvla/advanced-usage/api/cloud-entry-point.md new file mode 100644 index 0000000..2aee167 --- /dev/null +++ b/docs/nuvla/advanced-usage/api/cloud-entry-point.md @@ -0,0 +1,29 @@ +--- +layout: page +title: Cloud Entry Point +nav_order: 2 +parent: API +has_children: false +--- + + +# Cloud Entry Point + +{% include request_snippet.md file='api/credential-amazonec2.sh' actions='GET' endpoint='/api/cloud-entry-point' maincolor='none' prefix='allowed:' lettercolor='black' %} + +The primary directory of resources is the Cloud Entry Point (CEP), which contains a list of named resource collections and their URLs (in the href field) relative to the baseURI value. The CEP also contains some other metadata. + +The endpoint is accessible for all registered and anonymous Nuvla users. + +--- + +_Examples_ + +## Get the cloud entry point + +{% include request_snippet.md file='api/cep.sh' actions='GET' endpoint='/api/cloud-entry-point' %} + +{% include code_snippet.md file='api/cep.sh' language='shell' %} + +{% include response_snippet.md file='api/cep-response.md' %} + diff --git a/docs/nuvla/advanced-usage/api/common-design.md b/docs/nuvla/advanced-usage/api/common-design.md new file mode 100644 index 0000000..dc69baf --- /dev/null +++ b/docs/nuvla/advanced-usage/api/common-design.md @@ -0,0 +1,197 @@ +--- +layout: page +title: Common Design +nav_order: 1 +parent: API +has_children: true +--- + +# Common Design + + +| Action | HTTP Method | Target | +| --- | --- | --- | +| Search | GET or PUT | resource collection | +| Add (create) | POST | resource collection | +| Bulk_delete | DELETE | resource collection | +| Bulk_action | PATCH | resource collection | +| Read | GET | resource | +| Edit (update) | PUT | resource | +| Delete | DELETE | resource | + +The Nuvla REST API endpoints are constructed with the following pattern: + +`/api////` + +where + + - `` is the Kebab Case name of the resource collection you're accessing, + - `` is the unique identifier for the specific resource you're managing, + - `` is a custom additional operation that might be allowed for that resource. + +On top of that, Nuvla's REST API also offers searching and querying through a parameter-based set of keywords: + +`/api/?param=value¶m=value...` + +where + +| Parameter | Description | Examples | +| --- | --- | --- | +| `filter` | Used to return only the set of resources that have an `attribute` matching a certain `value` | `?filter=name="my-resource"`

`?filter=people/gender!="male" and people/age>=21`

`?filter=application-name^="my-app-"` | +| `orderby` | To order the returned resources by the specified attribute | `?orderby=created:desc`

`?orderby=people/surname:asc` | +| `aggregation` | On top of the requested resources, it will also return on-the-fly aggregations based on the specified function. Available functions: `avg`, `max`, `min`, `sum`, `cardinality`, `terms`, `stats`, `extendedstats`, `percentiles`, `value_count`, `missing` | `?aggregation=avg:people/age` | +| `last` and `first` | Returns a range of resources by setting the first and last (1-based) query parameters | `?first=10&last=20` | +| `select` | Selects only certain attributes to be returned by the server. Avoiding sending information that will not be useful reduces the load on the network and the server | `?select=people/id` | + +Nuvla's API also provide custom operations for certain resources. These will be covered individually in the subsections below. + +Here are a few examples on how to construct the different HTTP requests: + + - **GET** all the resources of a specific type: + + `GET /api/` + + - **GET** a specific resource: + + `GET /api//` + + - **CREATE** a new resource: + + ``` + POST /api/ + HEADERS content-type:application/json + DATA + ``` + + - **EDIT** an existing resource: + + ``` + PUT /api// + HEADERS content-type:application/json + DATA + ``` + + In case you want to delete existing attributes , add the attributes names in `select` parameter + and do not send these attributes in `DATA` request body. + + - **DELETE** a resource: + + `DELETE /api//` + + - **QUERY** on resources: + + `GET /api/?param=value¶m=value` + + *or* + + ``` + PUT /api/ + HEADERS content-type:application/x-www-form-urlencoded + DATA
+ ``` + + - **BULK_DELETE** of resources: + + `DELETE /api/?param=value¶m=value` + + *or* + + ``` + DELETE /api/ + HEADERS content-type:application/x-www-form-urlencoded, bulk:true + DATA + ``` + + + - **BULK_ACTION** of resources: + + `PATCH /api//?param=value¶m=value` + + *or* + + ``` + PATCH /api/ + HEADERS content-type:application/x-www-form-urlencoded, bulk:true + DATA + ``` + + +## Resources + +All the Nuvla API calls to retrieve resources will return a JSON output, and you'll notice that all of these outputs contain a set of common attributes: + + - _**id**_: unique resource identifier, defined by the API server + - _**acl**_: fine-grained access-control list, used for managing authorization process for each resource and its collections of resources. If not defined by the user, the API server will default it based on the requesting user credentials. + - _**created**_: timestamp of creation, defined by the API server + - _**created-by**_: user id who created the resource (useful to trace user action when he has switched to a group) + - _**updated**_: timestamp of the last update, defined by the API server + - _**updated-by**_: user id who updated the resource (useful to trace user action when he has switched to a group) + - _**resource-type**_: type of resource, defined by the API server + - _**parent**_: reference to parent resource + - _**operations**_: set of available operations for that resource, defined by the API server + - _**name**_: optional user-friendly name for a specific resource, defined by the user or defaulted to `None` if undefined + - _**description**_: optional verbose description for a specific resource, defined by the user or defaulted to `None` if undefined + +Resources are managed individually, which means that the data schemas and available operations might defer from one to the other. These options are all explained and exemplified in the following sections. + + + +## Filter syntax + +Filter parameter is used to search, to run bulk delete and to run bulk operations on existing resources. + +It could be a simple query e.g. + +- `name='hello'` + +- `acl/delete = 'group/demo'` + +- `created<'2021-11-24T19:59:18Z'` + +- `version < 2` + +- `location intersects 'POINT(13.86 60.84)'` + +- `online!=true` + +- `description=null` + +- `tags='eo'` + +- `fulltext == 'Demo*'` + +or a complex one with parenthesis and combination of logical [`or`, `and`] expression. + +- `(created<'2021-11-24T19:59:18Z' or name^='hello') and location intersects 'POINT(13.86 60.84)'` + +### Supported Values in filter + +| Name | Description | Example | +|---|---| +| Text | Single or double quoted text | `"foobar"` `'foobar'` | +| Date | Single or double quoted UTC timestamp or `now` expression | `'2021-11-24T19:59:18Z'` `'now<30m'` `'now>30d'` | +| Numeric | Integer or Float numbers | `3.14159` `3`| +| Boolean | | `true` `false` | +| Geo-point | Single or double quoted [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) string | `'POLYGON((-49.2 19.6,65.7 19.6,65.7 67.4,-49.2 67.4,-49.2 19.6))'` | +| Geo-shape | Single or double quoted [WKT](https://en.wikipedia.org/wiki/Well-known_text_representation_of_geometry) string | `'POLYGON((-49.2 19.6,65.7 19.6,65.7 67.4,-49.2 67.4,-49.2 19.6))'` | +| Null | | `null` | + +Arrays are a special case and searches are executed on their content as if they was a simple value. +E.g. tags field is defined as an array of string. In case we would like to search if tags contains "eo", the filter would be `tags='eo'`. + +### Operations + +| Name | Symbol | Supported values | Details | +|---|---|---|---| +| Equal | = | Numeric, Date, Text, Boolean, null | | +| Not Equal | != | Numeric, Date, Text, Boolean, null | | +| Less than | < | Numeric, Date, Text | | +| Less than or Equal | <= | Numeric, Date, Text | | +| Greater than | > | Numeric, Date, Text | | +| Greater than or Equal | >= | Numeric, Date, Text | | +| Start with | ^= | Text | | +| Full-text search | == | Text | Works only on field `name` , `description` or `fulltext` which is a virtual field that regroup more or less the full resource words. | +| Intersects | intersects | Geo-Point, Geo-shape | Return all documents whose geo_shape or geo_point field intersects the query geometry. | +| Disjoint | disjoint | Geo-shape | Return all documents whose geo_shape or geo_point field has nothing in common with the query geometry. | +| Within | within | Geo-shape | Return all documents whose geo_shape or geo_point field is within the query geometry. Line geometries are not supported. | +| Contains | contains | Geo-shape | Return all documents whose geo_shape or geo_point field contains the query geometry. | diff --git a/docs/nuvla/advanced-usage/api/credential.md b/docs/nuvla/advanced-usage/api/credential.md new file mode 100644 index 0000000..57fc248 --- /dev/null +++ b/docs/nuvla/advanced-usage/api/credential.md @@ -0,0 +1,99 @@ +--- +layout: page +title: Credential +nav_order: 5 +parent: API +has_children: false +--- + +# credential + +{% include request_snippet.md file='api/credential-amazonec2.sh' actions='POST GET PUT DELETE' endpoint='/api/credential/uuid' maincolor='none' prefix='allowed:' lettercolor='black' %} + +The `credential` resource is used to save all the credentials necessary to +manage your Nuvla resources. From API keys, to Container Orchestration Engine +credentials, TLS certificates, etc. Most of the credentials are expected to be +provided by the user, some are generated by Nuvla (e.g. API key). + +--- +_Examples_ + +## Generate an API key credential + +{% include request_snippet.md file='api/credential-apikey.sh' actions='POST' endpoint='/api/credential' %} + +{% include code_snippet.md file='api/credential-apikey.sh' language='shell' %} + +{% include response_snippet.md file='api/credential-apikey-response.md' %} + + + +## Docker Swarm token credential + +{% include request_snippet.md file='api/credential-swarmtoken.sh' actions='POST' endpoint='/api/credential' %} + +{% include code_snippet.md file='api/credential-swarmtoken.sh' language='shell' %} + +{% include response_snippet.md file='api/credential-swarmtoken-response.md' %} + + + +## Infrastructure Service S3 credential + +{% include request_snippet.md file='api/credential-s3.sh' actions='POST' endpoint='/api/credential' %} + +{% include code_snippet.md file='api/credential-s3.sh' language='shell' %} + +{% include response_snippet.md file='api/credential-s3-response.md' %} + + +## Infrastructure Service Docker Swarm HTTP API credential + +{% include request_snippet.md file='api/credential-swarm.sh' actions='POST' endpoint='/api/credential' %} + +{% include code_snippet.md file='api/credential-swarm.sh' language='shell' %} + +{% include response_snippet.md file='api/credential-swarm-response.md' %} + + +## Infrastructure Service Kubernetes HTTP API credential + +{% include request_snippet.md file='api/credential-kubernetes.sh' actions='POST' endpoint='/api/credential' %} + +{% include code_snippet.md file='api/credential-kubernetes.sh' language='shell' %} + +{% include response_snippet.md file='api/credential-kubernetes-response.md' %} diff --git a/docs/nuvla/advanced-usage/api/deployment.md b/docs/nuvla/advanced-usage/api/deployment.md new file mode 100644 index 0000000..4fc713b --- /dev/null +++ b/docs/nuvla/advanced-usage/api/deployment.md @@ -0,0 +1,24 @@ +--- +layout: page +title: Deployment +nav_order: 6 +parent: API +has_children: false +--- + +# deployment + +{% include request_snippet.md file='api/credential-amazonec2.sh' actions='POST GET PUT DELETE' endpoint='/api/deployment/uuid' maincolor='none' prefix='allowed:' lettercolor='black' %} + +The `deployment` resource allows you to deploy an instance of a `module`. + +--- +_Examples_ + +## Start/Stop an application + +{% include request_snippet.md file='api/deployment.sh' actions='POST PUT GET' endpoint='/api/deployment' %} + +{% include code_snippet.md file='api/deployment.sh' language='shell' %} + +{% include response_snippet.md file='api/deployment-response.md' %} diff --git a/docs/nuvla/advanced-usage/api/group.md b/docs/nuvla/advanced-usage/api/group.md new file mode 100644 index 0000000..3067605 --- /dev/null +++ b/docs/nuvla/advanced-usage/api/group.md @@ -0,0 +1,52 @@ +--- +layout: page +title: Group +nav_order: 4 +parent: API +has_children: false +--- + + +# Group + +{% include request_snippet.md actions='POST GET DELETE' endpoint='/api/group/uuid' maincolor='none' prefix='allowed:' lettercolor='black' %} + +The `group` resource allows you to: + + - create new groups + - invite users to join a group + +Group is a resource that allow users to have a common account/view on Nuvla on created resources (see `session` switch-group operation) or shared ones (via ACL). + +## Attributes + +**NOTE:** only common attributes for this resource + +--- + +## Examples + +**NOTE:** for later usage, we store the authenticated session in a file called _cookies_ + +Group is a templated resource. To create/add a new group, you have to refer to a +group-template resource. + +{% include request_snippet.md actions='GET' endpoint='/api/group-template' %} + +## Create a group + +{% include request_snippet.md actions='POST' endpoint='/api/group' %} + +{% include code_snippet.md file='api/group.sh' language='shell' %} + +{% include response_snippet.md file='api/group-response.md' %} + +## Invite operation + +You can invite a user to join a group by email doing as follow. + +{% include request_snippet.md actions='POST' endpoint='/api/group/dev/invite' %} + +{% include code_snippet.md file='api/invite.sh' language='shell' %} + +{% include response_snippet.md file='api/invite-response.md' %} diff --git a/docs/nuvla/advanced-usage/api/index.md b/docs/nuvla/advanced-usage/api/index.md new file mode 100644 index 0000000..883b263 --- /dev/null +++ b/docs/nuvla/advanced-usage/api/index.md @@ -0,0 +1,14 @@ +--- +layout: page +title: API +parent: Advanced Usage +nav_order: 1 +has_children: true +--- + +# REST API + +Nuvla provides a uniform and extensible HTTP-based RESTful API, for the management of Nuvla resources. A Nuvla resource can be anything you can perform an action on, through Nuvla, like your own user profile, a Nuvla application, credentials, etc. + +Users have at their disposal all the usual CRUD (Create, Read, Update, Delete) operations, plus Searching, Querying, Bulk delete and Bulk actions. + diff --git a/docs/nuvla/advanced-usage/api/infrastructure-service-group.md b/docs/nuvla/advanced-usage/api/infrastructure-service-group.md new file mode 100644 index 0000000..b6b62f6 --- /dev/null +++ b/docs/nuvla/advanced-usage/api/infrastructure-service-group.md @@ -0,0 +1,28 @@ +--- +layout: page +title: Infrastructure Service Group +nav_order: 5 +parent: API +has_children: false +--- + +# infrastructure-service-group + +{% include request_snippet.md file='api/credential-amazonec2.sh' actions='POST GET DELETE' endpoint='/api/infrastructure-service-group/uuid' maincolor='none' prefix='allowed:' lettercolor='black' %} + +The `infrastructure-service-group` resource is a logical container for your infrastructure-service and respective credential and data resources. + + +--- +_Examples_ + + +## Create an infrastructure-service-group + +{% include request_snippet.md file='api/infrastructure-service-group.sh' actions='POST' endpoint='/api/infrastructure-service-group' %} + +{% include code_snippet.md file='api/infrastructure-service-group.sh' language='shell' %} + +{% include response_snippet.md file='api/infrastructure-service-group-response.md' %} + + diff --git a/docs/nuvla/advanced-usage/api/infrastructure-service.md b/docs/nuvla/advanced-usage/api/infrastructure-service.md new file mode 100644 index 0000000..a1aeba5 --- /dev/null +++ b/docs/nuvla/advanced-usage/api/infrastructure-service.md @@ -0,0 +1,74 @@ +--- +layout: page +title: Infrastructure Service +nav_order: 4 +parent: API +has_children: false +--- + +# infrastructure-service + +{% include request_snippet.md file='api/credential-amazonec2.sh' actions='POST GET PUT DELETE' endpoint='/api/infrastructure-service/uuid' maincolor='none' prefix='allowed:' lettercolor='black' %} + +The `infrastructure-service` resource represents any manageable service with a working endpoint. This resource is templated, which means, like `session` and `credential`, you can also create infrastructure-services of different types. + +--- +_Examples_ + + +## Create Docker Swarm infrastructure service + +{% include request_snippet.md file='api/infrastructure-service.sh' actions='POST' endpoint='/api/infrastructure-service-swarm' %} + +{% include code_snippet.md file='api/infrastructure-service-swarm.sh' language='shell' %} + +{% include response_snippet.md file='api/infrastructure-service-swarm-response.md' %} + + +## Create Kubernetes infrastructure service + +{% include request_snippet.md file='api/infrastructure-service-k8s.sh' actions='POST' endpoint='/api/infrastructure-service' %} + +{% include code_snippet.md file='api/infrastructure-service-k8s.sh' language='shell' %} + +{% include response_snippet.md file='api/infrastructure-service-k8s-response.md' %} + + +## Create S3 infrastructure service + +{% include request_snippet.md file='api/infrastructure-service-s3.sh' actions='POST' endpoint='/api/infrastructure-service' %} + +{% include code_snippet.md file='api/infrastructure-service-s3.sh' language='shell' %} + +{% include response_snippet.md file='api/infrastructure-service-s3-response.md' %} + + +## Create generic infrastructure service + +{% include request_snippet.md file='api/infrastructure-service.sh' actions='POST' endpoint='/api/infrastructure-service' %} + +{% include code_snippet.md file='api/infrastructure-service.sh' language='shell' %} + +{% include response_snippet.md file='api/infrastructure-service-response.md' %} + + +# infrastructure-service-group + +{% include request_snippet.md file='api/credential-amazonec2.sh' actions='POST GET DELETE' endpoint='/api/infrastructure-service-group/uuid' maincolor='none' prefix='allowed:' lettercolor='black' %} + +The `infrastructure-service-group` resource is a logical container for your infrastructure-service and respective credential and data resources. + + +--- +_Examples_ + + +## Create an infrastructure-service-group + +{% include request_snippet.md file='api/infrastructure-service-group.sh' actions='POST' endpoint='/api/infrastructure-service-group' %} + +{% include code_snippet.md file='api/infrastructure-service-group.sh' language='shell' %} + +{% include response_snippet.md file='api/infrastructure-service-group-response.md' %} + + diff --git a/docs/nuvla/advanced-usage/api/session.md b/docs/nuvla/advanced-usage/api/session.md new file mode 100644 index 0000000..1a378d0 --- /dev/null +++ b/docs/nuvla/advanced-usage/api/session.md @@ -0,0 +1,129 @@ +--- +layout: page +title: Session +nav_order: 3 +parent: API +has_children: false +--- + + +# Session + +{% include request_snippet.md actions='POST GET DELETE' endpoint='/api/session/uuid' maincolor='none' prefix='allowed:' lettercolor='black' %} + +The `session` resource allows you to: + + - use your credentials for authenticating with Nuvla + - Delete session (logout) + - switch group (act for a group) + - get your peers (users that share some groups with you) + +Users (clients) authenticate with the Nuvla server by referencing a `session-template` resource (to +identify the authentication method), providing values for the associated parameters, and then +creating a `session` resource via the templated 'add' pattern. + +A successful authentication attempt will return a token (as an HTTP cookie) that must be used in +subsequent interactions with the Nuvla server. + +The detailed process consists of the following steps: + +1. Browse the `session-template` resources to find the authentication method + that you want to use. Unless you have a browser-based client, you will + probably want to use either 'password' (username and password) or 'api-key' + (API key and secret). **Use of API keys and secrets is preferred over the + username and password for programmatic access.** + +2. Prepare a 'create' JSON document that references the `session-template` you + have chosen and provides the corresponding parameters (e.g. username and + password for 'password'). + +3. Post the 'create' document to the `session` collection URL. + +4. On a successful authentication request, a token will be returned allowing + access to the Nuvla resources as the authenticated user. **For convenience, + this token is returned as an HTTP cookie.** + +The authentication token (cookie) must be used in all subsequent requests to +the Nuvla server. The token (cookie) has a **limited lifetime** and you +must re-authenticate with the server when the token expires. + +## Attributes + + - _**active-claim**_: group or user id that you are claiming + - _**client-ip**_: your client ip as seen from nuvla server + - _**expiry**_: expiry date of your session + - _**method**_: method used to sign-in + - _**roles**_: string space separated of current roles applied to retrieve resources based on ACL + - _**identifier**_: username used to sign-in + - _**groups**_: string space separated groups + +--- + +## Examples + +**NOTE:** for later usage, we store the authenticated session in a file called _cookies_ + +Session is a templated resource. To create/add a new session, you have to refer to a +session-template resource. + +{% include request_snippet.md actions='GET' endpoint='/api/session-template' %} + +## Login with username and password + +{% include request_snippet.md file='api/session.sh' actions='POST' endpoint='/api/session' %} + +{% include code_snippet.md file='api/login.sh' language='shell' %} + +{% include response_snippet.md file='api/login-response.md' %} + + +## Login with API keys + +{% include request_snippet.md file='api/session.sh' actions='POST' endpoint='/api/session' %} + +{% include code_snippet.md file='api/login-apikey.sh' language='shell' %} + +{% include response_snippet.md file='api/login-response.md' %} + + +## Search session + +The search feature of `session` resources will only return the +`session` resource associated with your current session (or none at all if your +are not authenticated). This can be used to determine if you have an active +session and your associated identity and rights (e.g. groups). + + +{% include request_snippet.md actions='GET' endpoint='/api/session' %} + +{% include response_snippet.md file='api/sessions-response.md' %} + + +## Switch group operation + +When a user is in a group, he can ask to change his session to claim the group access. + + +{% include request_snippet.md actions='POST' endpoint='/api/session/689df57a-b217-43eb-bf94-85a0ab638e2c/switch-group' %} + +{% include code_snippet.md file='api/switch-group.sh' language='shell' %} + +{% include response_snippet.md file='api/session-switch-group-response.md' %} + + +## Get peers operation + +Get users that share some groups with you. + + +{% include request_snippet.md actions='POST' endpoint='/api/session/689df57a-b217-43eb-bf94-85a0ab638e2c/get-peers' %} + +{% include response_snippet.md file='api/session-get-peers-response.md' %} + + + +## Logout + +{% include request_snippet.md actions='DELETE' endpoint='/api/session/689df57a-b217-43eb-bf94-85a0ab638e2c' %} + +{% include response_snippet.md file='api/logout-response.md' %} diff --git a/docs/nuvla/advanced-usage/api/to-be-deleted.md b/docs/nuvla/advanced-usage/api/to-be-deleted.md new file mode 100644 index 0000000..8765c41 --- /dev/null +++ b/docs/nuvla/advanced-usage/api/to-be-deleted.md @@ -0,0 +1,46 @@ +--- +layout: page +title: To Be deleted +nav_order: 100 +parent: API +has_children: false +--- + + +## evidence-record + +{% include request_snippet.md file='api/credential-amazonec2.sh' actions='POST GET PUT DELETE' endpoint='/api/evidence-record/uuid' maincolor='none' prefix='allowed:' lettercolor='black' %} + +The `evidence-record` resource allows you to create and manage audit evidence records that can afterwards help you keep track of your infrastructures' compliance to certain standards and certification schemas. + +--- +_Examples_ + +### Create an evidence record + +{% include request_snippet.md file='api/evidence-record.sh' actions='POST' endpoint='/api/evidencerecord' %} + +{% include code_snippet.md file='api/evidencerecord.sh' language='shell' %} + +{% include response_snippet.md file='api/evidencerecord-response.md' %} + + + +## voucher + +{% include request_snippet.md file='api/credential-amazonec2.sh' actions='POST GET PUT DELETE' endpoint='/api/voucher/uuid' maincolor='none' prefix='allowed:' lettercolor='black' %} + +The `voucher` resource let's you create and manage digital vouchers, associated with any digital service provider, for better tracking and accounting of voucher consumption. + + +--- +_Examples_ + + +### Create a new voucher + +{% include request_snippet.md file='api/voucher.sh' actions='POST' endpoint='/api/voucher' %} + +{% include code_snippet.md file='api/voucher.sh' language='shell' %} + +{% include response_snippet.md file='api/voucher-response.md' %} diff --git a/docs/nuvla/advanced-usage/api/user.md b/docs/nuvla/advanced-usage/api/user.md new file mode 100644 index 0000000..ce762bb --- /dev/null +++ b/docs/nuvla/advanced-usage/api/user.md @@ -0,0 +1,35 @@ +--- +layout: page +title: User +nav_order: 4 +parent: API +has_children: false +--- + + +# user + +{% include request_snippet.md file='api/credential-amazonec2.sh' actions='POST GET PUT DELETE' endpoint='/api/user/uuid' maincolor='none' prefix='allowed:' lettercolor='black' %} + +The `user` resource allows you to create a new user account on Nuvla. + +--- +_Examples_ + + +## Create a user with an email and a password + +{% include request_snippet.md file='api/user_email_password.sh' actions='POST' endpoint='/api/user' %} + +{% include code_snippet.md file='api/user_email_password.sh' language='shell' %} + +{% include response_snippet.md file='api/user-email-password-response.md' %} + +Password must contain at least one uppercase character, one lowercase character, +one digit, one special character, and at least 8 characters in total. + +The creation of a user with `email-password` template does not require a session. + +The user will receive an email with a callback that he have to follow to activate his account. +After following the link, the state attribute of user document will transit from NEW to ACTIVE. + diff --git a/docs/nuvla/advanced-usage.md b/docs/nuvla/advanced-usage/index.md similarity index 100% rename from docs/nuvla/advanced-usage.md rename to docs/nuvla/advanced-usage/index.md diff --git a/docs/nuvla/installation/advanced-installation.md b/docs/nuvla/advanced-usage/installation/advanced-installation.md similarity index 99% rename from docs/nuvla/installation/advanced-installation.md rename to docs/nuvla/advanced-usage/installation/advanced-installation.md index 941acce..e43fd46 100644 --- a/docs/nuvla/installation/advanced-installation.md +++ b/docs/nuvla/advanced-usage/installation/advanced-installation.md @@ -4,7 +4,6 @@ title: Production Installation nav_order: 2 parent: Installation permalink: /nuvla/installation/production -grand_parent: Nuvla --- diff --git a/docs/nuvla/installation/example-apps.md b/docs/nuvla/advanced-usage/installation/example-apps.md similarity index 89% rename from docs/nuvla/installation/example-apps.md rename to docs/nuvla/advanced-usage/installation/example-apps.md index 6f7f44f..276cb19 100644 --- a/docs/nuvla/installation/example-apps.md +++ b/docs/nuvla/advanced-usage/installation/example-apps.md @@ -3,7 +3,6 @@ layout: page title: Example Apps nav_order: 3 parent: Installation -grand_parent: Nuvla permalink: /nuvla/installation/example-apps --- diff --git a/docs/nuvla/installation.md b/docs/nuvla/advanced-usage/installation/index.md similarity index 93% rename from docs/nuvla/installation.md rename to docs/nuvla/advanced-usage/installation/index.md index 5f72886..2534fd4 100644 --- a/docs/nuvla/installation.md +++ b/docs/nuvla/advanced-usage/installation/index.md @@ -1,12 +1,12 @@ --- layout: page title: Installation -nav_order: 1 -parent: Nuvla +nav_order: 12 +parent: Advanced Usage has_children: true -permalink: /nuvla/installation --- + The following diagram shows the main blocks of the Nuvla Architecture. ![Nuvla Architecture](/assets/img/architecture.png) diff --git a/docs/nuvla/installation/operation-maintenance.md b/docs/nuvla/advanced-usage/installation/operation-maintenance.md similarity index 99% rename from docs/nuvla/installation/operation-maintenance.md rename to docs/nuvla/advanced-usage/installation/operation-maintenance.md index 07cc089..1e882e9 100644 --- a/docs/nuvla/installation/operation-maintenance.md +++ b/docs/nuvla/advanced-usage/installation/operation-maintenance.md @@ -3,7 +3,6 @@ layout: page title: Operate & Maintain nav_order: 4 parent: Installation -grand_parent: Nuvla permalink: /nuvla/installation/operation-maintenance --- diff --git a/docs/nuvla/installation/quickstart.md b/docs/nuvla/advanced-usage/installation/quickstart.md similarity index 99% rename from docs/nuvla/installation/quickstart.md rename to docs/nuvla/advanced-usage/installation/quickstart.md index 249d9d5..ad935c9 100644 --- a/docs/nuvla/installation/quickstart.md +++ b/docs/nuvla/advanced-usage/installation/quickstart.md @@ -3,7 +3,6 @@ layout: page title: Quickstart nav_order: 1 parent: Installation -grand_parent: Nuvla --- Here's a simple guide to quickly install Nuvla for evaluation purposes. So if you're looking for quickly trying out Nuvla, you're at the right place. However, if you're looking for a robust production level installation, you probably want to look at [the production deployment page](/nuvla/installation/production). diff --git a/docs/nuvla/advanced-usage/manage-data.md b/docs/nuvla/advanced-usage/manage-data.md index 492a3d5..1983757 100644 --- a/docs/nuvla/advanced-usage/manage-data.md +++ b/docs/nuvla/advanced-usage/manage-data.md @@ -3,7 +3,7 @@ layout: page title: Manage Data parent: Advanced Usage grand_parent: Nuvla -nav_order: 1 +nav_order: 4 permalink: /nuvla/advanced-usage/manage-data --- diff --git a/docs/nuvla/nuvla.md b/docs/nuvla/index.md similarity index 100% rename from docs/nuvla/nuvla.md rename to docs/nuvla/index.md diff --git a/docs/nuvla/user-guide/api.md b/docs/nuvla/user-guide/api.md deleted file mode 100644 index a9df300..0000000 --- a/docs/nuvla/user-guide/api.md +++ /dev/null @@ -1,437 +0,0 @@ ---- -layout: page -title: API -parent: User Guide -grand_parent: Nuvla -nav_order: 12 -permalink: /nuvla/api ---- - -- [REST API](#rest-api) - * [Understanding the Nuvla REST API output format](#understanding-the-nuvla-rest-api-output-format) - * [API Syntax](#api-syntax) - * [Resources](#resources) - + [cloud-entry-point](#cloud-entry-point) - + [Get the cloud entry point](#get-the-cloud-entry-point) - + [credential](#credential) - + [API key credential](#generate-an-api-key-credential) - + [Docker Swarm token credential](#docker-swarm-token-credential) - + [Infrastructure Service S3 credential](#infrastructure-service-s3-credential) - + [Infrastructure Service Docker Swarm HTTP API credential](#infrastructure-service-docker-swarm-http-api-credential) - + [Infrastructure Service Kubernetes HTTP API credential](#infrastructure-service-kubernetes-http-api-credential) - + [deployment](#deployment) - + [Start/Stop an application](#startstop-an-application) - + [evidence-record](#evidence-record) - + [Create an evidence record](#create-an-evidence-record) - + [infrastructure-service](#infrastructure-service) - + [Create Docker Swarm infrastructure service](#create-docker-swarm-infrastructure-service) - + [Create Kubernetes infrastructure service](#create-kubernetes-infrastructure-service) - + [Create S3 infrastructure service](#create-s3-infrastructure-service) - + [Create generic infrastructure service](#create-generic-infrastructure-service) - + [infrastructure-service-group](#infrastructure-service-group) - + [Create an infrastructure-service-group](#create-an-infrastructure-service-group) - + [session](#session) - + [Login with username and password](#login-with-username-and-password) - + [Login with API keys](#login-with-api-keys) - + [user](#user) - + [Create a user with an email and a password](#create-a-user-with-an-email-and-a-password) - + [voucher](#voucher) - + [Create a new voucher](#create-a-new-voucher) -- [Python API](#python-api) - - -# REST API - -Nuvla provides a uniform and extensible HTTP-based RESTful API, for the management of Nuvla resources. A Nuvla resource can be anything you can perform an action on, through Nuvla, like your own user profile, a Nuvla application, credentials, etc. - -Users have at their disposal all the usual CRUD (Create, Read, Update, Delete) operations, plus Searching and Querying. - - -| Action | HTTP Method | Target | -| --- | --- | --- | -| Search | GET or PUT | resource collection | -| Add (create) | POST | resource collection | -| Read | GET | resource | -| Edit (update) | PUT | resource | -| Delete | DELETE | resource | - -Finally, due to its versatility, Nuvla's API also provide custom operations for certain resources. These will be covered individually in the subsections below. - -Here are a few examples on how to construct the different HTTP requests: - - - **GET** all the resources of a specific type: - - `GET /api/` - - - **GET** a specific resource: - - `GET /api//` - - - **CREATE** a new resource: - - ``` -POST /api/ - HEADERS Content-type:application/json - DATA - ``` - - - **EDIT** an existing resource: - - ``` -PUT /api// - HEADERS Content-type:application/json - DATA - ``` - - - **DELETE** a resource: - - `DELETE /api//` - - - -## Understanding the Nuvla REST API output format - -All the Nuvla API calls will return a JSON output, and you'll notice that all of these outputs contain a set of common attributes: - - - _**id**_: unique resource identifier, defined by the API server - - _**acl**_: fine-grained access-control list, used for managing authorization process for each resource and its collections of resources. If not defined by the user, the API server will default it based on the requesting user credentials. - - _**created**_: timestamp of creation, defined by the API server - - _**updated**_: timestamp of the last update, defined by the API server - - _**resource-type**_: type of resource, defined by the API server - - _**operations**_: set of available operations for that resource, defined by the API server - - _**name**_: optional user-friendly name for a specific resource, defined by the user or defaulted to `None` if undefined - - _**description**_: optional verbose description for a specific resource, defined by the user or defaulted to `None` if undefined - - -## API Syntax - -The Nuvla REST API endpoints are constructed with the following pattern: - -`/api////` - -where - - - `` is the Kebab Case name of the resource collection you're accessing, - - `` is the unique identifier for the specific resource you're managing, - - `` is a custom additional operation that might be allowed for that resource. - -On top of that, Nuvla's REST API also offers searching and querying through a parameter-based set of keywords: - -`/api/?param=value¶m=value...` - -where - -| Parameter | Description | Examples | -| --- | --- | --- | -| `filter` | Used to return only the set of resources that have an `attribute` matching a certain `value` | `?filter=name="my-resource"`

`?filter=people/gender!="male" and people/age>=21`

`?filter=application-name^="my-app-"` | -| `orderby` | To order the returned resources by the specified attribute | `?orderby=created:desc`

`?orderby=people/surname:asc` | -| `aggregation` | On top of the requested resources, it will also return on-the-fly aggregations based on the specified function. Available functions: `avg`, `max`, `min`, `sum`, `cardinality`, `terms`, `stats`, `extendedstats`, `percentiles`, `value_count`, `missing` | `?aggregation=avg:people/age` | -| `last` and `first` | Returns a range of resources by setting the first and last (1-based) query parameters | `?first=10&last=20` | -| `select` | Selects only certain attributes to be returned by the server. Avoiding sending information that will not be useful reduces the load on the network and the server | `?select=people/id` | - - -## Resources - -Resources are managed individually, which means that the data schemas and available operations might defer from one to the other. These options are all explained and exemplified in the following sections. - - -### cloud-entry-point - -{% include request_snippet.md file='api/credential-amazonec2.sh' actions='GET' endpoint='/api/cloud-entry-point' maincolor='none' prefix='allowed:' lettercolor='black' %} - -The primary directory of resources is the Cloud Entry Point (CEP), which contains a list of named resource collections and their URLs (in the href field) relative to the baseURI value. The CEP also contains some other metadata. - -The endpoint is accessible for all registered and anonymous Nuvla users. - ---- - -_Examples_ - -##### Get the cloud entry point - -{% include request_snippet.md file='api/cep.sh' actions='GET' endpoint='/api/cloud-entry-point' %} - -{% include code_snippet.md file='api/cep.sh' language='shell' %} - -{% include response_snippet.md file='api/cep-response.md' %} - - -### credential - -{% include request_snippet.md file='api/credential-amazonec2.sh' actions='POST GET PUT DELETE' endpoint='/api/credential/uuid' maincolor='none' prefix='allowed:' lettercolor='black' %} - -The `credential` resource is used to save all the credentials necessary to -manage your Nuvla resources. From API keys, to Container Orchestration Engine -credentials, TLS certificates, etc. Most of the credentials are expected to be -provided by the user, some are generated by Nuvla (e.g. API key). - ---- -_Examples_ - -##### Generate an API key credential - -{% include request_snippet.md file='api/credential-apikey.sh' actions='POST' endpoint='/api/credential' %} - -{% include code_snippet.md file='api/credential-apikey.sh' language='shell' %} - -{% include response_snippet.md file='api/credential-apikey-response.md' %} - - - -##### Docker Swarm token credential - -{% include request_snippet.md file='api/credential-swarmtoken.sh' actions='POST' endpoint='/api/credential' %} - -{% include code_snippet.md file='api/credential-swarmtoken.sh' language='shell' %} - -{% include response_snippet.md file='api/credential-swarmtoken-response.md' %} - - -##### Infrastructure Service S3 credential - -{% include request_snippet.md file='api/credential-s3.sh' actions='POST' endpoint='/api/credential' %} - -{% include code_snippet.md file='api/credential-s3.sh' language='shell' %} - -{% include response_snippet.md file='api/credential-s3-response.md' %} - - -##### Infrastructure Service Docker Swarm HTTP API credential - -{% include request_snippet.md file='api/credential-swarm.sh' actions='POST' endpoint='/api/credential' %} - -{% include code_snippet.md file='api/credential-swarm.sh' language='shell' %} - -{% include response_snippet.md file='api/credential-swarm-response.md' %} - - -##### Infrastructure Service Kubernetes HTTP API credential - -{% include request_snippet.md file='api/credential-kubernetes.sh' actions='POST' endpoint='/api/credential' %} - -{% include code_snippet.md file='api/credential-kubernetes.sh' language='shell' %} - -{% include response_snippet.md file='api/credential-kubernetes-response.md' %} - - -### deployment - -{% include request_snippet.md file='api/credential-amazonec2.sh' actions='POST GET PUT DELETE' endpoint='/api/deployment/uuid' maincolor='none' prefix='allowed:' lettercolor='black' %} - -The `deployment` resource allows you to deploy an instance of a `module`. - ---- -_Examples_ - -##### Start/Stop an application - -{% include request_snippet.md file='api/deployment.sh' actions='POST PUT GET' endpoint='/api/deployment' %} - -{% include code_snippet.md file='api/deployment.sh' language='shell' %} - -{% include response_snippet.md file='api/deployment-response.md' %} - - - - -### evidence-record - -{% include request_snippet.md file='api/credential-amazonec2.sh' actions='POST GET PUT DELETE' endpoint='/api/evidence-record/uuid' maincolor='none' prefix='allowed:' lettercolor='black' %} - -The `evidence-record` resource allows you to create and manage audit evidence records that can afterwards help you keep track of your infrastructures' compliance to certain standards and certification schemas. - ---- -_Examples_ - -##### Create an evidence record - -{% include request_snippet.md file='api/evidence-record.sh' actions='POST' endpoint='/api/evidencerecord' %} - -{% include code_snippet.md file='api/evidencerecord.sh' language='shell' %} - -{% include response_snippet.md file='api/evidencerecord-response.md' %} - - - - -### infrastructure-service - -{% include request_snippet.md file='api/credential-amazonec2.sh' actions='POST GET PUT DELETE' endpoint='/api/infrastructure-service/uuid' maincolor='none' prefix='allowed:' lettercolor='black' %} - -The `infrastructure-service` resource represents any manageable service with a working endpoint. This resource is templated, which means, like `session` and `credential`, you can also create infrastructure-services of different types. - ---- -_Examples_ - - -##### Create Docker Swarm infrastructure service - -{% include request_snippet.md file='api/infrastructure-service.sh' actions='POST' endpoint='/api/infrastructure-service-swarm' %} - -{% include code_snippet.md file='api/infrastructure-service-swarm.sh' language='shell' %} - -{% include response_snippet.md file='api/infrastructure-service-swarm-response.md' %} - - -##### Create Kubernetes infrastructure service - -{% include request_snippet.md file='api/infrastructure-service-k8s.sh' actions='POST' endpoint='/api/infrastructure-service' %} - -{% include code_snippet.md file='api/infrastructure-service-k8s.sh' language='shell' %} - -{% include response_snippet.md file='api/infrastructure-service-k8s-response.md' %} - - -##### Create S3 infrastructure service - -{% include request_snippet.md file='api/infrastructure-service-s3.sh' actions='POST' endpoint='/api/infrastructure-service' %} - -{% include code_snippet.md file='api/infrastructure-service-s3.sh' language='shell' %} - -{% include response_snippet.md file='api/infrastructure-service-s3-response.md' %} - - -##### Create generic infrastructure service - -{% include request_snippet.md file='api/infrastructure-service.sh' actions='POST' endpoint='/api/infrastructure-service' %} - -{% include code_snippet.md file='api/infrastructure-service.sh' language='shell' %} - -{% include response_snippet.md file='api/infrastructure-service-response.md' %} - - -### infrastructure-service-group - -{% include request_snippet.md file='api/credential-amazonec2.sh' actions='POST GET DELETE' endpoint='/api/infrastructure-service-group/uuid' maincolor='none' prefix='allowed:' lettercolor='black' %} - -The `infrastructure-service-group` resource is a logical container for your infrastructure-service and respective credential and data resources. - - ---- -_Examples_ - - -##### Create an infrastructure-service-group - -{% include request_snippet.md file='api/infrastructure-service-group.sh' actions='POST' endpoint='/api/infrastructure-service-group' %} - -{% include code_snippet.md file='api/infrastructure-service-group.sh' language='shell' %} - -{% include response_snippet.md file='api/infrastructure-service-group-response.md' %} - - - - -### session - -{% include request_snippet.md file='api/credential-amazonec2.sh' actions='POST GET DELETE' endpoint='/api/session/uuid' maincolor='none' prefix='allowed:' lettercolor='black' %} - -The `session` resource allows you to use your credentials for authenticating with Nuvla. - -**NOTE:** for later usage, we store the authenticated session in a file called _cookies_ - ---- -_Examples_ - - -##### Login with username and password - -{% include request_snippet.md file='api/session.sh' actions='POST' endpoint='/api/session' %} - -{% include code_snippet.md file='api/login.sh' language='shell' %} - -{% include response_snippet.md file='api/login-response.md' %} - - -##### Login with API keys - -{% include request_snippet.md file='api/session.sh' actions='POST' endpoint='/api/session' %} - -{% include code_snippet.md file='api/login_apikey.sh' language='shell' %} - -{% include response_snippet.md file='api/login-response.md' %} - -### user - -{% include request_snippet.md file='api/credential-amazonec2.sh' actions='POST GET PUT DELETE' endpoint='/api/user/uuid' maincolor='none' prefix='allowed:' lettercolor='black' %} - -The `user` resource allows you to create a new user account on Nuvla. - ---- -_Examples_ - - -##### Create a user with an email and a password - -{% include request_snippet.md file='api/user_email_password.sh' actions='POST' endpoint='/api/user' %} - -{% include code_snippet.md file='api/user_email_password.sh' language='shell' %} - -{% include response_snippet.md file='api/user-email-password-response.md' %} - -Password must contain at least one uppercase character, one lowercase character, -one digit, one special character, and at least 8 characters in total. - -The creation of a user with `email-password` template does not require a session. - -The user will receive an email with a callback that he have to follow to activate his account. -After following the link, the state attribute of user document will transit from NEW to ACTIVE. - - -### voucher - -{% include request_snippet.md file='api/credential-amazonec2.sh' actions='POST GET PUT DELETE' endpoint='/api/voucher/uuid' maincolor='none' prefix='allowed:' lettercolor='black' %} - -The `voucher` resource let's you create and manage digital vouchers, associated with any digital service provider, for better tracking and accounting of voucher consumption. - - ---- -_Examples_ - - -##### Create a new voucher - -{% include request_snippet.md file='api/voucher.sh' actions='POST' endpoint='/api/voucher' %} - -{% include code_snippet.md file='api/voucher.sh' language='shell' %} - -{% include response_snippet.md file='api/voucher-response.md' %} - - -# Python API - -(coming soon...) diff --git a/docs/nuvla/user-guide.md b/docs/nuvla/user-guide/index.md similarity index 86% rename from docs/nuvla/user-guide.md rename to docs/nuvla/user-guide/index.md index fc0be24..c7c1474 100644 --- a/docs/nuvla/user-guide.md +++ b/docs/nuvla/user-guide/index.md @@ -8,7 +8,7 @@ has_children: true # Nuvla - What is it? -Nuvla is a secured edge-to-cloud (and back) management platform that enables near-data AI for a connected world. +Nuvlaa is a secured edge-to-cloud (and back) management platform that enables near-data AI for a connected world. The container native platform supports all forms of infrastructure: public cloud, private cloud and bare metal infrastructures, as well as edge (with our NuvlaBox). diff --git a/docs/nuvlabox/v1/contributing/agent-api.md b/docs/nuvlabox/contributing/agent-api.md similarity index 99% rename from docs/nuvlabox/v1/contributing/agent-api.md rename to docs/nuvlabox/contributing/agent-api.md index 5267b7a..1c16c2b 100644 --- a/docs/nuvlabox/v1/contributing/agent-api.md +++ b/docs/nuvlabox/contributing/agent-api.md @@ -4,8 +4,7 @@ title: Before Starting nav_order: 1 parent: Contributing has_children: false -grand_parent: v1 -old_version: true +grand_parent: NuvlaBox --- Before you start contributing to the NuvlaBox software stack, you must be acquainted not only with the NB and NBE architectures and features, but also with the internal functionalities offered specifically for allowing the interaction between NBE micro-services. diff --git a/docs/nuvlabox/v1/contributing/custom-peripheral-managers.md b/docs/nuvlabox/contributing/custom-peripheral-managers.md similarity index 99% rename from docs/nuvlabox/v1/contributing/custom-peripheral-managers.md rename to docs/nuvlabox/contributing/custom-peripheral-managers.md index 996ef47..2f8eb2e 100644 --- a/docs/nuvlabox/v1/contributing/custom-peripheral-managers.md +++ b/docs/nuvlabox/contributing/custom-peripheral-managers.md @@ -4,8 +4,7 @@ title: Custom Peripheral Managers nav_order: 2 parent: Contributing has_children: false -grand_parent: v1 -old_version: true +grand_parent: NuvlaBox --- Building your own NuvlaBox Peripheral Manager diff --git a/docs/nuvlabox/v1/contributing/index.md b/docs/nuvlabox/contributing/index.md similarity index 94% rename from docs/nuvlabox/v1/contributing/index.md rename to docs/nuvlabox/contributing/index.md index d6099df..46c7b66 100644 --- a/docs/nuvlabox/v1/contributing/index.md +++ b/docs/nuvlabox/contributing/index.md @@ -1,11 +1,10 @@ --- layout: nuvlabox title: Contributing -nav_order: 6 -parent: v1 +nav_order: 5 +parent: NuvlaBox has_children: true permalink: /nuvlabox/nuvlabox-contributing -old_version: true --- Contributing to NuvlaBox diff --git a/docs/nuvlabox/v2/deploying-apps/first-app.md b/docs/nuvlabox/deploying-apps/first-app.md similarity index 98% rename from docs/nuvlabox/v2/deploying-apps/first-app.md rename to docs/nuvlabox/deploying-apps/first-app.md index 0133f64..1b35eb1 100644 --- a/docs/nuvlabox/v2/deploying-apps/first-app.md +++ b/docs/nuvlabox/deploying-apps/first-app.md @@ -3,7 +3,7 @@ layout: nuvlabox title: Your First NuvlaBox App nav_order: 1 parent: Apps Deployment -grand_parent: v2 +grand_parent: NuvlaBox has_children: false redirect_from: - /nuvlabox/latest/deploying-apps/first-app diff --git a/docs/nuvlabox/v2/deploying-apps/index.md b/docs/nuvlabox/deploying-apps/index.md similarity index 91% rename from docs/nuvlabox/v2/deploying-apps/index.md rename to docs/nuvlabox/deploying-apps/index.md index 30170f8..af9a753 100644 --- a/docs/nuvlabox/v2/deploying-apps/index.md +++ b/docs/nuvlabox/deploying-apps/index.md @@ -1,8 +1,8 @@ --- layout: nuvlabox title: Apps Deployment -nav_order: 4 -parent: v2 +nav_order: 6 +parent: NuvlaBox has_children: true redirect_from: - /nuvlabox/latest/deploying diff --git a/docs/nuvlabox/v2/how-to-choose.md b/docs/nuvlabox/how-to-choose.md similarity index 96% rename from docs/nuvlabox/v2/how-to-choose.md rename to docs/nuvlabox/how-to-choose.md index 3171122..41d19fe 100644 --- a/docs/nuvlabox/v2/how-to-choose.md +++ b/docs/nuvlabox/how-to-choose.md @@ -1,8 +1,8 @@ --- layout: nuvlabox title: NuvlaBox... Engine or OS? -nav_order: 1 -parent: v2 +nav_order: 4 +parent: NuvlaBox redirect_from: - /nuvlabox/latest/how-to-choose --- diff --git a/docs/nuvlabox/nuvlabox-engine/index.md b/docs/nuvlabox/nuvlabox-engine/index.md new file mode 100644 index 0000000..2658df7 --- /dev/null +++ b/docs/nuvlabox/nuvlabox-engine/index.md @@ -0,0 +1,17 @@ +--- +layout: nuvlabox +title: NuvlaBox Engine +nav_order: 1 +description: "Secure and intelligent edge computing solution" +parent: NuvlaBox +has_children: true +--- + +NuvlaBox Engine +======== + +The NuvlaBox Engine (**NBE**) is the heart of the NuvlaBox (**NB**). It provides the foundation services of the NB, which in turn ensure a robust, feature-rich and secure remote management from Nuvla. + +The NBE is implemented as a set of loosely coupled, open-source and containerised micro-services. You can find NBE's source code in [NuvlaBox's GitHub organisation](https://github.com/nuvlabox). + +You can find all releases of the NBE at [https://github.com/nuvlabox/deployment](https://github.com/nuvlabox/deployment). diff --git a/docs/nuvlabox/v1/nuvlabox-engine/architecture.md b/docs/nuvlabox/nuvlabox-engine/v1/architecture.md similarity index 79% rename from docs/nuvlabox/v1/nuvlabox-engine/architecture.md rename to docs/nuvlabox/nuvlabox-engine/v1/architecture.md index 034726a..dc1d0a8 100644 --- a/docs/nuvlabox/v1/nuvlabox-engine/architecture.md +++ b/docs/nuvlabox/nuvlabox-engine/v1/architecture.md @@ -2,17 +2,15 @@ layout: nuvlabox title: Architecture nav_order: 1 -parent: NuvlaBox Engine -grand_parent: v1 +grand_parent: NuvlaBox Engine +parent: v1 old_version: true --- NuvlaBox Engine Architecture ======== -The NuvlaBox Engine (**NBE**) runs as a set of loosely coupled containers. Under the hood, containers form the NBE components described in the following image: - -![nuvlabox-os-arch-detail](/assets/img/nuvlabox-os-arch-detail.png) +![nuvlabox-os-arch-detail](/assets/img/nuvlabox-engine-arch-v1.png) | NBE Component | Description | |-: |- | @@ -23,4 +21,4 @@ The NuvlaBox Engine (**NBE**) runs as a set of loosely coupled containers. Under | VPN CLIENT | The standalone `vpn-client` component is solely responsible for picking up an OpenVPN configuration set by the `network-manager` and establishing a secure VPN tunnel with SixSq's VPN server (or any other desired VPN server), ensuring that the NB is always remotely accessible | | SECURITY | The `security` component is an autonomous self-assessment agent which scans the edge device on a configurable periodic basis, looking for vulnerabilities. Each potential vulnerability is compared with public reference databases (like the CVE) for a full categorization of the problem. These databases are also kept up to date due to internal synchronization procedure which are also scheduled with a configurable frequency. The most critical vulnerabilities are sent to Nuvla (via the `agent`) | | DATA GATEWAY | The NBE `data-gateway` is a combination of micro-services which provides an abstraction layer between user applications and IoT sensors/actuators. Is is equipped with communication layer mechanisms (like an MQTT broker and a Reverse Proxy) which can, on demand, serve raw sensor data to any existing user applications, thus preventing users from having to embed complex sensor-specific data acquisition interfaces into their applications. Additionaly, and **optionally**, the NBE can also be deployed with the Data Gateway's FIWARE Processor, which is a sidekick micro-service that validates the schema of MQTT data, against FIWARE's data models, and upon successful validation, forwards data to a configurable outgoing endpoint. Learn how to make use of the Data Gateway in [this video](https://youtu.be/x7RKQWVq1Mc) | -| * PERIPHERAL MANAGER | The NBE has the concept of Peripheral Managers. These are **optional** micro-services which perform automatic detection and categorization of peripherals that *are* or *can be* connected to the edge device. Such peripheral information can then be used to activate sensor data acquisition throught the Data Gateway. Examples of existing peripheral managers are: `peripheral-manager-usb`, `peripheral-manager-bluetooth`, `peripheral-manager-modbus`, `peripheral-manager-gpu`, `peripheral-manager-network`, and others | \ No newline at end of file +| PERIPHERAL MANAGER | The NBE has the concept of Peripheral Managers. These are **optional** micro-services which perform automatic detection and categorization of peripherals that *are* or *can be* connected to the edge device. Such peripheral information can then be used to activate sensor data acquisition throught the Data Gateway. Examples of existing peripheral managers are: `peripheral-manager-usb`, `peripheral-manager-bluetooth`, `peripheral-manager-modbus`, `peripheral-manager-gpu`, `peripheral-manager-network`, and others | \ No newline at end of file diff --git a/docs/nuvlabox/v1/nuvlabox-engine/configuration.md b/docs/nuvlabox/nuvlabox-engine/v1/configuration.md similarity index 94% rename from docs/nuvlabox/v1/nuvlabox-engine/configuration.md rename to docs/nuvlabox/nuvlabox-engine/v1/configuration.md index 596bab1..3c0e8bb 100644 --- a/docs/nuvlabox/v1/nuvlabox-engine/configuration.md +++ b/docs/nuvlabox/nuvlabox-engine/v1/configuration.md @@ -2,14 +2,13 @@ layout: nuvlabox title: Configuration nav_order: 3 -parent: NuvlaBox Engine -grand_parent: v1 +parent: v1 +grand_parent: NuvlaBox Engine old_version: true --- -# NuvlaBox Engine (NBE) Configuration - -Before installing the NBE, you should be acquainted with all the configuration options available. Once installed, the NBE's configuration can only be changed through an update on full re-installation of the NBE. +When installing the NBE, there are a number of environment variable which can be set in order to customize the NuvlaBox. +Once installed, the NBE's configuration can only be changed through an update on full re-installation of the NBE. ## Environment Variables diff --git a/docs/nuvlabox/nuvlabox-engine/v1/index.md b/docs/nuvlabox/nuvlabox-engine/v1/index.md new file mode 100644 index 0000000..36cc22a --- /dev/null +++ b/docs/nuvlabox/nuvlabox-engine/v1/index.md @@ -0,0 +1,51 @@ +--- +layout: nuvlabox +title: v1 +nav_order: 2 +parent: NuvlaBox Engine +has_children: true +old_version: true +--- + +## Compatibility Matrix for the NuvlaBox Engine v1 + +**NOTE**: this table is only relevant in case you have your own instance of Nuvla. When working with [Nuvla.io](https://nuvla.io), +all NuvlaBox Engine versions are supported. + +When installing the NBE, please make sure the target release is supported by the Nuvla instance being used ([Nuvla.io](https://nuvla.io) by default). + +You can check Nuvla's version number on the page's footer, or at the "about" page (eg. [Nuvla.io current version](https://nuvla.io/ui/about)) + + +| NBE Release | Nuvla Release | +| :----: | :----: | +| 1.16.2 | 2.2.17+ | +| 1.16.1 | 2.2.14+ | +| 1.16.0 | 2.2.14+ | +| 1.15.2 | 2.2.12+ | +| 1.15.1 | 2.2.12+ | +| 1.15.0 | 2.2.12+ | +| 1.14.0 | 2.2.12+ | +| 1.13.0 | 2.2.10+ | +| 1.12.0 | 2.2.10+ | +| 1.11.0 | 2.2.10+ | +| 1.10.0 | 2.2.7+ | +| 1.9.2 | 2.2.1+ | +| 1.9.1 | 2.2.1+ | +| 1.9.0 | 2.2.0+ | +| 1.8.0 | 2.1.17+ | +| 1.7.0 | 2.1.15+ | +| 1.6.0 | 2.1.12+ | +| 1.5.0 | 2.1.12+ | +| 1.4.0 | 2.1.10+ | +| 1.3.1 | 2.1.10+ | +| 1.3.0 | 2.1.9+ | +| 1.2.0 | 2.1.9+ | +| 1.1.0 | 2.1.3+ | +| 1.0.0 | 2.0.0+ | + + + + + + diff --git a/docs/nuvlabox/nuvlabox-engine/v1/installation/index.md b/docs/nuvlabox/nuvlabox-engine/v1/installation/index.md new file mode 100644 index 0000000..93af391 --- /dev/null +++ b/docs/nuvlabox/nuvlabox-engine/v1/installation/index.md @@ -0,0 +1,10 @@ +--- +layout: nuvlabox +title: Installation +nav_order: 4 +parent: v1 +has_children: true +old_version: true +--- + +The NBE installation starts from Nuvla's [edge panel](https://nuvla.io/ui/edge). From there you can opt for one of two available installation methods: Compose Files bundle, or USB stick. diff --git a/docs/nuvlabox/nuvlabox-engine/v1/installation/install-with-compose-files.md b/docs/nuvlabox/nuvlabox-engine/v1/installation/install-with-compose-files.md new file mode 100644 index 0000000..f51acf4 --- /dev/null +++ b/docs/nuvlabox/nuvlabox-engine/v1/installation/install-with-compose-files.md @@ -0,0 +1,92 @@ +--- +layout: nuvlabox +title: Compose Files +nav_order: 1 +parent: Installation +grand_parent: v1 +old_version: true +--- + +# Install via Compose Files bundle + +1. login into [nuvla.io](https://nuvla.io) +2. from the [edge panel](https://nuvla.io/ui/edge), add a new `nuvlabox`, and either + 1. download the compose files from Nuvla, or + 2. copy the NuvlaBox UUID, and on your device, run `export NUVLABOX_UUID=` and download the compose files from [GitHub](https://github.com/nuvlabox/deployment/releases) +3. copy the given `docker-compose -p nuvlabox ...` command from Nuvla, and on your device, alongside the compose files retrieved in step 2. above, paste and run the command +4. after a few seconds, you should see your new NuvlaBox edge device becoming green in [Nuvla](https://nuvla.io/ui/edge), and if you run `docker ps` in your device, you should find (amongst others) something like: + ```bash + 865403c5d7f2 nuvlabox/system-manager:0.4.0 "./app.py" 3 weeks ago Up 6 hours (healthy) 127.0.0.1:3636->3636/tcp, 0.0.0.0:3637->3637/tcp nuvlabox_system-manager_1 + ``` + +### Halt the NuvlaBox + +In an edge environment, halting your devices is sometimes necessary. + +**When rebooting** your edge device, the NuvlaBox will resume by itself, alongside your device's Docker service, so you don't need to do anything. + +**When manually halting** the NuvlaBox, you can simply find the original compose files in your edge device, re-export the original environment variables (if not exported already), and run `docker-compose -p nuvlabox down`. Then **to resume**, simply run `docker-compose -p nuvlabox up -d`. Remember to specific the compose files in this command, whenever peripheral managers are also to be halted. + + +### Upgrade/Downgrade the NuvlaBox + +#### From Nuvla + +The NBE can be updated directly from Nuvla. On the user interface, in each NuvlaBox page, you'll find an action called "Update NuvlaBox" (as depicted below) + +![nb-update-nuvla.png](/assets/img/nb-update-nuvla.png) + +By clicking on it, you can specify which version of the NuvlaBox Engine is the target for the release. Please note that this is an asynchronous action that can take a few minutes, depending on your edge device's network. + +**Troubleshooting**: Please note that the update capability was only introduced in [NuvlaBox Engine v1.14.0](https://github.com/nuvlabox/deployment/releases/tag/1.14.0). You can still update your NuvlaBox to/from an older NuvlaBox Engine version, **however**, since the persistency of NB installation parameters was only introduced in v1.14.0, we can not guarantee that the final update will result in a similarly configured NBE! If you're updating to/from a NBE version <1.14.0, we recommend taking note of all the environment variables and Docker Compose arguments used during the installation, just in case a manual intervention is needed after an unsuccessful update. + +--- + +#### Manually + +You can also SSH into your edge device, and find the original project folder where you saved your Compose files. + +If you've initially installed the NuvlaBox Engine according to the instructions above, then you should see all of its components by running: + +```bash +# if there are also peripheral managers installed, remember to add "-f docker-compose..yml" to this command +# where "" is the type of peripheral manager you've installed above +$ docker-compose -p nuvlabox ps +``` + +You should get something like this: + +``` + Name Command State Ports +-------------------------------------------------------------------------------------------------- +datagateway /entrypoint.sh --entrypoin ... Up 80/tcp +nbmosquitto /docker-entrypoint.sh /usr ... Up (healthy) 1883/tcp +nuvlabox_agent_1 ./app.py Up 5000/tcp +nuvlabox_compute-api_1 ./api.sh Up 0.0.0.0:5000->5000/tcp +nuvlabox_management-api_1 ./app.py Up (healthy) 0.0.0.0:5001->5001/tcp +nuvlabox_network-manager_1 /opt/nuvlabox/network-mana ... Up 1194/udp +nuvlabox_system-manager_1 ./app.py Up (healthy) 127.0.0.1:3636->3636/tcp +vpn-client ./openvpn-client.sh Up +``` + +- **Cherry picking a NuvlaBox Engine component to be upgraded/downgraded:** let's say, as an example, that we want to upgrade the NuvlaBox Engine's Agent component. Then: + 1. open the `docker-compose.yml` file and find the `agent` service + 2. replace the corresponding Docker image tag (nuvlabox/agent:X.Y.Z)with the target version number. Save the file + 3. re-import all the necessary environment variables for the component being upgraded. In this case, make sure that at least NUVLABOX_UUID is set (if you're using [Nuvla.io](https://nuvla.io) + 4. execute `docker-compose -p nuvlabox up -d agent` + + This is valid for any NuvlaBox Engine component + +- **Upgrade/Downgrade the entire NuvlaBox Engine installation**: let's say we want to upgrade our existing NuvlaBox Engine installation to the latest release in [GitHub](https://github.com/nuvlabox/deployment/releases). Then: + 1. halt the NuvlaBox with `docker-compose -p nuvlabox down`, as explained [above](#halt-the-nuvlabox) + 2. move (or delete) the Compose files from the project folder you are in + 3. download the Compose files from the [target release in GitHub](https://github.com/nuvlabox/deployment/releases) + 4. resume the NuvlaBox Engine installation by running `docker-compose -p nuvlabox up -d` + + +### Uninstall the NuvlaBox + +To completely and **permanently** uninstall the NuvlaBox from your edge device, simply find your original compose files in the edge device, and run `docker-compose -p nuvlabox down -v --remove-orphans`. + +To re-install a new NuvlaBox from scratch in the same edge device, you'll need to go through the installation steps from above. + diff --git a/docs/nuvlabox/nuvlabox-engine/v1/installation/install-with-usb-stick.md b/docs/nuvlabox/nuvlabox-engine/v1/installation/install-with-usb-stick.md new file mode 100644 index 0000000..cd3545b --- /dev/null +++ b/docs/nuvlabox/nuvlabox-engine/v1/installation/install-with-usb-stick.md @@ -0,0 +1,118 @@ +--- +layout: nuvlabox +title: USB Stick +nav_order: 2 +parent: Installation +grand_parent: v1 +old_version: true +--- + +# Install via USB stick + +If your are looking to streamline the installation of the NuvlaBox Engine in your edge devices, then this is the best choice for you. + +The advantages of this installation method are: +- **NO** need for an external display +- **NO** need for SSH access to the device +- The same USB stick can be used **as many times** as needed +- **NO** technical expertise required + +Unlike the Compose file bundle, the USB stick installation method does not require manual user intervention, and thus does not support manual configuration of the NBE environment variable. **NUVLABOX_UUID**, **NUVLA_ENDPOINT** and **NUVLA_ENDPOINT_INSECURE** are automatically defined for you by Nuvla, during the installation process. + +It is _not_ yet possible to define variables like **HOSTNAME** and **VPN_INTERFACE_NAME** with this installation method. All possible NBE configurations for this installation method are set from Nuvla, at the time of creation of the USB stick file. + +### Additional requirements + +This installation method requires a specific NuvlaBox plugin to be installed in your Operating System, which will trigger the USB-based installation whenever you plug the flash drive. + +- if your devices **are running** a [NuvlaBox OS](/nuvlabox/nuvlabox-os.html), then you're good! You can jump straight to the [installation procedure below](#procedure) + +- if your devices **are NOT running** a [NuvlaBox OS](/nuvlabox/nuvlabox-os.html), then you **must** first prepare your operating system as follows: + + 1. make sure you are running a Linux distribution with `systemd` installed (we recommend using Debian or Ubuntu) + 2. get the latest version of the NuvlaBox USB Auto-installer plugin from GitHub: + + ```bash + git clone https://github.com/nuvlabox/nuvlabox-os.git /tmp/nuvlabox-os + + cd /tmp/nuvlabox-os + ``` + + 3. you'll find different NuvlaBox OS distributions here. These are enclosed within folders like `raspberrypi` (for a Raspbian-like NuvlaBox OS) or `generic` (for generic amd64 Debian-like NuvlaBox OS). Navigate to the folder that it closer to your own distribution + + ```bash + cd /tmp/nuvlabox-os/ + ``` + + 4. inside you'll find a `99_usb-auto-installer` folder + + ```bash + ls 99_usb-auto-installer + ``` + + 5. for all distros, inside the `99_usb-auto-installer` folder, you'll find an `.howToInstall` file. Run it + + ```bash + sudo sh .howToInstall + ``` + +You can now automate the installation of the NuvlaBox Engine into your fleet of edge devices. + +### Procedure + +If the OS of your edge device meets the [requirements](#additional-requirements), then all you have to do is to prepare your USB flash drive. + +Just follow these steps: + +1. go to [Nuvla](https://nuvla.io) and login +2. on the NuvlaBox tab, click `+add` and select the **USB stick** installation method + + ![nuvlabox-install-usb](/assets/img/nuvlabox-add-usb.png) + + With this method, a new API key credential is generated for you, and embedded into your USB stick. You can choose for how long this credentials should be valid. By default, this value is set for 30 days. After that, the credential expires and the corresponding USB stick becomes invalid. + +3. click `create` and wait. A new API key credential will be created and you'll be given a "trigger" file to download + + ![nuvlabox-add-usb-trigger](/assets/img/nuvlabox-add-usb-trigger.png) + +4. download the Trigger file, and copy it into your USB stick. You can place it anywhere within. + + **IMPORTANT:** make your your USB stick's filesystem is formatted as one of the following: _vfat, ext2, ext3, ext4, hfsplus_ or _ntfs_. + +5. plug your USB stick into your edge device. + +6. the NuvlaBox Auto-installer plugin that is installed in your device's OS will automatically be triggered by the USB stick, and kickstart the installation of the NuvlaBox Engine. At this stage, all you need to do is wait... + + It shouldn't take more than a few seconds for the process to start. Depending on your hardware, you might be able to get some external feedback on the progress of the installation. This feedback signal works for the following machine types: + - `raspberrypi`: + - **CONSTANT GREEN LED** for 10 sec. This means the NuvlaBox Engine installation process has **started** and you can safely remove your USB stick + + ![rpi-nb-start](/assets/img/rpi-nb-start.gif) + + - **HEARTBEAT GREEN LED** for 10 sec. This means the NuvlaBox Engine installation process has **finished** successfully + + ![rpi-nb-success](/assets/img/rpi-nb-success.gif) + + - **PULSING GREEN LED** for 10 sec. This means the NuvlaBox Engine installation process has **failed** + + ![rpi-nb-error](/assets/img/rpi-nb-error.gif) + +7. go back to the NuvlaBox tab in [Nuvla](https://nuvla.io) and your new NuvlaBox resource will appear. + + +### Upgrade the NuvlaBox Engine + +It is also possible to use the USB stick method to upgrade your NuvlaBox Engine installation. + +The procedure is the same as described [above](#procedure). If in Nuvla, you select a different NuvlaBox Engine version than the one you have already installed in your devices, then, when you plug the USB stick into the device, the NuvlaBox Auto-installer will upgrade all the outdated NuvlaBox Engine components, according to your desired version. + + +### Overwrite an existing installation + +It is also possible to use the USB stick method to completely delete and re-install your NuvlaBox Engine installation. However, in order to avoid damaging an existing installation, this process can only happen if the following conditions are met: + +- your previous NuvlaBox Engine installation is misconfigured, or +- your NuvlaBox resource is DECOMMISSIONED or in ERROR in [Nuvla](https://nuvla.io/ui/edge), or +- your NuvlaBox resource does not exist anymore in [Nuvla](https://nuvla.io/ui/edge), + +then the NuvlaBox Auto-installer will completely remove the existing NuvlaBox Engine installation from your device, and install a fresh new one. diff --git a/docs/nuvlabox/v1/nuvlabox-engine/requirements.md b/docs/nuvlabox/nuvlabox-engine/v1/requirements.md similarity index 64% rename from docs/nuvlabox/v1/nuvlabox-engine/requirements.md rename to docs/nuvlabox/nuvlabox-engine/v1/requirements.md index 8f93b2c..c109bd3 100644 --- a/docs/nuvlabox/v1/nuvlabox-engine/requirements.md +++ b/docs/nuvlabox/nuvlabox-engine/v1/requirements.md @@ -1,9 +1,9 @@ --- layout: nuvlabox title: Requirements -nav_order: 1 -parent: NuvlaBox Engine -grand_parent: v1 +nav_order: 2 +parent: v1 +grand_parent: NuvlaBox Engine old_version: true --- @@ -14,13 +14,12 @@ To ensure a smooth and fully functional installation of the NuvlaBox Engine (**N ## OS Requirements +The NuvlaBox Engine is compliant with any OS that officially and fully supports Docker. We recommend one of the following: +- Ubuntu +- CentOS +- Debian (and Debian variants like Raspbian and Raspberry Pi OS) -Ideally, you should be running one of the following: - - Ubuntu - - CentOS - - Debian (and Debian variants like Raspbian and Raspberry Pi OS) - -Other Linux distributions should also work, but will require testing. +Other Docker-compliant Linux distributions should also work, but the NuvlaBox functionality will be subject to the level of Docker support the OS provides. Functionalities like the automatic discovery and categorization of peripherals are **not** ensured for macOS and Windows. @@ -51,5 +50,5 @@ The NBE requires the following ports to be opened: |-: |- | | 3636 | Used by the `system-manager` to publish the internal NB dashboard | | 5000 | Used by the `compute-api` as the relay endpoint for Docker | -| 5001 | Used by the `management-api` for the NB remote management REST API | - +| 5001 | Used by the `management-api` for the NB remote management REST API | +| 1194 | (optional) outgoing UDP connections to vpn.nuvlabox.com must be allowed on this port in case you'd like to remotely connect to the edge device, via the VPN Client | diff --git a/docs/nuvlabox/nuvlabox-engine/v1/troubleshooting.md b/docs/nuvlabox/nuvlabox-engine/v1/troubleshooting.md new file mode 100644 index 0000000..d3592f0 --- /dev/null +++ b/docs/nuvlabox/nuvlabox-engine/v1/troubleshooting.md @@ -0,0 +1,35 @@ +--- +layout: nuvlabox +title: Troubleshooting +nav_order: 6 +parent: v1 +grand_parent: NuvlaBox Engine +old_version: true +--- + +# Troubleshooting + +
Failed to upgrade/downgrade my NuvlaBox Engine from/to v1.14.0 or lower + +
+Please note that the update capability was only introduced in [NuvlaBox Engine v1.14.0](https://github.com/nuvlabox/deployment/releases/tag/1.14.0). You can still update your NuvlaBox to/from an older NuvlaBox Engine version, **however**, since the persistency of NB installation parameters was only introduced in v1.14.0, we can not guarantee that the final update will result in a similarly configured NBE! If you're updating to/from a NBE version <1.14.0, we recommend taking note of all the environment variables and Docker Compose arguments used during the installation, just in case a manual intervention is needed after an unsuccessful update. + +
+
+ +--- + + +
ERROR: Get https://registry-1.docker.io/v2/: net/http: request canceled while waiting for connection + +
+If you are getting this error while installing the NuvlaBox Engine: + +```bash +ERROR: Get https://registry-1.docker.io/v2/: net/http: request canceled while waiting for connection (Client.Timeout exceeded while awaiting headers) +``` + +then you might be experiencing some networking issues with your setup. Try restarting your Docker Daemon (e.g. `systemctl restart docker` on Ubuntu), or ultimately, restart your device. If none of these solutions work, have a look at this [thread](https://forums.docker.com/t/docker-pull-results-in-request-canceled-while-waiting-for-connection-client-timeout-exceeded-while-awaiting-headers/73064/27) +
+ +
\ No newline at end of file diff --git a/docs/nuvlabox/nuvlabox-engine/v2/architecture.md b/docs/nuvlabox/nuvlabox-engine/v2/architecture.md new file mode 100644 index 0000000..8c1fb20 --- /dev/null +++ b/docs/nuvlabox/nuvlabox-engine/v2/architecture.md @@ -0,0 +1,34 @@ +--- +layout: nuvlabox +title: Architecture +nav_order: 1 +parent: v2 +grand_parent: NuvlaBox Engine +redirect_from: + - /nuvlabox/latest/nuvlabox-engine/architecture +--- + +Architecture +======== + +![nuvlabox-os-arch-detail](/assets/img/nuvlabox-engine-arch-v2.png) + +| NBE Component | Description | +|-: |- | +| AGENT | The `agent` is the beating heart of the NBE. It is responsible for the NB activation, commissioning and monitoring procedures. All outgoing communication towards Nuvla shall pass by the `agent`, via its internal REST API | +| SYSTEM MANAGER | The `system-manager` is the NBE's watchdog. It runs independently of all the other components. During the NBE bootstrap, it double checks that the device has the minimum requirements to support a NB, and if so, it starts scanning the whole NB on a periodic basis, searching for faulty NBE containers and trying to fix them automatically. It also provides an internal dashboard on the host's `127.0.0.1:3636` endpoint, with the overall status of the NB | +| COMPUTE CREDENTIALS MANAGER | Also referred to as the "COMPUTE API", this component makes sure all synchronous communications between Nuvla and the NuvlaBox, for application management, are secured | +| VPN CLIENT | The standalone `vpn-client` component is solely responsible for picking up an OpenVPN configuration set by the `agent` and establishing a secure VPN tunnel with SixSq's VPN server (or any other desired VPN server), ensuring that the NB is always remotely accessible | +| SECURITY | The `security` component is an autonomous self-assessment entity which scans the edge device on a configurable periodic basis, looking for vulnerabilities. Each potential vulnerability is compared with public reference databases (like the CVE) for a full categorization of the problem. These databases are also kept up to date via an internal synchronization procedure which is also scheduled with a configurable frequency. The most critical vulnerabilities are sent to Nuvla (via the `agent`) | +| DATA GATEWAY | The NBE `data-gateway` is an abstraction layer between user applications and IoT sensors/actuators. This component consists of an MQTT Broker (i.e. Mosquitto) which sits behind an internal shared network (the `nuvlabox-shared-network`). Depending on whether the NuvlaBox is operating in cluster mode or not, this component can either take the form of a standalone container behind a bridge network, or a load balanced service behind an overlay network. This configuration switch is handled automatically by the System Manager. Additionaly, and **optionally**, the NBE can also be deployed with the Data Gateway's FIWARE Processor, which is a sidekick micro-service that validates the schema of MQTT data, against FIWARE's data models, and upon successful validation, forwards data to a configurable outgoing endpoint | +| JOB ENGINE LITE | The Job Engine Lite is a lightweight version of the job processing engine behind Nuvla. Its introduction to the NuvlaBox Engine architecture allows users to remotely schedule operations to be executed inside the NuvlaBox, even if the edge device happens to be unreachable at the time of the command | +| PERIPHERAL MANAGER | The NBE has the concept of Peripheral Managers. These are **optional** micro-services which perform automatic detection and categorization of peripherals that *are* or *can be* connected to the edge device. Such peripheral information can then be used to activate sensor data acquisition throught the Data Gateway. Examples of existing peripheral managers are: `peripheral-manager-usb`, `peripheral-manager-bluetooth`, `peripheral-manager-modbus`, `peripheral-manager-gpu`, `peripheral-manager-network`, and others | + + +Deprecated Components +======== + +The following components have been deprecated with respect to the previous version of the NuvlaBox Engine, v1: + + - **Network Manager**: this component's functionality has been distributed over multiple components, including the System Manager, Agent and VPN Client; + - **Management API**: the NuvlaBox Engine v2 no longer exposes a dedicated API endpoint for remote management. Instead, with the introduction of the Job Engine Lite, all remote management operations are now done asynchronously, in the form of jobs that are scheduled from Nuvla and then pulled by the Agent for local execution within the NuvlaBox; \ No newline at end of file diff --git a/docs/nuvlabox/nuvlabox-engine/v2/configuration.md b/docs/nuvlabox/nuvlabox-engine/v2/configuration.md new file mode 100644 index 0000000..1262569 --- /dev/null +++ b/docs/nuvlabox/nuvlabox-engine/v2/configuration.md @@ -0,0 +1,34 @@ +--- +layout: nuvlabox +title: Configuration +nav_order: 3 +parent: v2 +grand_parent: NuvlaBox Engine +redirect_from: + - /nuvlabox/latest/nuvlabox-engine/configuration +--- + +When installing the NBE, there are a number of environment variable which can be set in order to customize the NuvlaBox. +Once installed, the NBE's configuration can only be changed through an update on full re-installation of the NBE. + + +## Environment Variables + +When installing the NBE, you can customize your NB via environment variables: + +- **NUVLABOX_UUID**: the unique Nuvla ID given to your NuvlaBox. Nuvla will provide this UUID. Also, if you've downloaded the compose files from Nuvla, this environment variable will already be set for you, otherwise, **you must set it** via `export NUVLABOX_UUID=`. Please note that the value of the variable can be given both in the form of `nuvlabox/` or simply ``; +- **NUVLABOX_DATA_GATEWAY_IMAGE**: name of the container image to be used for the MQTT Broker behind the NuvlaBox Data Gateway. You should only change this variable if you are sure the resulting Data Gateway functionality is not affected. To define a new MQTT broker image, simply run `export NUVLABOX_DATA_GATEWAY_IMAGE=` before the installation; +- **NUVLABOX_API_KEY**: when the NuvlaBox Engine is successfully installed, Nuvla will issue a unique API Key/Secret credential for that NuvlaBox to be able to securily communicate with Nuvla. This credential's key and secret are stored locally within the NuvlaBox Engine's data volume, which means that if for some reason, the volume is lost, so is the NuvlaBox, and you'll have to create a new one. With this variable, if your NuvlaBox local data is completely lost and but you know what its API Key and Secret were, you can still recover it by running `export NUVLABOX_API_KEY=credential/` and re-doing the NuvlaBox Engine installation steps. **NOTE**: this variable also needs NUVLABOX_API_SECRET to be set; +- **NUVLABOX_API_SECRET**: the secret corresponding to the NUVLABOX_API_KEY mentioned above. Please note that API secrets are not stored in Nuvla, so you can only get this value from your NuvlaBox's local data volume; +- **NUVLA_ENDPOINT**: endpoint for a Nuvla instance. By default it points to https://nuvla.io. But if you have your own Nuvla instance, you can point your NuvlaBox to it by running `export NUVLA_ENDPOINT=` before launching it; +- **NUVLA_ENDPOINT_INSECURE**: indicates whether to allow insecure (ignore TLS verification) communication between the NuvlaBox and Nuvla. By default it is set to **_false_**. In cases where you might have your own Nuvla instance, running on self-signed certificates, make sure you run `export NUVLA_ENDPOINT_INSECURE=True` before launching the NuvlaBox; +- **NUVLABOX_SSH_PUB_KEY**: it adds the provided string as a public SSH key into the host's `${HOME}/.ssh/authorized_keys` file. Please **note** that once set, this variable is no longer taken into consideration (e.g. during NuvlaBox Engine updates). This SSH key is immutable; +- **HOME**: defaults to your system user's HOME path. It is used for SSH key management. You should not edit this variable; +- **HOSTNAME**: used to generate the compute API credentials used by Nuvla to manage applications on the NuvlaBox. You should not edit this variable; +- **VPN_INTERFACE_NAME**: the NuvlaBox will have its own VPN client. By default, it will create a new network interface called **_vpn_**. If this conflicts with your existing network configuration, then please run `export VPN_INTERFACE_NAME=` before launching the NuvlaBox; +- **SKIP_MINIMUM_REQUIREMENTS**: when set to "True", it forces the installation of the NuvlaBox Engine without checking the system and software requirements. **Note**: this is not recommended, as the NuvlaBox might not behave as expected if the system requirements do not fulfill the minimum expectations; +- **EXTERNAL_CVE_VULNERABILITY_DB**: it consists of a link to an external CVE database, in CSV format and compressed, to be used as the reference database for the vulnerability scans. By default it points to an [aggregated CVE databased compiled by SixSq](https://github.com/nuvla/vuln-db/blob/main/databases/all.aggregated.csv.gz), from multiple trusted sources. If you want to use your own CVE database, then simply `export EXTERNAL_CSV_VULNERABILITY_DB=`; +- **EXTERNAL_CVE_VULNERABILITY_DB_UPDATE_INTERVAL**: the NBE Security component will periodically check for updates on the external CVE database defined in `EXTERNAL_CVE_VULNERABILITY_DB`. You can control how frequently these check for updates and synchronizations are performed. By default this interval is set to 86400 seconds (1 day). If you'd like to change it (please consider the consequences of the network load caused by such an update, in case your DB is large), please run `export EXTERNAL_CVE_VULNERABILITY_DB_UPDATE_INTERVAL=`. Please also **note** that this check for updates also relies on Nuvla, meaning that whatever `EXTERNAL_CVE_VULNERABILITY_DB` is chosen, it shall also be recognized by Nuvla. If it is not, please contact us; +- **SECURITY_SCAN_INTERVAL**: defines how regular the security scans are. By default, the scans are performed every 1800 seconds (30 min). If you'd like to change this, simply `export SECURITY_SCAN_INTERVAL=`. Bare in mind that depending on the `EXTERNAL_CSV_VULNERABILITY_DB`'s size, a security scan can take some time (order of minutes) and consume quite a bit of CPU, so take caution when increasing the frequency of the scans; + +_NOTE_: you can set these environment variables by either replacing them directly in the NuvlaBox Engine's Compose Files, or by running `export =` directly on your terminal prior to the installation \ No newline at end of file diff --git a/docs/nuvlabox/nuvlabox-engine/v2/index.md b/docs/nuvlabox/nuvlabox-engine/v2/index.md new file mode 100644 index 0000000..a9d9fe7 --- /dev/null +++ b/docs/nuvlabox/nuvlabox-engine/v2/index.md @@ -0,0 +1,36 @@ +--- +layout: nuvlabox +title: v2 +nav_order: 1 +parent: NuvlaBox Engine +has_children: true +redirect_from: +- /nuvlabox/latest +--- + +## Compatibility Matrix for the NuvlaBox Engine v2 + +**NOTE**: this table is only relevant in case you have your own instance of Nuvla. When working with [Nuvla.io](https://nuvla.io), +all NuvlaBox Engine versions are supported. + +When installing the NBE, please make sure the target release is supported by the Nuvla instance being used ([Nuvla.io](https://nuvla.io) by default). + +NOTE: you can check Nuvla's version number on the page's footer, or at the "about" page (eg. [Nuvla.io current version](https://nuvla.io/ui/about)) + + +| NBE Release | Nuvla Release | +| :----: | :----: | +| 2.1.1 | 2.2.25+ | +| 2.1.0 | 2.2.25+ | +| 2.0.6* | 2.2.25+ | +| 2.0.5* | 2.2.24+ | +| 2.0.4* | 2.2.24+ | +| 2.0.1* | 2.2.23+ | +| 2.0.0* | 2.2.20+ | + +\* **pre-release**: should not be used in production + + + + + diff --git a/docs/nuvlabox/nuvlabox-engine/v2/installation/index.md b/docs/nuvlabox/nuvlabox-engine/v2/installation/index.md new file mode 100644 index 0000000..b29856b --- /dev/null +++ b/docs/nuvlabox/nuvlabox-engine/v2/installation/index.md @@ -0,0 +1,11 @@ +--- +layout: nuvlabox +title: Installation +nav_order: 4 +parent: v2 +has_children: true +redirect_from: +- /nuvlabox/latest/nuvlabox-engine/quickstart +--- + +The NBE installation starts from Nuvla's [edge panel](https://nuvla.io/ui/edge). From there you can opt for one of two available installation methods: Compose Files bundle, or USB stick. diff --git a/docs/nuvlabox/nuvlabox-engine/v2/installation/install-with-compose-files.md b/docs/nuvlabox/nuvlabox-engine/v2/installation/install-with-compose-files.md new file mode 100644 index 0000000..6d820e7 --- /dev/null +++ b/docs/nuvlabox/nuvlabox-engine/v2/installation/install-with-compose-files.md @@ -0,0 +1,103 @@ +--- +layout: nuvlabox +title: Compose Files +nav_order: 1 +parent: Installation +grand_parent: v2 +--- + +# Install via Compose Files bundle + +1. login into [nuvla.io](https://nuvla.io) +2. from the [edge panel](https://nuvla.io/ui/edge), add a new `nuvlabox`, and either + 1. download the compose files from Nuvla, or + 2. copy the NuvlaBox UUID, and on your device, run `export NUVLABOX_UUID=` and download the compose files from [here](https://github.com/nuvlabox/deployment/releases) +3. copy the given `docker-compose -p nuvlabox ...` command from Nuvla, and on your device, in the same folder as the compose files from step 2., paste and run the command +4. after a few seconds, you should see your new NuvlaBox edge device becoming green in [Nuvla](https://nuvla.io/ui/edge), and if you run `docker ps` in your device, you should find (amongst others) something like: + ```bash + 9ca2441396d0 eclipse-mosquitto:1.6.12 "sh -c 'sleep 10 && …" 3 days ago Up 3 days 1883/tcp data-gateway.1.pgukfkffcn6ahooafaovzn6eq + 072743d2229a nuvladev/agent:master "./app.py" 3 weeks ago Up 3 days (healthy) 127.0.0.1:5080->80/tcp nuvlabox_agent_1 + 478817a492f2 nuvladev/compute-api:master "./api.sh" 3 weeks ago Up 3 days (healthy) 0.0.0.0:5000->5000/tcp, :::5000->5000/tcp compute-api + 7d71e78eaf2b nuvlabox/vpn-client:1.0.0 "./openvpn-client.sh" 3 weeks ago Up 3 days vpn-client + c2ef3b427eae nuvlabox/system-manager:2.1.5 "./run.py" 3 weeks ago Up 3 days (healthy) 127.0.0.1:3636->3636/tcp nuvlabox_system-manager_1 + d561b3bbdc7f nuvla/job-lite:2.18.0 "/app/pause.py" 3 weeks ago Up 3 days (Paused) nuvlabox-job-engine-lite + f92b151430e3 nuvlabox/security:1.2.0 "./app.py" 3 weeks ago Up 3 days nuvlabox_security_1 + 24226c6f802c nuvlabox/peripheral-manager-network:1.1.4 "python manager.py" 3 weeks ago Up 3 days nuvlabox_peripheral-manager-network_1 + abd12f371adb nuvlabox/peripheral-manager-usb:2.0.4 "peripheral-manager-…" 3 weeks ago Up 3 days nuvlabox_peripheral-manager-usb_1 + 3b9114d398cd nuvlabox/on-stop:1.0.1 "./run.py pause" 3 weeks ago Up 3 days (Paused) nuvlabox-on-stop + ``` + +If this is not the case, please consult the [Troubleshooting page](/nuvlabox/latest/nuvlabox-engine/troubleshooting). + +### Halt the NuvlaBox + +In an edge environment, halting your devices is sometimes necessary. Halting **does not mean** you will delete the NuvlaBox nor its local data, but rather stop its services temporarily. + +**When rebooting** your edge device, the NuvlaBox will resume by itself, alongside your device's Docker service, so you don't need to do anything. + +**When manually halting** the NuvlaBox, you **must** find (or re-download) the original compose files in your edge device, and run `docker-compose -p nuvlabox down`. Then **to resume**, simply run `docker-compose -p nuvlabox up -d`. Please note that `` must correspond to the list of compose files you have used during the first installation. In our case, looking at the `docker ps` output from above, `` should be replaced by `-f docker-compose.yml -f docker-compose.usb.yml -f docker-compose.network.yml` (e.g., to halt the NuvlaBox we'd then run `docker-compose -p nuvlabox -f docker-compose.yml -f docker-compose.usb.yml -f docker-compose.network.yml down`) + + +### Upgrade/Downgrade the NuvlaBox + +**NOTE**: automated migrations are not currently supported. If you must upgrade from a NuvlaBox Engine v1 to v2, or vice versa, please contact us. + +#### From Nuvla + +The NBE can be updated directly from Nuvla. On the user interface, in each NuvlaBox page, you'll find an action called "Update NuvlaBox" (as depicted below) + +![nb-update-nuvla.png](/assets/img/nb-update-nuvla.png) + +By clicking on it, you can specify which version of the NuvlaBox Engine is the target for the release. Please note that this is an asynchronous action that can take a few minutes, depending on your edge device's network. + +--- + +#### Manually + +You can also SSH into your edge device, and find the original project folder where you saved your Compose files. + +If you've initially installed the NuvlaBox Engine according to the instructions above, then you should see all of its components by running: + +```bash +$ docker-compose -p nuvlabox -f docker-compose.yml -f docker-compose.usb.yml -f docker-compose.network.yml ps +``` + +You should get something like this: + +``` + Name Command State Ports +-------------------------------------------------------------------------------------------------------------------------- +compute-api ./api.sh Up (healthy) 0.0.0.0:5000->5000/tcp,:::5000->5000/tcp +deployment_agent_1 ./app.py Up (healthy) 127.0.0.1:5080->80/tcp +deployment_peripheral-manager-network_1 python manager.py Up +deployment_peripheral-manager-usb_1 peripheral-manager-usb Up +deployment_security_1 ./app.py Up +deployment_system-manager_1 ./run.py Up (healthy) 127.0.0.1:3636->3636/tcp +nuvlabox-job-engine-lite /app/pause.py Paused +nuvlabox-on-stop ./run.py pause Paused +vpn-client ./openvpn-client.sh Up +``` + +- **Cherry picking a NuvlaBox Engine component to be upgraded/downgraded:** let's say, as an example, that we want to upgrade the NuvlaBox Engine's Agent component. Then: + 1. open the `docker-compose.yml` file and find the `agent` service + 2. replace the corresponding Docker image tag (nuvlabox/agent:X.Y.Z) with the target version number. Save the file + 4. execute `docker-compose -p nuvlabox -f docker-compose.yml -f docker-compose.usb.yml -f docker-compose.network.yml up -d agent` + + This is valid for any NuvlaBox Engine component + +- **Upgrade/Downgrade the entire NuvlaBox Engine installation**: let's say we want to upgrade our existing NuvlaBox Engine installation to the latest release in [GitHub](https://github.com/nuvlabox/deployment/releases). Then: + 1. halt the NuvlaBox, as explained [above](#halt-the-nuvlabox) + 2. backup the Compose files from the project folder you are in into a different folder (just in case you need to rollback) + 3. download the Compose files from the [target release in GitHub](https://github.com/nuvlabox/deployment/releases) + 4. resume the NuvlaBox Engine installation by running `docker-compose -p nuvlabox -f docker-compose.yml -f docker-compose.usb.yml -f docker-compose.network.yml up -d` + 1. if your goal is also to add a new peripheral manager to the existing NuvlaBox, then simply add its compose file to this command. For example, to also start managing Bluetooth peripherals, run `docker-compose -p nuvlabox -f docker-compose.yml -f docker-compose.usb.yml -f docker-compose.network.yml -f docker-compose.bluetooth.yml up -d` + 2. if your goal is also to remove an existing peripheral manager from the NuvlaBox installation, then remove its compose file from this command, and add `--remove-orphans`. For example, to also stop managing Network peripherals, run `docker-compose -p nuvlabox -f docker-compose.yml -f docker-compose.usb.yml up -d --remove-orphans` + + +### Uninstall the NuvlaBox + +**NOTE**: this action is permanent, **unless** you keep a copy of the NuvlaBox's API Key/Secret credential. This credential can be found at `/var/lib/docker/volumes/nuvlabox_nuvlabox-db/_data/.activated`. + +To completely and **permanently** uninstall the NuvlaBox from your edge device, simply find your original compose files in the edge device, and run `docker-compose -p nuvlabox down -v`. The `-v` will remove the NuvlaBox local data volume, so all of its data will be lost. + +To re-install a new NuvlaBox from scratch in the same edge device, you'll need to go through the installation steps from above. If you have the API Key/Secret from the NuvlaBox you've just deleted, then you also have the choice to recover it, even from a different device, via the configuration variables `NUVLABOX_API_KEY` and `NUVLABOX_API_SECRET`. See the [NuvlaBox Engine configuration](/nuvlabox/nuvlabox-engine/v2/configuration/) for more details. diff --git a/docs/nuvlabox/nuvlabox-engine/v2/installation/install-with-usb-stick.md b/docs/nuvlabox/nuvlabox-engine/v2/installation/install-with-usb-stick.md new file mode 100644 index 0000000..d862748 --- /dev/null +++ b/docs/nuvlabox/nuvlabox-engine/v2/installation/install-with-usb-stick.md @@ -0,0 +1,117 @@ +--- +layout: nuvlabox +title: USB Stick +nav_order: 2 +parent: Installation +grand_parent: v2 +--- + +# Install via USB stick + +If your are looking to streamline the installation of the NuvlaBox Engine in your edge devices, then this is the best choice for you. + +The advantages of this installation method are: +- **NO** need for an external display +- **NO** need for SSH access to the device +- The same USB stick can be used **as many times** as needed +- **NO** technical expertise required + +Unlike the Compose file bundle, the USB stick installation method does not require manual user intervention, and thus does not support manual configuration of the NBE environment variable. **NUVLABOX_UUID**, **NUVLA_ENDPOINT** and **NUVLA_ENDPOINT_INSECURE** are automatically defined for you by Nuvla, during the installation process. + +It is _not_ yet possible to define variables like **HOSTNAME** and **VPN_INTERFACE_NAME** with this installation method. All possible NBE configurations for this installation method are set from Nuvla, at the time of creation of the USB stick file. + +### Additional requirements + +This installation method requires a specific NuvlaBox plugin to be installed in your Operating System, which will trigger the USB-based installation whenever you plug the flash drive. + +- if your devices **are running** a [NuvlaBox OS](/nuvlabox/nuvlabox-os.html), then you're good! You can jump straight to the [installation procedure below](#procedure) + +- if your devices **are NOT running** a [NuvlaBox OS](/nuvlabox/nuvlabox-os.html), then you **must** first prepare your operating system as follows: + + 1. make sure you are running a Linux distribution with `systemd` installed (we recommend using Debian or Ubuntu) + 2. get the latest version of the NuvlaBox USB Auto-installer plugin from GitHub: + + ```bash + git clone https://github.com/nuvlabox/nuvlabox-os.git /tmp/nuvlabox-os + + cd /tmp/nuvlabox-os + ``` + + 3. you'll find different NuvlaBox OS distributions here. These are enclosed within folders like `raspberrypi` (for a Raspbian-like NuvlaBox OS) or `generic` (for generic amd64 Debian-like NuvlaBox OS). Navigate to the folder that it closer to your own distribution + + ```bash + cd /tmp/nuvlabox-os/ + ``` + + 4. inside you'll find a `99_usb-auto-installer` folder + + ```bash + ls 99_usb-auto-installer + ``` + + 5. for all distros, inside the `99_usb-auto-installer` folder, you'll find an `.howToInstall` file. Run it + + ```bash + sudo sh .howToInstall + ``` + +You can now automate the installation of the NuvlaBox Engine into your fleet of edge devices. + +### Procedure + +If the OS of your edge device meets the [requirements](#additional-requirements), then all you have to do is to prepare your USB flash drive. + +Just follow these steps: + +1. go to [Nuvla](https://nuvla.io) and login +2. on the NuvlaBox tab, click `+add` and select the **USB stick** installation method + + ![nuvlabox-install-usb](/assets/img/nuvlabox-add-usb.png) + + With this method, a new API key credential is generated for you, and embedded into your USB stick. You can choose for how long this credentials should be valid. By default, this value is set for 30 days. After that, the credential expires and the corresponding USB stick becomes invalid. + +3. click `create` and wait. A new API key credential will be created and you'll be given a "trigger" file to download + + ![nuvlabox-add-usb-trigger](/assets/img/nuvlabox-add-usb-trigger.png) + +4. download the Trigger file, and copy it into your USB stick. You can place it anywhere within. + + **IMPORTANT:** make your your USB stick's filesystem is formatted as one of the following: _vfat, ext2, ext3, ext4, hfsplus_ or _ntfs_. + +5. plug your USB stick into your edge device. + +6. the NuvlaBox Auto-installer plugin that is installed in your device's OS will automatically be triggered by the USB stick, and kickstart the installation of the NuvlaBox Engine. At this stage, all you need to do is wait... + + It shouldn't take more than a few seconds for the process to start. Depending on your hardware, you might be able to get some external feedback on the progress of the installation. This feedback signal works for the following machine types: + - `raspberrypi`: + - **CONSTANT GREEN LED** for 10 sec. This means the NuvlaBox Engine installation process has **started** and you can safely remove your USB stick + + ![rpi-nb-start](/assets/img/rpi-nb-start.gif) + + - **HEARTBEAT GREEN LED** for 10 sec. This means the NuvlaBox Engine installation process has **finished** successfully + + ![rpi-nb-success](/assets/img/rpi-nb-success.gif) + + - **PULSING GREEN LED** for 10 sec. This means the NuvlaBox Engine installation process has **failed** + + ![rpi-nb-error](/assets/img/rpi-nb-error.gif) + +7. go back to the NuvlaBox tab in [Nuvla](https://nuvla.io) and your new NuvlaBox resource will appear. + + +### Upgrade the NuvlaBox Engine + +It is also possible to use the USB stick method to upgrade your NuvlaBox Engine installation. + +The procedure is the same as described [above](#procedure). If in Nuvla, you select a different NuvlaBox Engine version than the one you have already installed in your devices, then, when you plug the USB stick into the device, the NuvlaBox Auto-installer will upgrade all the outdated NuvlaBox Engine components, according to your desired version. + + +### Overwrite an existing installation + +It is also possible to use the USB stick method to completely delete and re-install your NuvlaBox Engine installation. However, in order to avoid damaging an existing installation, this process can only happen if the following conditions are met: + +- your previous NuvlaBox Engine installation is misconfigured, or +- your NuvlaBox resource is DECOMMISSIONED or in ERROR in [Nuvla](https://nuvla.io/ui/edge), or +- your NuvlaBox resource does not exist anymore in [Nuvla](https://nuvla.io/ui/edge), + +then the NuvlaBox Auto-installer will completely remove the existing NuvlaBox Engine installation from your device, and install a fresh new one. diff --git a/docs/nuvlabox/nuvlabox-engine/v2/requirements.md b/docs/nuvlabox/nuvlabox-engine/v2/requirements.md new file mode 100644 index 0000000..25ff0a7 --- /dev/null +++ b/docs/nuvlabox/nuvlabox-engine/v2/requirements.md @@ -0,0 +1,55 @@ +--- +layout: nuvlabox +title: Requirements +nav_order: 2 +parent: v2 +grand_parent: NuvlaBox Engine +redirect_from: + - /nuvlabox/latest/nuvlabox-engine/requirements +--- + +# Requirements + +To ensure a smooth and fully functional installation of the NuvlaBox Engine (**NBE**), please make sure you comply with the following system requirements. + + +## OS Requirements + +The NuvlaBox Engine is compliant with any OS that officially and fully supports Docker. We recommend one of the following: +- Ubuntu +- CentOS +- Debian (and Debian variants like Raspbian and Raspberry Pi OS) + +Other Docker-compliant Linux distributions should also work, but the NuvlaBox functionality will be subject to the level of Docker support the OS provides. + +Functionalities like the automatic discovery and categorization of peripherals are **not** guaranteed for macOS and Windows. + + +## Hardware Requirements + +In order to install the NBE and ensure its smooth execution over time, your device should have at least: + +- 1GB of RAM +- 2GB of free disk space + + +## Software Requirements + +Before you can install the NBE, please make sure you have: + +- [Docker Engine (version 18 or higher)](https://docs.docker.com/install/#supported-platforms), running in [Swarm mode](https://docs.docker.com/engine/swarm/swarm-tutorial/) +- [Docker Compose (version 1.27.4 or higher)](https://docs.docker.com/compose/install/) + + +## Network Requirements + +You need **an internet connection**. + +The NBE requires the following ports to be opened: + +| Port | Reason | +|-: |- | +| 3636 | This port is used by the `system-manager` to publish the internal NB dashboard | +| 5000 | Used by the `compute-api` as the relay endpoint for Docker. Ingress must be allowed | +| 5080 | This port is used by the `agent` to provide the internal REST API for other NB components to speak with, internally | +| 1194 | (optional) outgoing UDP connections to vpn.nuvlabox.com must be allowed on this port in case you'd like to remotely connect to the edge device, via the VPN Client | diff --git a/docs/nuvlabox/nuvlabox-engine/v2/troubleshooting.md b/docs/nuvlabox/nuvlabox-engine/v2/troubleshooting.md new file mode 100644 index 0000000..0ee2e44 --- /dev/null +++ b/docs/nuvlabox/nuvlabox-engine/v2/troubleshooting.md @@ -0,0 +1,37 @@ +--- +layout: nuvlabox +title: Troubleshooting +nav_order: 6 +parent: v2 +grand_parent: NuvlaBox Engine +redirect_from: + - /nuvlabox/latest/nuvlabox-engine/troubleshooting +--- + +# Troubleshooting + + +
Failed to downgrade my NuvlaBox Engine to v1 + +
+Automated migrations are not currently supported. So even if it looks like your NuvlaBox Engine downgrade finished successfully, you'll soon realize, from Nuvla, that your NuvlaBox is not healthy. If you must downgrade from a NuvlaBox Engine v2 to v1, please contact us. +
+ +
+ +--- + + +
ERROR: Get https://registry-1.docker.io/v2/: net/http: request canceled while waiting for connection + +
+If you are getting this error while installing the NuvlaBox Engine: + +```bash +ERROR: Get https://registry-1.docker.io/v2/: net/http: request canceled while waiting for connection (Client.Timeout exceeded while awaiting headers) +``` + +then you might be experiencing some networking issues with your setup. Try restarting your Docker Daemon (e.g. `systemctl restart docker` on Ubuntu), or ultimately, restart your device. If none of these solutions work, have a look at this [thread](https://forums.docker.com/t/docker-pull-results-in-request-canceled-while-waiting-for-connection-client-timeout-exceeded-while-awaiting-headers/73064/27) +
+ +
\ No newline at end of file diff --git a/docs/nuvlabox/v2/nuvlabox-os/index.md b/docs/nuvlabox/nuvlabox-os/index.md similarity index 85% rename from docs/nuvlabox/v2/nuvlabox-os/index.md rename to docs/nuvlabox/nuvlabox-os/index.md index e40f813..b8585a5 100644 --- a/docs/nuvlabox/v2/nuvlabox-os/index.md +++ b/docs/nuvlabox/nuvlabox-os/index.md @@ -1,8 +1,8 @@ --- layout: nuvlabox title: NuvlaBox OS -nav_order: 2 -parent: v2 +nav_order: 3 +parent: NuvlaBox has_children: false redirect_from: - /nuvlabox/latest/nuvlabox-os diff --git a/docs/nuvlabox/v1/deploying-apps/first-app.md b/docs/nuvlabox/v1/deploying-apps/first-app.md deleted file mode 100644 index 47989a1..0000000 --- a/docs/nuvlabox/v1/deploying-apps/first-app.md +++ /dev/null @@ -1,36 +0,0 @@ ---- -layout: nuvlabox -title: Your First NuvlaBox App -nav_order: 1 -parent: Apps Deployment -grand_parent: v1 -has_children: false -old_version: true ---- - -# Deploying your first NuvlaBox Application - -Once you've installed either the NuvlaBox Engine or NuvlaBox OS, you'll find yourself with an Edge Computing capable device, that you can remotely manage from Nuvla. - -If your NuvlaBox installation was successful, you should now see the following in Nuvla: - - - from the [Edge panel](https://nuvla.io/ui/edge), your NuvlaBox is online - - in the [Infrastructures panel](https://nuvla.io/ui/infrastructures) you'll now see a new Docker Swarm infrastructure, named after your NuvlaBox - - in the [Credentials panel](https://nuvla.io/ui/credentials) you'll find the credentials for this infrastructure - ---- - -So, **let's deploy a Nuvla App into your NuvlaBox**: - - 1. login into [nuvla.io](https://nuvla.io) and go to the [App Store](https://nuvla.io/ui/apps) - - ![nuvla-app-store](/assets/img/app-store.png) - - 2. find your desired application (let's say Nginx for example) - 3. after making sure that App is compatible with your NuvlaBox's architecture, click `launch` - - ![nuvla-launch-app](/assets/img/launch-app.png) - - 4. select the right Credential for the NuvlaBox infrastructure you're deploying to - 5. if applicable, define any environment variables, configuration files and/or other runtime parameters that might be required by your app - 6. click `launch`, and you'll be redirected to your dashboard, where you can follow the state of your deployment diff --git a/docs/nuvlabox/v1/deploying-apps/index.md b/docs/nuvlabox/v1/deploying-apps/index.md deleted file mode 100644 index 5bd6930..0000000 --- a/docs/nuvlabox/v1/deploying-apps/index.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -layout: nuvlabox -title: Apps Deployment -nav_order: 4 -parent: v1 -has_children: true -old_version: true ---- - -Deployment of Applications on NuvlaBox -======== - -This section provides examples on deployment of user applications on NuvlaBox. - -![nuvlabox-os-arch-detail](/assets/img/nuvlabox-os-arch-detail.png) - - - diff --git a/docs/nuvlabox/v1/how-to-choose.md b/docs/nuvlabox/v1/how-to-choose.md deleted file mode 100644 index e437b1e..0000000 --- a/docs/nuvlabox/v1/how-to-choose.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -layout: nuvlabox -title: NuvlaBox... Engine or OS? -nav_order: 1 -parent: v1 -old_version: true ---- - -# NuvlaBox Engine or OS? - -NuvlaBox allows you to create a smart edge device, such that you can share its computing power for all sorts of edge processing tasks. You have two ways of achieving this goal. - -#### NuvlaBox Engine - -> you can take an existing functional device (with an OS and Docker Engine already installed), and turn it into an Edge device. [Follow these instructions](/nuvlabox/v1/nuvlabox-engine). - - -#### NuvlaBox OS - -> if you have a hardware platform without an Operating System (OS) installed, you can install the NuvlaBox OS, a dedicated and optimised OS for the edge. [Follow these instructions](/nuvlabox/v1/nuvlabox-os). - -Both options will result in a functional NuvlaBox, connected to a Nuvla service, able to deliver an edge computing solution, at scale. diff --git a/docs/nuvlabox/v1/index.md b/docs/nuvlabox/v1/index.md deleted file mode 100644 index 16a944a..0000000 --- a/docs/nuvlabox/v1/index.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -layout: nuvlabox -title: v1 -nav_order: 2 -description: "Secure and intelligent edge computing solution" -parent: NuvlaBox -has_children: true -old_version: true ---- - -![nuvlabox-logo](/assets/img/nuvlabox-logo.png){: .center-image } - -With NuvlaBox (**NB**), you can transform most ARM and x86 hardware platforms into a smart edge device, to be managed by a Nuvla service. - -To ensure a smooth edge deployment and operation, SixSq has certified a number of [hardware platforms](https://sixsq.com/products-and-services/nuvlabox/tech-spec), including x86 and ARM based systems, from HPE, Dell, Logic Supply, Raspberry Pi and Nvidia. - -But if you prefer to run on a different platform, SixSq offers a certification service, which will ensure you are able to deploy to this platform, at scale, without issues. Further, SixSq can also certify base operating systems (OS). Therefore, if you have your own operating system, as long as it supports Docker, SixSq also offers a certification process, ensuring that your operating system can run as a NuvlaBox OS. diff --git a/docs/nuvlabox/v1/nuvlabox-engine/index.md b/docs/nuvlabox/v1/nuvlabox-engine/index.md deleted file mode 100644 index e0632c3..0000000 --- a/docs/nuvlabox/v1/nuvlabox-engine/index.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -layout: nuvlabox -title: NuvlaBox Engine -nav_order: 1 -parent: v1 -has_children: true -old_version: true ---- - -NuvlaBox Engine -======== - -The NuvlaBox Engine (**NBE**) is the heart of the NuvlaBox (**NB**). It provides the foundation services of the NB, which in turn ensure a robust, feature-rich and secure remote management from Nuvla. - -The NBE is implemented as a set of loosely coupled, open-source and containerised micro-services. You can find NBE's source code in [NuvlaBox's GitHub organisation](https://github.com/nuvlabox). - -You can find all releases of the NBE at [https://github.com/nuvlabox/deployment](https://github.com/nuvlabox/deployment). - - -## Compatibility Matrix - -When installing the NBE, please make sure the target release is supported by the Nuvla instance being used ([Nuvla.io](https://nuvla.io) by default). - -_NOTE: you can check Nuvla's version number on the page's footer, or at the "about" page (eg. [Nuvla.io current version](https://nuvla.io/ui/about))_ - - -| NBE Release | Nuvla Release | -| :----: | :----: | -| 1.15.2 | 2.2.12+ | -| 1.15.1 | 2.2.12+ | -| 1.15.0 | 2.2.12+ | -| 1.14.0 | 2.2.12+ | -| 1.13.0 | 2.2.10+ | -| 1.12.0 | 2.2.10+ | -| 1.11.0 | 2.2.10+ | -| 1.10.0 | 2.2.7+ | -| 1.9.2 | 2.2.1+ | -| 1.9.1 | 2.2.1+ | -| 1.9.0 | 2.2.0+ | -| 1.8.0 | 2.1.17+ | -| 1.7.0 | 2.1.15+ | -| 1.6.0 | 2.1.12+ | -| 1.5.0 | 2.1.12+ | -| 1.4.0 | 2.1.10+ | -| 1.3.1 | 2.1.10+ | -| 1.3.0 | 2.1.9+ | -| 1.2.0 | 2.1.9+ | -| 1.1.0 | 2.1.3+ | -| 1.0.0 | 2.0.0+ | - - - - - - diff --git a/docs/nuvlabox/v1/nuvlabox-engine/quickstart.md b/docs/nuvlabox/v1/nuvlabox-engine/quickstart.md deleted file mode 100644 index 5c011f4..0000000 --- a/docs/nuvlabox/v1/nuvlabox-engine/quickstart.md +++ /dev/null @@ -1,203 +0,0 @@ ---- -layout: nuvlabox -title: Installation -nav_order: 4 -parent: NuvlaBox Engine -grand_parent: v1 -old_version: true ---- - -The NBE installation starts from Nuvla's [edge panel](https://nuvla.io/ui/edge). From there you can opt for one of two available installation methods: Compose file bundle, or USB stick. - -# Install via Compose file bundle - - 1. login into [nuvla.io](https://nuvla.io) - 2. from the [edge panel](https://nuvla.io/ui/edge), add a new `nuvlabox`, and either - 1. download the compose files from Nuvla, or - 2. copy the NuvlaBox UUID, and on your device, run `export NUVLABOX_UUID=` and download the compose files from [GitHub](https://github.com/nuvlabox/deployment/releases) - 3. copy the given `docker-compose -p nuvlabox ...` command from Nuvla, and on your device, alongside the compose files retrieved in step 2. above, paste and run the command - 4. after a few seconds, you should see your new NuvlaBox edge device becoming green in [Nuvla](https://nuvla.io/ui/edge), and if you run `docker ps` in your device, you should find (amongst others) something like: - ```bash - 865403c5d7f2 nuvlabox/system-manager:0.4.0 "./app.py" 3 weeks ago Up 6 hours (healthy) 127.0.0.1:3636->3636/tcp, 0.0.0.0:3637->3637/tcp nuvlabox_system-manager_1 - ``` - -### Halt the NuvlaBox - -In an edge environment, halting your devices is sometimes necessary. - -**When rebooting** your edge device, the NuvlaBox will resume by itself, alongside your device's Docker service, so you don't need to do anything. - -**When manually halting** the NuvlaBox, you can simply find the original compose files in your edge device, re-export the original environment variables (if not exported already), and run `docker-compose -p nuvlabox down`. Then **to resume**, simply run `docker-compose -p nuvlabox up -d`. - - -### Upgrade/Downgrade the NuvlaBox - -#### From Nuvla - -The NBE can be updated directly from Nuvla. On the user interface, in each NuvlaBox page, you'll find an action called "Update NuvlaBox" (as depicted below) - -![nb-update-nuvla.png](/assets/img/nb-update-nuvla.png) - -By clicking on it, you can specify which version of the NuvlaBox Engine is the target for the release. Please note that this is an asynchronous action that can take a few minutes, depending on your edge device's network. - -**Troubleshooting**: Please note that the update capability was only introduced in [NuvlaBox Engine v1.14.0](https://github.com/nuvlabox/deployment/releases/tag/1.14.0). You can still update your NuvlaBox to/from an older NuvlaBox Engine version, **however**, since the persistency of NB installation parameters was only introduced in v1.14.0, we can not guarantee that the final update will result in a similarly configured NBE! If you're updating to/from a NBE version <1.14.0, we recommend taking note of all the environment variables and Docker Compose arguments used during the installation, just in case a manual intervention is needed after an unsuccessful update. - ---- - -#### Manually - -You can also SSH into your edge device, and find the original project folder where you saved your Compose files. - -If you've initially installed the NuvlaBox Engine according to the instructions above, then you should see all of its components by running: - -```bash -$ docker-compose -p nuvlabox ps -``` - -You should get something like this: - -``` - Name Command State Ports --------------------------------------------------------------------------------------------------- -datagateway /entrypoint.sh --entrypoin ... Up 80/tcp -nbmosquitto /docker-entrypoint.sh /usr ... Up (healthy) 1883/tcp -nuvlabox_agent_1 ./app.py Up 5000/tcp -nuvlabox_compute-api_1 ./api.sh Up 0.0.0.0:5000->5000/tcp -nuvlabox_management-api_1 ./app.py Up (healthy) 0.0.0.0:5001->5001/tcp -nuvlabox_network-manager_1 /opt/nuvlabox/network-mana ... Up 1194/udp -nuvlabox_system-manager_1 ./app.py Up (healthy) 127.0.0.1:3636->3636/tcp -vpn-client ./openvpn-client.sh Up -``` - - - **Cherry picking a NuvlaBox Engine component to be upgraded/downgraded:** let's say, as an example, that we want to upgrade the NuvlaBox Engine's Agent component. Then: - 1. open the `docker-compose.yml` file and find the `agent` service - 2. replace the corresponding Docker image tag (nuvlabox/agent:X.Y.Z)with the target version number. Save the file - 3. re-import all the necessary environment variables for the component being upgraded. In this case, make sure that at least NUVLABOX_UUID is set (if you're using [Nuvla.io](https://nuvla.io) - 4. execute `docker-compose -p nuvlabox up -d agent` - - This is valid for any NuvlaBox Engine component - - - **Upgrade/Downgrade the entire NuvlaBox Engine installation**: let's say we want to upgrade our existing NuvlaBox Engine installation to the latest release in [GitHub](https://github.com/nuvlabox/deployment/releases). Then: - 1. halt the NuvlaBox with `docker-compose -p nuvlabox down`, as explained [above](#halt-the-nuvlabox) - 2. move (or delete) the Compose files from the project folder you are in - 3. download the Compose files from the [target release in GitHub](https://github.com/nuvlabox/deployment/releases) - 4. resume the NuvlaBox Engine installation by running `docker-compose -p nuvlabox up -d` - - -### Uninstall the NuvlaBox - -To completely and **permanently** uninstall the NuvlaBox from your edge device, simply find your original compose files in the edge device, and run `docker-compose -p nuvlabox down -v`. - -To re-install a new NuvlaBox from scratch in the same edge device, you'll need to go through the installation steps from above. - - - -# Install via USB stick - -If your are looking to streamline the installation of the NuvlaBox Engine in your edge devices, then this is the best choice for you. - -The advantages of this installation method are: - - **NO** need for an external display - - **NO** need for SSH access to the device - - The same USB stick can be used **as many times** as needed - - **NO** technical expertise required - -Unlike the Compose file bundle, the USB stick installation method does not require manual user intervention, and thus does not support manual configuration of the NBE environment variable. **NUVLABOX_UUID**, **NUVLA_ENDPOINT** and **NUVLA_ENDPOINT_INSECURE** are automatically defined for you by Nuvla, during the installation process. - -It is _not_ yet possible to define variables like **HOSTNAME** and **VPN_INTERFACE_NAME** with this installation method. All possible NBE configurations for this installation method are set from Nuvla, at the time of creation of the USB stick file. - -### Additional requirements - -This installation method requires a specific NuvlaBox plugin to be installed in your Operating System, which will trigger the USB-based installation whenever you plug the flash drive. - - - if your devices **are running** a [NuvlaBox OS](/nuvlabox/v1/nuvlabox-os), then you're good! You can jump straight to the [installation procedure below](#procedure) - - - if your devices **are NOT running** a [NuvlaBox OS](/nuvlabox/v1/nuvlabox-os), then you **must** first prepare your operating system as follows: - - 1. make sure you are running a Linux distribution with `systemd` installed (we recommend using Debian or Ubuntu) - 2. get the latest version of the NuvlaBox USB Auto-installer plugin from GitHub: - - ```bash - git clone https://github.com/nuvlabox/nuvlabox-os.git /tmp/nuvlabox-os - - cd /tmp/nuvlabox-os - ``` - - 3. you'll find different NuvlaBox OS distributions here. These are enclosed within folders like `raspberrypi` (for a Raspbian-like NuvlaBox OS) or `generic` (for generic amd64 Debian-like NuvlaBox OS). Navigate to the folder that it closer to your own distribution - - ```bash - cd /tmp/nuvlabox-os/ - ``` - - 4. inside you'll find a `99_usb-auto-installer` folder - - ```bash - ls 99_usb-auto-installer - ``` - - 5. for all distros, inside the `99_usb-auto-installer` folder, you'll find an `.howToInstall` file. Run it - - ```bash - sudo sh .howToInstall - ``` - -You can now automate the installation of the NuvlaBox Engine into your fleet of edge devices. - -### Procedure - -If the OS of your edge device meets the [requirements](#additional-requirements), then all you have to do is to prepare your USB flash drive. - -Just follow these steps: - - 1. go to [Nuvla](https://nuvla.io) and login - 2. on the NuvlaBox tab, click `+add` and select the **USB stick** installation method - - ![nuvlabox-install-usb](/assets/img/nuvlabox-add-usb.png) - - With this method, a new API key credential is generated for you, and embedded into your USB stick. You can choose for how long this credentials should be valid. By default, this value is set for 30 days. After that, the credential expires and the corresponding USB stick becomes invalid. - - 3. click `create` and wait. A new API key credential will be created and you'll be given a "trigger" file to download - - ![nuvlabox-add-usb-trigger](/assets/img/nuvlabox-add-usb-trigger.png) - - 4. download the Trigger file, and copy it into your USB stick. You can place it anywhere within. - - **IMPORTANT:** make your your USB stick's filesystem is formatted as one of the following: _vfat, ext2, ext3, ext4, hfsplus_ or _ntfs_. - - 5. plug your USB stick into your edge device. - - 6. the NuvlaBox Auto-installer plugin that is installed in your device's OS will automatically be triggered by the USB stick, and kickstart the installation of the NuvlaBox Engine. At this stage, all you need to do is wait... - - It shouldn't take more than a few seconds for the process to start. Depending on your hardware, you might be able to get some external feedback on the progress of the installation. This feedback signal works for the following machine types: - - `raspberrypi`: - - **CONSTANT GREEN LED** for 10 sec. This means the NuvlaBox Engine installation process has **started** and you can safely remove your USB stick - - ![rpi-nb-start](/assets/img/rpi-nb-start.gif) - - - **HEARTBEAT GREEN LED** for 10 sec. This means the NuvlaBox Engine installation process has **finished** successfully - - ![rpi-nb-success](/assets/img/rpi-nb-success.gif) - - - **PULSING GREEN LED** for 10 sec. This means the NuvlaBox Engine installation process has **failed** - - ![rpi-nb-error](/assets/img/rpi-nb-error.gif) - - 7. go back to the NuvlaBox tab in [Nuvla](https://nuvla.io) and your new NuvlaBox resource will appear. - - -### Upgrade the NuvlaBox Engine - -It is also possible to use the USB stick method to upgrade your NuvlaBox Engine installation. - -The procedure is the same as described [above](#procedure). If in Nuvla, you select a different NuvlaBox Engine version than the one you have already installed in your devices, then, when you plug the USB stick into the device, the NuvlaBox Auto-installer will upgrade all the outdated NuvlaBox Engine components, according to your desired version. - - -### Overwrite an existing installation - -It is also possible to use the USB stick method to completely delete and re-install your NuvlaBox Engine installation. However, in order to avoid damaging an existing installation, this process can only happen if the following conditions are met: - - - your previous NuvlaBox Engine installation is misconfigured, or - - your NuvlaBox resource is DECOMMISSIONED or in ERROR in [Nuvla](https://nuvla.io/ui/edge), or - - your NuvlaBox resource does not exist anymore in [Nuvla](https://nuvla.io/ui/edge), - -then the NuvlaBox Auto-installer will completely remove the existing NuvlaBox Engine installation from your device, and install a fresh new one. diff --git a/docs/nuvlabox/v1/nuvlabox-os/index.md b/docs/nuvlabox/v1/nuvlabox-os/index.md deleted file mode 100644 index c0dcc8e..0000000 --- a/docs/nuvlabox/v1/nuvlabox-os/index.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -layout: nuvlabox -title: NuvlaBox OS -nav_order: 2 -parent: v1 -has_children: false -redirect_from: - - /nuvlabox/nuvlabox-os/nuvlabox-os -old_version: true ---- - -![nuvlabox-os-arch-overview](/assets/img/nuvlabox-os-arch-overview.png) diff --git a/docs/nuvlabox/v2/contributing/agent-api.md b/docs/nuvlabox/v2/contributing/agent-api.md deleted file mode 100644 index 9f9d705..0000000 --- a/docs/nuvlabox/v2/contributing/agent-api.md +++ /dev/null @@ -1,151 +0,0 @@ ---- -layout: nuvlabox -title: Before Starting -nav_order: 1 -parent: Contributing -grand_parent: v2 -has_children: false -redirect_from: - - /nuvlabox/latest/contributing/agent-api ---- - -Before you start contributing to the NuvlaBox software stack, you must be acquainted not only with the NB and NBE architectures and features, but also with the internal functionalities offered specifically for allowing the interaction between NBE micro-services. - -# The NBE Agent API - -As mentioned in the [NBE Architecture](/nuvlabox/v2/nuvlabox-engine/architecture), the NBE Agent is one of the most critical components of the NB. - -All outgoing communication to Nuvla pass through the `agent`. For that, it provides an internal REST API for other NBE micro-services to speak with when they need to reach out to Nuvla. - -This ensures that whatever new micro-services are added to the NB, they won't need to manipulate Nuvla credentials in order to reach out to Nuvla. Instead, the `agent` will validate and broker their requests, sanitizing whatever information is being passed. - -So in short, if you are building a new component that will run alongside the NBE as a micro-service, and you need to interact with Nuvla, you need to use the NBE Agent API as follows: - -## REST API - -The NBE Agent API can only be reached from inside the NuvlaBox! - - - If your micro-service is **running on the same local Docker network** as the `agent` (typically this network is called `nuvlabox_default`, otherwise you can double check its name by running `docker network ls`), then you can reach the API at `http://agent/api` - - or, - - - if your micro-service is **running in host mode** (same network scope as any other process on the host device), then you can reach the API at `http://127.0.0.1:5080` - ---- - - -### Get agent healthcheck - -{% include request_snippet.md file='api/credential-amazonec2.sh' actions='GET' endpoint='/api/healthcheck' maincolor='none' prefix='allowed:' lettercolor='black' %} - -Returns something if the agent and respective API are already up and running. This call is meant to be used as a healthcheck for other components that are waiting for the agent to be ready. - -**_Examples:_** - -{% include request_snippet.md file='api/agent-api-healthcheck.sh' actions='GET' endpoint='/api/healthcheck' %} - -{% include code_snippet.md file='api/agent-api-healthcheck.sh' language='shell' %} - -{% include response_snippet.md file='api/agent-api-healthcheck-response.md' %} - ---- - -### Re-commission the NuvlaBox - -{% include request_snippet.md file='api/credential-amazonec2.sh' actions='POST' endpoint='/api/commission' maincolor='none' prefix='allowed:' lettercolor='black' %} - -It might happen that due to a change in the NuvlaBox or a need to refresh certain credentials and/or system configurations, the NuvlaBox needs to be re-commissioned so that Nuvla can propagate the new changes. This call will trigger a NuvlaBox re-commissioning, according to the request payload. - -This call is tailored to be used by specific NuvlaBox components like the Network Manager. - -However, **if you must use it**, you'll need to POST a JSON payload compliant with the NuvlaBox `commission` schema described [here](https://github.com/nuvla/api-server/blob/master/code/src/sixsq/nuvla/server/resources/nuvlabox/workflow_utils.clj). - -**_Examples:_** - -{% include request_snippet.md file='api/agent-api-commission.sh' actions='POST' endpoint='/api/commission' %} - -{% include code_snippet.md file='api/agent-api-commission.sh' language='shell' %} - -{% include response_snippet.md file='api/agent-api-commission-response.md' %} - ---- - -### Manage a peripheral - - -{% include request_snippet.md file='api/credential-amazonec2.sh' actions='GET POST PUT DELETE' endpoint='/api/peripheral/' maincolor='none' prefix='allowed:' lettercolor='black' %} - -Provides reading and editing capabilities for peripherals. - -**_Examples:_** - -#### Get a list of all peripheral identifiers already registered: - -{% include request_snippet.md file='api/agent-api-peripheral-get.sh' actions='GET' endpoint='/api/peripheral' %} - -{% include code_snippet.md file='api/agent-api-peripheral-get.sh' language='shell' %} - -{% include response_snippet.md file='api/agent-api-peripheral-get-response.md' %} - -
- - -#### Get the description of a specific peripheral, by identifier: - -{% include request_snippet.md file='api/agent-api-peripheral-get-specific.sh' actions='GET' endpoint='/api/peripheral/`identifier`' %} - -{% include code_snippet.md file='api/agent-api-peripheral-get-specific.sh' language='shell' %} - -{% include response_snippet.md file='api/agent-api-peripheral-get-specific-response.md' %} - -
- -#### Add a new peripheral: - -{% include request_snippet.md file='api/agent-api-peripheral-post.sh' actions='POST' endpoint='/api/peripheral' %} - -{% include code_snippet.md file='api/agent-api-peripheral-post.sh' language='shell' %} - -{% include response_snippet.md file='api/agent-api-peripheral-post-response.md' %} - -
- -#### Search for a peripheral by attribute: - -{% include request_snippet.md file='api/agent-api-peripheral-search.sh' actions='GET' endpoint='/api/peripheral?' %} - -{% include code_snippet.md file='api/agent-api-peripheral-search.sh' language='shell' %} - -{% include response_snippet.md file='api/agent-api-peripheral-search-response.md' %} - -
- - -#### Search for a peripheral by identifier regex: - -{% include request_snippet.md file='api/agent-api-peripheral-search-regex.sh' actions='GET' endpoint='/api/peripheral?' %} - -{% include code_snippet.md file='api/agent-api-peripheral-search-regex.sh' language='shell' %} - -{% include response_snippet.md file='api/agent-api-peripheral-search-regex-response.md' %} - -
- -#### Edit an existing peripheral - -{% include request_snippet.md file='api/agent-api-peripheral-put.sh' actions='PUT' endpoint='/api/peripheral/`identifier`' %} - -{% include code_snippet.md file='api/agent-api-peripheral-put.sh' language='shell' %} - -{% include response_snippet.md file='api/agent-api-peripheral-put-response.md' %} - -
- - -#### Delete an existing peripheral - -{% include request_snippet.md file='api/agent-api-peripheral-delete.sh' actions='DELETE' endpoint='/api/peripheral/`identifier`' %} - -{% include code_snippet.md file='api/agent-api-peripheral-delete.sh' language='shell' %} - -{% include response_snippet.md file='api/agent-api-peripheral-delete-response.md' %} \ No newline at end of file diff --git a/docs/nuvlabox/v2/contributing/custom-peripheral-managers.md b/docs/nuvlabox/v2/contributing/custom-peripheral-managers.md deleted file mode 100644 index f2542bf..0000000 --- a/docs/nuvlabox/v2/contributing/custom-peripheral-managers.md +++ /dev/null @@ -1,182 +0,0 @@ ---- -layout: nuvlabox -title: Custom Peripheral Managers -nav_order: 2 -parent: Contributing -has_children: false -grand_parent: v2 -redirect_from: - - /nuvlabox/latest/contributing/custom-peripheral-managers ---- - -Building your own NuvlaBox Peripheral Manager -======== - -There is a set of natively supported peripheral managers that you can opt to add to your NuvlaBox at installation time. Those are also open-source and can be found on GitHub [here](https://github.com/nuvlabox?q=peripheral-manager-). - -NuvlaBox Peripheral Managers are completely optional and should only be used if you'd like to have an automated mechanism to discover, register and manage peripheral devices that are attached to your NuvlaBox. Once registered, these peripheral devices can be visualized, managed and sometimes even directly controlled from Nuvla (like USB webcams). - -Due to the wide variety of IoT sensors/actuators and generic peripheral devices, it would be an impossible task for us at SixSq to develop all the NuvlaBox Peripheral Managers to support every single peripheral out there. - -## **This is where you come in!!** -{:style="text-align: center;"} - -Let's say you need a new NuvlaBox Peripheral Manager for a specific peripheral device. There are two ways you can go about it: - - 1. email us at [Support](mailto:support@sixsq.com) with your request and we'll try our best to accommodate your needs - - 2. develop your own NuvlaBox Peripheral Manager microservice - -If you go option 2., you should host your code in your own public/private repository, and then deploy alongside the NuvlaBox Engine. - -We support community-built NuvlaBox Peripheral Managers, so you can let us know about it and we can work together to make it official and available off the shelf from Nuvla! - ---- - -Building a new NuvlaBox Peripheral Manager is quite simple. We have built a transparent and generic REST API within the NuvlaBox Engine core installation that allows you to register and manage your peripheral devices in the Nuvla-NuvlaBox ecosystem without any in-depth knowledge nor code dependencies. - -There are only **2 requirements** for having your microservice functioning correctly as a NuvlaBox Peripheral Manager: - - a. _Your microservice needs to be on the same Docker network as the [NuvlaBox Agent component](https://github.com/nuvlabox/agent). This is usually guaranteed when you deploy all components at once, as described in the [Installation Quickstart](/nuvlabox/v2/nuvlabox-engine/quickstart)_ - - b. _Your code must manage the NuvlaBox peripheral devices through the management interface provided by the NuvlaBox Agent on port 80. The specification for this API can be found [here](https://github.com/nuvlabox/agent#manage-nuvlabox-peripherals)_ - - -Mocking a NuvlaBox Peripheral Manager ---------- - -Here's an example of a mock peripheral manager, that you can use as a starting point to build your own. - - -### Step 1 - -Create a working environment (local folder, GitHub repository, etc.) where you can put your code. - -We have created a [peripheral manager mock](https://github.com/nuvlabox/peripheral-manager-mock) for this exercise. - - -### Step 2 - -In that working environment, create your custom peripheral manager script. In our case, we're using a simple Shell script, so let's name our main manager script `peripheral-manager-mock.sh`. - -_peripheral-manager-mock.sh:_ -{% include code_snippet.md file='/nuvlabox-peripherals/peripheral-manager-mock_1.sh' language=shell %} - -#### Step 2.1 - -**Since this is an example**, we make certain assumptions. One of those is that we assume we know in advance the unique local identifier of our mock peripheral device. - -_peripheral-manager-mock.sh:_ -{% include code_snippet.md file='/nuvlabox-peripherals/peripheral-manager-mock_2.sh' language=shell %} - -**IMPORTANT**: unless you have a very special case, you should try to infer the peripheral identifier dynamically. - - -### Step 3 - -Our script needs to interact with the NuvlaBox Agent API for managing the mock peripheral, so let's build a couple of functions to help us to that. - -**NOTE**: these two functions are generic, so in most cases you can literally copy and paste them into your own scripts. - -_peripheral-manager-mock.sh:_ -{% include code_snippet.md file='/nuvlabox-peripherals/peripheral-manager-mock_3.sh' language=shell %} - - -### Step 4 - -Now to the actual peripheral discovery part of our script. According to our assumptions, our mock peripheral can be discovered via the existence of a certain file in the filesystem - _/dev/video0_. - -So it's quite a simple use case - all we need to do is to continuously watch that file, and trigger one of the functions from [Step 3](#step-3) above whenever the file is created or deleted. - -The `inotify-tools` package gives us a very useful tool for this purpose: `inotifywait` - -So our main code block would look something like this: -```shell -inotifywait -m -e create -e delete /dev | -while read -r directory event file -do - # We assume we only care about /dev/video0 - if [[ "${file}" = "video0" ]] - then - # If the mock peripheral was plugged in, then we want to register the new NuvlaBox peripheral - # otherwise, we want to remove it - if [[ "${event}" = "CREATE" ]] - then - #...do something - fi - - if [[ "${event}" = "DELETE" ]] - then - #...do something - fi - fi -done -``` - -Whenever the mock peripheral device is plugged, the CREATE event will be triggered and we'll need to: - 1. build the nuvlabox-resource JSON payload for that peripheral, according to the schema represented in [Nuvla API schema for NuvlaBox peripherals](https://nuvla.io/ui/documentation/nuvlabox-peripheral-1-1) - 2. send a POST request to the NuvlaBox Agent API, to register the new peripheral - -And, whenever the mock peripheral is unplugged, the DELETE event will be triggered, so we need to: - 1. send a DELETE request to the NuvlaBox Agent API with the corresponding peripheral identifier - -**Here's our final _peripheral-manager-mock.sh_ script!** - -_peripheral-manager-mock.sh:_ -{% include code_snippet.md file='/nuvlabox-peripherals/peripheral-manager-mock_4.sh' language=shell %} - - -### Step 5 - -Now that we've built our custom NuvlaBox Peripheral Manager for Mock peripherals (congrats), it's time to package our code. - -Let's build a Docker image that can be installed with the rest of the NuvlaBox Engine component. - -We want it to be **small**. So let's use Alpine, install our dependencies(`jq` and `curl` for the NuvlaBox Agent API functions, plus `inotify-tools` for watching the mock peripheral file), and copy our script into it. - -Build the following Dockerfile. - -_Dockerfile:_ -{% include code_snippet.md file='/nuvlabox-peripherals/Dockerfile' language=makefile %} - -### Step 6 - -We are now ready to build our Docker image. - -#### Simple build - -Just run `docker build . -t `. And the push the Docker image: `docker push `. - -#### Multi-platform build - -Make sure you have `docker buildx`. If not, have a look at: https://docs.docker.com/buildx/working-with-buildx/ - -```shell -# Create the build context: -docker buildx create --name multiplatformbuilder --use - -# Bootstrap the context and make sure you're targeted platforms are supported by it -docker buildx inspect --bootstrap - -# Build and push the Docker image -# Feel free to replace the platforms below by the ones you're targeting -docker buildx build --platform linux/arm/v6,linux/arm/v7,linux/amd64,linux/arm64 -t . --push -``` - -### Step 7 - - -We need a compose file to go alongside the other NuvlaBox Engine compose files. Remember to use **your Docker image** from [Step 6](#step-6), and to bind mount (read-only) the host's _/dev_ directory. - -_docker-compose.mock.yml:_ -{% include code_snippet.md file='/nuvlabox-peripherals/docker-compose.mock.yml' language=yaml %} - - -### Step 8 - -Finally, we can launch the custom NuvlaBox Peripheral Manager for Mock peripherals. - -Just add `-f docker-compose.mock.yml` to your NuvlaBox Engine installation command (as described in [NuvlaBox Installation](/nuvlabox/v2/nuvlabox-engine/quickstart) and that's it! - -**NOTE**: if you want to deploy your custom NuvlaBox Peripheral Manager after the NuvlaBox Engine has been installed, then please make sure that your container runs within the same Docker network as the NuvlaBox Agent. To do so, check in which Docker network your NuvlaBox Agent is running, via `docker network ls` and `docker inspect `, and add that network to your peripheral manager container, via the Compose property `networks` (see [Docker Compose docs](https://docs.docker.com/compose/compose-file/#networks)). - diff --git a/docs/nuvlabox/v2/contributing/index.md b/docs/nuvlabox/v2/contributing/index.md deleted file mode 100644 index 6284ae8..0000000 --- a/docs/nuvlabox/v2/contributing/index.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -layout: nuvlabox -title: Contributing -nav_order: 6 -parent: v2 -has_children: true -redirect_from: - - /nuvlabox/latest/contributing ---- - -Contributing to NuvlaBox -======== - -The NuvlaBox is a fully open-source project - [NuvlaBox in GitHub](https://github.com/nuvlabox/) - with all its components licensed under Apache 2.0. - -If you'd like to participate in the development of the NuvlaBox, either by writing new code or simply reporting issues and feature requests, you are free and encouraged to do so. - -For each NuvlaBox component, you'll find a Contributing guide within the respective GitHub repository. Here's an example for a [generic Contributing guide](https://github.com/nuvlabox/agent/blob/master/CONTRIBUTING.md). - -![for-contributors](/assets/img/uncle-sam.png){:.center-image } - - - diff --git a/docs/nuvlabox/v2/index.md b/docs/nuvlabox/v2/index.md deleted file mode 100644 index e1c0e82..0000000 --- a/docs/nuvlabox/v2/index.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -layout: nuvlabox -title: v2 -nav_order: 1 -description: "Secure and intelligent edge computing solution" -parent: NuvlaBox -has_children: true -redirect_from: - - /nuvlabox/latest ---- - -![nuvlabox-logo](/assets/img/nuvlabox-logo.png){: .center-image } - -With NuvlaBox (**NB**), you can transform most ARM and x86 hardware platforms into a smart edge device, to be managed by a Nuvla service. - -To ensure a smooth edge deployment and operation, SixSq has certified a number of [hardware platforms](https://sixsq.com/products-and-services/nuvlabox/tech-spec), including x86 and ARM based systems, from HPE, Dell, Logic Supply, Raspberry Pi and Nvidia. - -But if you prefer to run on a different platform, SixSq offers a certification service, which will ensure you are able to deploy to this platform, at scale, without issues. Further, SixSq can also certify base operating systems (OS). Therefore, if you have your own operating system, as long as it supports Docker, SixSq also offers a certification process, ensuring that your operating system can run as a NuvlaBox OS. diff --git a/docs/nuvlabox/v2/nuvlabox-engine/architecture.md b/docs/nuvlabox/v2/nuvlabox-engine/architecture.md deleted file mode 100644 index d888521..0000000 --- a/docs/nuvlabox/v2/nuvlabox-engine/architecture.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -layout: nuvlabox -title: Architecture -nav_order: 1 -parent: NuvlaBox Engine -grand_parent: v2 -redirect_from: - - /nuvlabox/latest/nuvlabox-engine/architecture ---- - -NuvlaBox Engine Architecture -======== - -The NuvlaBox Engine (**NBE**) runs as a set of loosely coupled containers. Under the hood, containers form the NBE components described in the following image: - -![nuvlabox-os-arch-detail](/assets/img/nuvlabox-os-arch-detail.png) - -| NBE Component | Description | -|-: |- | -| AGENT | The `agent` is the beating heart of the NBE. It is responsible for the NB activation, commissioning and monitoring procedures. All outgoing communication towards Nuvla shall pass by the `agent`, via its internal REST API | -| SYSTEM MANAGER | The `system-manager` is the NBE's watchdog. It runs independently of all the other components. During the NBE bootstrap, it double checks that the device has the minimum requirements to support a NB, and if so, it starts scanning the whole NB on a periodic basis, searching for faulty NBE containers and trying to fix them automatically. It also provides an internal dashboard on the host's `127.0.0.1:3636` endpoint, with the overall status of the NB | -| API | There are 2 externally accessible APIs managed by the NBE: the `compute-api` provides a TLS-encrypted relay point to Docker (for app & container management) on the host's `:5000` endpoint; and the `management-api` provides a TLS-encrypted and NB-specific management API for remote control of the NB, on the host's `:5001` endpoint | -| NETWORK MANAGER | The `network-manager` is responsible for ensuring a correct configuration of the host's network stack, in such a way that it supports the NBE's connectivity needs (such as the establishment of a VPN connection) | -| VPN CLIENT | The standalone `vpn-client` component is solely responsible for picking up an OpenVPN configuration set by the `network-manager` and establishing a secure VPN tunnel with SixSq's VPN server (or any other desired VPN server), ensuring that the NB is always remotely accessible | -| SECURITY | The `security` component is an autonomous self-assessment agent which scans the edge device on a configurable periodic basis, looking for vulnerabilities. Each potential vulnerability is compared with public reference databases (like the CVE) for a full categorization of the problem. These databases are also kept up to date due to internal synchronization procedure which are also scheduled with a configurable frequency. The most critical vulnerabilities are sent to Nuvla (via the `agent`) | -| DATA GATEWAY | The NBE `data-gateway` is a combination of micro-services which provides an abstraction layer between user applications and IoT sensors/actuators. Is is equipped with communication layer mechanisms (like an MQTT broker and a Reverse Proxy) which can, on demand, serve raw sensor data to any existing user applications, thus preventing users from having to embed complex sensor-specific data acquisition interfaces into their applications. Additionaly, and **optionally**, the NBE can also be deployed with the Data Gateway's FIWARE Processor, which is a sidekick micro-service that validates the schema of MQTT data, against FIWARE's data models, and upon successful validation, forwards data to a configurable outgoing endpoint. Learn how to make use of the Data Gateway in [this video](https://youtu.be/x7RKQWVq1Mc) | -| * PERIPHERAL MANAGER | The NBE has the concept of Peripheral Managers. These are **optional** micro-services which perform automatic detection and categorization of peripherals that *are* or *can be* connected to the edge device. Such peripheral information can then be used to activate sensor data acquisition throught the Data Gateway. Examples of existing peripheral managers are: `peripheral-manager-usb`, `peripheral-manager-bluetooth`, `peripheral-manager-modbus`, `peripheral-manager-gpu`, `peripheral-manager-network`, and others | \ No newline at end of file diff --git a/docs/nuvlabox/v2/nuvlabox-engine/configuration.md b/docs/nuvlabox/v2/nuvlabox-engine/configuration.md deleted file mode 100644 index bc47059..0000000 --- a/docs/nuvlabox/v2/nuvlabox-engine/configuration.md +++ /dev/null @@ -1,32 +0,0 @@ ---- -layout: nuvlabox -title: Configuration -nav_order: 3 -parent: NuvlaBox Engine -grand_parent: v2 -redirect_from: - - /nuvlabox/latest/nuvlabox-engine/configuration ---- - -# NuvlaBox Engine (NBE) Configuration - -Before installing the NBE, you should be acquainted with all the configuration options available. Once installed, the NBE's configuration can only be changed through an update on full re-installation of the NBE. - - -## Environment Variables - -When installing the NBE, you can customize your NB via environment variables: - - - **NUVLABOX_UUID**: the unique Nuvla ID given to your NuvlaBox. Nuvla will provide this UUID. Also, if you've downloaded the compose files from Nuvla, this environment variable will already be set for you, otherwise, **you must set it** via `export NUVLABOX_UUID=`; - - **NUVLA_ENDPOINT**: endpoint for a Nuvla instance. By default it points to https://nuvla.io. But if you have your own Nuvla instance, you can point your NuvlaBox to it by running `export NUVLA_ENDPOINT=` before launching it; - - **NUVLA_ENDPOINT_INSECURE**: indicated whether to allow insecure (ignore TLS verification) communication between the NuvlaBox and Nuvla. By default it is set to **_false_**. In cases where you might have your own Nuvla instance, running on self-signed certificates, make sure you run `export NUVLA_ENDPOINT_INSECURE=True` before launching the NuvlaBox; - - **HOST**: your device's hostname. This is optional, and sometimes take by default from your `env`, if the variable `$HOSTNAME` exists. It is used to generate the self-signed NuvlaBox certificates; - - **VPN_INTERFACE_NAME**: introduced in v1.3.0. The NuvlaBox will have its own VPN client. By default it will create a new network interface called **_vpn_**. If this conflicts with your existing network configuration, then please run `export VPN_INTERFACE_NAME=` before launching the NuvlaBox (use `export NUVLABOX_VPN_IFACE=` for versions <1.16.1); - - **NUVLABOX_SSH_PUB_KEY**: introduced in v1.9.0. If set, it add the provided string as a public SSH key into the host's `${HOME}/.ssh/authorized_keys` file; - - **HOST_USER**: introduced in v1.9.0 and meant to be dynamically defined at installation time, to match the host's user who is installing the NuvlaBox Engine. This value is important for the SSH key management workflow and thus should only be manually fixed under very special circumstances, at the user's own risk. **Deprecated** in v1.16.1; - - **HOST_HOME**: introduced in v1.16.1, as a replacement for the deprecated `$HOST_USER`. This variable is taken automatically from the underlying host environment. It is used as part of the SSH key management mechanism; - - **SKIP_MINIMUM_REQUIREMENTS**: introduced in v1.10.0, when set to "True", it forces the installation of the NuvlaBox Engine without checking the system and software requirements. **Note**: this is not recommended, as the NuvlaBox might not behave as expected if the system requirements do not fulfil the minimum expectations; - - **NUVLABOX_ENGINE_VERSION**: introduced in v1.10.0. This is a variable which is set upstream and thus should not be changed by the user. Changing it manually can result in reporting and operational inconsistencies when managing and using the NuvlaBox; - - **EXTERNAL_CVE_VULNERABILITY_DB**: introduced in v1.11.0. It consists of a link to an external CVE database, in CSV format and compressed, to be used as the reference database for the vulnerability scans. By default it points to an [aggregated CVE databased compiled by SixSq](https://github.com/nuvla/vuln-db/blob/main/databases/all.aggregated.csv.gz), from multiple trusted sources. If you want to use your own CVE database, then simply `export EXTERNAL_CSV_VULNERABILITY_DB=`; - - **EXTERNAL_CVE_VULNERABILITY_DB_UPDATE_INTERVAL**: introduced in v1.11.0. The NBE Security component will periodically check for updates on the external CVE database defined in `EXTERNAL_CVE_VULNERABILITY_DB`. You can control for frequently these check for updates and synchronization are performed. By default this interval is set to 86400 seconds (1 day). If you'd like to change it (please consider the consequences of the network load caused by such an update, in case your DB is large), please run `export EXTERNAL_CVE_VULNERABILITY_DB_UPDATE_INTERVAL=`. Please also **note** that this check for updates also relies on Nuvla, meaning that whatever `EXTERNAL_CVE_VULNERABILITY_DB` is chosen, it shall also be recognized by Nuvla. If it is not, please contact us; - - **SECURITY_SCAN_INTERVAL**: introduced in v1.11.0. Defines how regular the security scans are. By default, the scans are performed every 1800 seconds (30 min). If you'd like to change this, simply `export SECURITY_SCAN_INTERVAL=`. Bare in mind that depending on the `EXTERNAL_CSV_VULNERABILITY_DB`'s size, a security scan can take some time (order of minutes) and consume quite a bit of CPU, so take caution when increasing the frequency of the scans; \ No newline at end of file diff --git a/docs/nuvlabox/v2/nuvlabox-engine/index.md b/docs/nuvlabox/v2/nuvlabox-engine/index.md deleted file mode 100644 index f57de9d..0000000 --- a/docs/nuvlabox/v2/nuvlabox-engine/index.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -layout: nuvlabox -title: NuvlaBox Engine -nav_order: 1 -parent: v2 -has_children: true -redirect_from: - - /nuvlabox/latest/nuvlabox-engine ---- - -NuvlaBox Engine -======== - -The NuvlaBox Engine (**NBE**) is the heart of the NuvlaBox (**NB**). It provides the foundation services of the NB, which in turn ensure a robust, feature-rich and secure remote management from Nuvla. - -The NBE is implemented as a set of loosely coupled, open-source and containerised micro-services. You can find NBE's source code in [NuvlaBox's GitHub organisation](https://github.com/nuvlabox). - -You can find all releases of the NBE at [https://github.com/nuvlabox/deployment](https://github.com/nuvlabox/deployment). - - -## Compatibility Matrix - -When installing the NBE, please make sure the target release is supported by the Nuvla instance being used ([Nuvla.io](https://nuvla.io) by default). - -_NOTE: you can check Nuvla's version number on the page's footer, or at the "about" page (eg. [Nuvla.io current version](https://nuvla.io/ui/about))_ - - -| NBE Release | Nuvla Release | -| :----: | :----: | -| 1.15.2 | 2.2.12+ | -| 1.15.1 | 2.2.12+ | -| 1.15.0 | 2.2.12+ | -| 1.14.0 | 2.2.12+ | -| 1.13.0 | 2.2.10+ | -| 1.12.0 | 2.2.10+ | -| 1.11.0 | 2.2.10+ | -| 1.10.0 | 2.2.7+ | -| 1.9.2 | 2.2.1+ | -| 1.9.1 | 2.2.1+ | -| 1.9.0 | 2.2.0+ | -| 1.8.0 | 2.1.17+ | -| 1.7.0 | 2.1.15+ | -| 1.6.0 | 2.1.12+ | -| 1.5.0 | 2.1.12+ | -| 1.4.0 | 2.1.10+ | -| 1.3.1 | 2.1.10+ | -| 1.3.0 | 2.1.9+ | -| 1.2.0 | 2.1.9+ | -| 1.1.0 | 2.1.3+ | -| 1.0.0 | 2.0.0+ | - - - - - - diff --git a/docs/nuvlabox/v2/nuvlabox-engine/quickstart.md b/docs/nuvlabox/v2/nuvlabox-engine/quickstart.md deleted file mode 100644 index fb1e69a..0000000 --- a/docs/nuvlabox/v2/nuvlabox-engine/quickstart.md +++ /dev/null @@ -1,204 +0,0 @@ ---- -layout: nuvlabox -title: Installation -nav_order: 4 -parent: NuvlaBox Engine -grand_parent: v2 -redirect_from: - - /nuvlabox/latest/nuvlabox-engine/quickstart ---- - -The NBE installation starts from Nuvla's [edge panel](https://nuvla.io/ui/edge). From there you can opt for one of two available installation methods: Compose file bundle, or USB stick. - -# Install via Compose file bundle - - 1. login into [nuvla.io](https://nuvla.io) - 2. from the [edge panel](https://nuvla.io/ui/edge), add a new `nuvlabox`, and either - 1. download the compose files from Nuvla, or - 2. copy the NuvlaBox UUID, and on your device, run `export NUVLABOX_UUID=` and download the compose files from [GitHub](https://github.com/nuvlabox/deployment/releases) - 3. copy the given `docker-compose -p nuvlabox ...` command from Nuvla, and on your device, alongside the compose files retrieved in step 2. above, paste and run the command - 4. after a few seconds, you should see your new NuvlaBox edge device becoming green in [Nuvla](https://nuvla.io/ui/edge), and if you run `docker ps` in your device, you should find (amongst others) something like: - ```bash - 865403c5d7f2 nuvlabox/system-manager:0.4.0 "./app.py" 3 weeks ago Up 6 hours (healthy) 127.0.0.1:3636->3636/tcp, 0.0.0.0:3637->3637/tcp nuvlabox_system-manager_1 - ``` - -### Halt the NuvlaBox - -In an edge environment, halting your devices is sometimes necessary. - -**When rebooting** your edge device, the NuvlaBox will resume by itself, alongside your device's Docker service, so you don't need to do anything. - -**When manually halting** the NuvlaBox, you can simply find the original compose files in your edge device, re-export the original environment variables (if not exported already), and run `docker-compose -p nuvlabox down`. Then **to resume**, simply run `docker-compose -p nuvlabox up -d`. - - -### Upgrade/Downgrade the NuvlaBox - -#### From Nuvla - -The NBE can be updated directly from Nuvla. On the user interface, in each NuvlaBox page, you'll find an action called "Update NuvlaBox" (as depicted below) - -![nb-update-nuvla.png](/assets/img/nb-update-nuvla.png) - -By clicking on it, you can specify which version of the NuvlaBox Engine is the target for the release. Please note that this is an asynchronous action that can take a few minutes, depending on your edge device's network. - -**Troubleshooting**: Please note that the update capability was only introduced in [NuvlaBox Engine v1.14.0](https://github.com/nuvlabox/deployment/releases/tag/1.14.0). You can still update your NuvlaBox to/from an older NuvlaBox Engine version, **however**, since the persistency of NB installation parameters was only introduced in v1.14.0, we can not guarantee that the final update will result in a similarly configured NBE! If you're updating to/from a NBE version <1.14.0, we recommend taking note of all the environment variables and Docker Compose arguments used during the installation, just in case a manual intervention is needed after an unsuccessful update. - ---- - -#### Manually - -You can also SSH into your edge device, and find the original project folder where you saved your Compose files. - -If you've initially installed the NuvlaBox Engine according to the instructions above, then you should see all of its components by running: - -```bash -$ docker-compose -p nuvlabox ps -``` - -You should get something like this: - -``` - Name Command State Ports --------------------------------------------------------------------------------------------------- -datagateway /entrypoint.sh --entrypoin ... Up 80/tcp -nbmosquitto /docker-entrypoint.sh /usr ... Up (healthy) 1883/tcp -nuvlabox_agent_1 ./app.py Up 5000/tcp -nuvlabox_compute-api_1 ./api.sh Up 0.0.0.0:5000->5000/tcp -nuvlabox_management-api_1 ./app.py Up (healthy) 0.0.0.0:5001->5001/tcp -nuvlabox_network-manager_1 /opt/nuvlabox/network-mana ... Up 1194/udp -nuvlabox_system-manager_1 ./app.py Up (healthy) 127.0.0.1:3636->3636/tcp -vpn-client ./openvpn-client.sh Up -``` - - - **Cherry picking a NuvlaBox Engine component to be upgraded/downgraded:** let's say, as an example, that we want to upgrade the NuvlaBox Engine's Agent component. Then: - 1. open the `docker-compose.yml` file and find the `agent` service - 2. replace the corresponding Docker image tag (nuvlabox/agent:X.Y.Z)with the target version number. Save the file - 3. re-import all the necessary environment variables for the component being upgraded. In this case, make sure that at least NUVLABOX_UUID is set (if you're using [Nuvla.io](https://nuvla.io) - 4. execute `docker-compose -p nuvlabox up -d agent` - - This is valid for any NuvlaBox Engine component - - - **Upgrade/Downgrade the entire NuvlaBox Engine installation**: let's say we want to upgrade our existing NuvlaBox Engine installation to the latest release in [GitHub](https://github.com/nuvlabox/deployment/releases). Then: - 1. halt the NuvlaBox with `docker-compose -p nuvlabox down`, as explained [above](#halt-the-nuvlabox) - 2. move (or delete) the Compose files from the project folder you are in - 3. download the Compose files from the [target release in GitHub](https://github.com/nuvlabox/deployment/releases) - 4. resume the NuvlaBox Engine installation by running `docker-compose -p nuvlabox up -d` - - -### Uninstall the NuvlaBox - -To completely and **permanently** uninstall the NuvlaBox from your edge device, simply find your original compose files in the edge device, and run `docker-compose -p nuvlabox down -v`. - -To re-install a new NuvlaBox from scratch in the same edge device, you'll need to go through the installation steps from above. - - - -# Install via USB stick - -If your are looking to streamline the installation of the NuvlaBox Engine in your edge devices, then this is the best choice for you. - -The advantages of this installation method are: - - **NO** need for an external display - - **NO** need for SSH access to the device - - The same USB stick can be used **as many times** as needed - - **NO** technical expertise required - -Unlike the Compose file bundle, the USB stick installation method does not require manual user intervention, and thus does not support manual configuration of the NBE environment variable. **NUVLABOX_UUID**, **NUVLA_ENDPOINT** and **NUVLA_ENDPOINT_INSECURE** are automatically defined for you by Nuvla, during the installation process. - -It is _not_ yet possible to define variables like **HOSTNAME** and **VPN_INTERFACE_NAME** with this installation method. All possible NBE configurations for this installation method are set from Nuvla, at the time of creation of the USB stick file. - -### Additional requirements - -This installation method requires a specific NuvlaBox plugin to be installed in your Operating System, which will trigger the USB-based installation whenever you plug the flash drive. - - - if your devices **are running** a [NuvlaBox OS](/nuvlabox/v2/nuvlabox-os), then you're good! You can jump straight to the [installation procedure below](#procedure) - - - if your devices **are NOT running** a [NuvlaBox OS](/nuvlabox/v2/nuvlabox-os), then you **must** first prepare your operating system as follows: - - 1. make sure you are running a Linux distribution with `systemd` installed (we recommend using Debian or Ubuntu) - 2. get the latest version of the NuvlaBox USB Auto-installer plugin from GitHub: - - ```bash - git clone https://github.com/nuvlabox/nuvlabox-os.git /tmp/nuvlabox-os - - cd /tmp/nuvlabox-os - ``` - - 3. you'll find different NuvlaBox OS distributions here. These are enclosed within folders like `raspberrypi` (for a Raspbian-like NuvlaBox OS) or `generic` (for generic amd64 Debian-like NuvlaBox OS). Navigate to the folder that it closer to your own distribution - - ```bash - cd /tmp/nuvlabox-os/ - ``` - - 4. inside you'll find a `99_usb-auto-installer` folder - - ```bash - ls 99_usb-auto-installer - ``` - - 5. for all distros, inside the `99_usb-auto-installer` folder, you'll find an `.howToInstall` file. Run it - - ```bash - sudo sh .howToInstall - ``` - -You can now automate the installation of the NuvlaBox Engine into your fleet of edge devices. - -### Procedure - -If the OS of your edge device meets the [requirements](#additional-requirements), then all you have to do is to prepare your USB flash drive. - -Just follow these steps: - - 1. go to [Nuvla](https://nuvla.io) and login - 2. on the NuvlaBox tab, click `+add` and select the **USB stick** installation method - - ![nuvlabox-install-usb](/assets/img/nuvlabox-add-usb.png) - - With this method, a new API key credential is generated for you, and embedded into your USB stick. You can choose for how long this credentials should be valid. By default, this value is set for 30 days. After that, the credential expires and the corresponding USB stick becomes invalid. - - 3. click `create` and wait. A new API key credential will be created and you'll be given a "trigger" file to download - - ![nuvlabox-add-usb-trigger](/assets/img/nuvlabox-add-usb-trigger.png) - - 4. download the Trigger file, and copy it into your USB stick. You can place it anywhere within. - - **IMPORTANT:** make your your USB stick's filesystem is formatted as one of the following: _vfat, ext2, ext3, ext4, hfsplus_ or _ntfs_. - - 5. plug your USB stick into your edge device. - - 6. the NuvlaBox Auto-installer plugin that is installed in your device's OS will automatically be triggered by the USB stick, and kickstart the installation of the NuvlaBox Engine. At this stage, all you need to do is wait... - - It shouldn't take more than a few seconds for the process to start. Depending on your hardware, you might be able to get some external feedback on the progress of the installation. This feedback signal works for the following machine types: - - `raspberrypi`: - - **CONSTANT GREEN LED** for 10 sec. This means the NuvlaBox Engine installation process has **started** and you can safely remove your USB stick - - ![rpi-nb-start](/assets/img/rpi-nb-start.gif) - - - **HEARTBEAT GREEN LED** for 10 sec. This means the NuvlaBox Engine installation process has **finished** successfully - - ![rpi-nb-success](/assets/img/rpi-nb-success.gif) - - - **PULSING GREEN LED** for 10 sec. This means the NuvlaBox Engine installation process has **failed** - - ![rpi-nb-error](/assets/img/rpi-nb-error.gif) - - 7. go back to the NuvlaBox tab in [Nuvla](https://nuvla.io) and your new NuvlaBox resource will appear. - - -### Upgrade the NuvlaBox Engine - -It is also possible to use the USB stick method to upgrade your NuvlaBox Engine installation. - -The procedure is the same as described [above](#procedure). If in Nuvla, you select a different NuvlaBox Engine version than the one you have already installed in your devices, then, when you plug the USB stick into the device, the NuvlaBox Auto-installer will upgrade all the outdated NuvlaBox Engine components, according to your desired version. - - -### Overwrite an existing installation - -It is also possible to use the USB stick method to completely delete and re-install your NuvlaBox Engine installation. However, in order to avoid damaging an existing installation, this process can only happen if the following conditions are met: - - - your previous NuvlaBox Engine installation is misconfigured, or - - your NuvlaBox resource is DECOMMISSIONED or in ERROR in [Nuvla](https://nuvla.io/ui/edge), or - - your NuvlaBox resource does not exist anymore in [Nuvla](https://nuvla.io/ui/edge), - -then the NuvlaBox Auto-installer will completely remove the existing NuvlaBox Engine installation from your device, and install a fresh new one. diff --git a/docs/nuvlabox/v2/nuvlabox-engine/requirements.md b/docs/nuvlabox/v2/nuvlabox-engine/requirements.md deleted file mode 100644 index c6a7bf5..0000000 --- a/docs/nuvlabox/v2/nuvlabox-engine/requirements.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -layout: nuvlabox -title: Requirements -nav_order: 1 -parent: NuvlaBox Engine -grand_parent: v2 -redirect_from: - - /nuvlabox/latest/nuvlabox-engine/requirements ---- - -# Requirements - -To ensure a smooth and fully functional installation of the NuvlaBox Engine (**NBE**), please make sure you comply with the following system requirements. - - -## OS Requirements - - -Ideally, you should be running one of the following: - - Ubuntu - - CentOS - - Debian (and Debian variants like Raspbian and Raspberry Pi OS) - -Other Linux distributions should also work, but will require testing. - -Functionalities like the automatic discovery and categorization of peripherals are **not** ensured for macOS and Windows. - - -## Hardware Requirements - -In order to install the NBE and ensure its smooth execution over time, your device should have at least: - - - 1GB of RAM - - 2GB of free disk space - - -## Software Requirements - -Before you can install the NBE, please make sure you have: - - - [Docker Engine (version 18 or higher)](https://docs.docker.com/install/#supported-platforms), running in [Swarm mode](https://docs.docker.com/engine/swarm/swarm-tutorial/) - - [Docker Compose (version 1.27.4 or higher)](https://docs.docker.com/compose/install/) - - -## Network Requirements - -You need **an internet connection**. - -The NBE requires the following ports to be opened: - -| Port | Reason | -|-: |- | -| 3636 | Used by the `system-manager` to publish the internal NB dashboard | -| 5000 | Used by the `compute-api` as the relay endpoint for Docker | -| 5001 | Used by the `management-api` for the NB remote management REST API | -