diff --git a/docs/diana/backend.md b/docs/diana/backend.md index bb85b213..c0790502 100644 --- a/docs/diana/backend.md +++ b/docs/diana/backend.md @@ -29,39 +29,40 @@ We recommend you use a [Python virtual environment](https://docs.python.org/3/li 1. Create a Python virtual environment: -``` -python3.10 -m venv venv -``` + ``` + python3.10 -m venv venv + ``` 2. Open a new terminal window. Activate the Python virtual environment in this new window: -``` -. venv/bin/activate -``` + ``` + . venv/bin/activate + ``` -Using this new window, proceed with the instructions. + Using this new window, proceed with the instructions. ## Install Diana 3. Use Pip to install Diana: -``` -pip install --pre neon-diana-utils -``` - -This command installs the newest pre-release version, which is described in this tutorial. - -**Warning:** You can use `pip install neon-diana-utils` to install the current stable version. Version 1.0.0 includes Helm chart support. For information on installing and running older versions, see [the archived documentation in the README file](https://github.com/NeonGeckoCom/neon-diana-utils/blob/dev/README.md). + ``` + pip install --pre neon-diana-utils + ``` -For more information on the available versions of Diana, see [the Python Package Index repo for Neon Diana](https://pypi.org/project/neon-diana-utils/). + This command installs the newest pre-release version, which is described in this tutorial. + + **Warning:** You can use `pip install neon-diana-utils` to install the current stable version. Version 1.0.0 includes Helm chart support. For information on installing and running older versions, see [the archived documentation in the README file](https://github.com/NeonGeckoCom/neon-diana-utils/blob/dev/README.md). + + For more information on the available versions of Diana, see [the Python Package Index repo for Neon Diana](https://pypi.org/project/neon-diana-utils/). 4. Verify Diana is installed: -``` -diana --version -``` + ``` + diana --version + ``` -**Tip:** If your computer does not recognize this command, you may need to add `~/.local/bin` to your $PATH with a command like `export PATH=$PATH:/home/${USER}/.local/bin`. + **Tip:** If your computer does not recognize this command, you may need to + add `~/.local/bin` to your $PATH with a command like `export PATH=$PATH:/home/${USER}/.local/bin`. Use `diana --help` for detailed information about Diana and its commands. @@ -105,39 +106,42 @@ newgrp microk8s 5. Start Microk8s: -``` -microk8s start -``` + ``` + microk8s start + ``` 6. Enable the services for persistent storage, DNS, and the Kubernetes dashboard: -``` -microk8s enable hostpath-storage -microk8s enable dns -microk8s enable dashboard -``` + ``` + microk8s enable hostpath-storage + microk8s enable dns + microk8s enable dashboard + ``` 7. Enable the MetalLB service: -``` -microk8s enable metallb -``` - -At the prompt, enter a subnet which is not being used by your router. For example: - -``` -10.10.10.10-10.10.10.10 -``` - -Note: Unless you plan on adding multiple nodes, this range only needs one address. + ``` + microk8s enable metallb + ``` + + At the prompt, enter a subnet which is not being used by your router. For example: + + ``` + 10.10.10.10-10.10.10.10 + ``` + + Note: Unless you plan on adding multiple nodes, this range only needs one address. 8. After Microk8s is running, use `microk8s kubectl create token default` to create a Microk8s token. -9. In the new terminal window, use `microk8s kubectl port-forward -n kube-system service/kubernetes-dashboard 1443:443` to forward the dashboard port. +9. In the new terminal window, use + `microk8s kubectl port-forward -n kube-system service/kubernetes-dashboard 1443:443` + to forward the dashboard port. -You can now access your Kubernetes dashboard in a browser at https://localhost:1443/ using the token you created in step 2. + You can now access your Kubernetes dashboard in a browser at https://localhost:1443/ using the token you created in step 2. -10. The process in this terminal needs to keep running. Either background the process, or leave this terminal window open and open a new terminal window to continue working. +10. The process in this terminal needs to keep running. Either background the process, + or leave this terminal window open and open a new terminal window to continue working. ### Set Up DNS @@ -145,63 +149,67 @@ The ingress controller needs URLs to be mapped to services. There are a number o For this guide, we will use the simple case of editing the `/etc/hosts` file. -11. Edit the `/etc/hosts` file. Add one entry for the domain name of each service you intend to run. Add the canonical domain and point it to the IP address you gave MetalLB in step 3. +11. Edit the `/etc/hosts` file. Add one entry for the domain name of each service you + intend to run. Add the canonical domain and point it to the IP address you gave MetalLB in step 3. -For example, if you plan to run a service named `test-service` on the `diana.k8s` domain, add the following line: + For example, if you plan to run a service named `test-service` on the + `diana.k8s` domain, add the following line: -``` -10.10.10.10 test-service.diana.k8s -``` + ``` + 10.10.10.10 test-service.diana.k8s + ``` -This tells your computer that `test-service.diana.k8s` is at IP address `10.10.10.10`. Your computer will route all requests for `test-service.diana.k8s` to the Kubernetes cluster you set up at `10.10.10.10`, instead of looking for it on the public internet. - -Add one line for each service. Point each service to the same IP address. + This tells your computer that `test-service.diana.k8s` is at IP address + `10.10.10.10`. Your computer will route all requests for `test-service.diana.k8s` + to the Kubernetes cluster you set up at `10.10.10.10`, instead of looking for it on the public internet. + + Add one line for each service. Point each service to the same IP address. ### Prepare for Deployment 12. After you set up your Kubernetes cluster and configure DNS, configure the Diana backend with: -``` -diana configure-mq-backend OUTPUT_PATH -``` - -Replace `OUTPUT_PATH` with the directory where you want Diana to store its Helm charts and configurations. For example: - -``` -diana configure-mq-backend ~/neon_diana -``` + ``` + diana configure-mq-backend OUTPUT_PATH + ``` -Follow the prompts to provide any necessary configuration parameters. + Replace `OUTPUT_PATH` with the directory where you want Diana to store its Helm charts and configurations. For example: + + ``` + diana configure-mq-backend ~/neon_diana + ``` + + Follow the prompts to provide any necessary configuration parameters. -13. **Optional:** To add extra TCP ports (i.e. for RabbitMQ), update the `OUTPUT_PATH/ingress-nginx/values.yaml` file accordingly. +13. **Optional:** To add extra TCP ports (i.e. for RabbitMQ), update the + `OUTPUT_PATH/ingress-nginx/values.yaml` file accordingly. 14. Deploy the NGINX ingress: -``` -helm install ingress-nginx OUTPUT_PATH/ingress-common --namespace ingress-nginx --create-namespace -``` + ``` + helm install ingress-nginx OUTPUT_PATH/ingress-common --namespace ingress-nginx --create-namespace + ``` -15. Edit `OUTPUT_PATH/diana-backend-values.yaml` and update any necessary configuration. At minimum, you need to update the following parameters: +15. Edit `OUTPUT_PATH/diana-backend-values.yaml` and update any necessary configuration. + At minimum, you need to update the following parameters: -* `domain` Change this to the domain you added to the `/etc/hosts` file in step 11. -* `letsencrypt.email` If you are using a "real" domain, change this to the email address you want to use for the [Let's Encrypt](https://letsencrypt.org/) SSL certificate. For local testing, leave this as is. -* `letsencrypt.server` If you are using a "real" domain, change this to a valid Let's Encrypt server address, such as `https://acme-v02.api.letsencrypt.org/directory`. For local testing, leave this as is. + * `domain` Change this to the domain you added to the `/etc/hosts` file in step 11. + * `letsencrypt.email` If you are using a "real" domain, change this to the email address you want to use for the [Let's Encrypt](https://letsencrypt.org/) SSL certificate. For local testing, leave this as is. + * `letsencrypt.server` If you are using a "real" domain, change this to a valid Let's Encrypt server address, such as `https://acme-v02.api.letsencrypt.org/directory`. For local testing, leave this as is. ## Deploy the Diana Backend 16. Update the Helm dependency: -``` -helm dependency update OUTPUT_PATH/diana-backend -``` + ``` + helm dependency update OUTPUT_PATH/diana-backend + ``` 17. Use Helm to launch Diana: -``` -helm install diana-backend OUTPUT_PATH/test/diana-backend --namespace backend --create-namespace -``` - -This creates the `backend` namespace and launches Diana into that namespace. You can change this to any namespace name you prefer. You may want to use separate namespaces for test versus production deployments, to separate the Diana backend from other deployments, or both. - -``` + ``` + helm install diana-backend OUTPUT_PATH/test/diana-backend --namespace backend --create-namespace + ``` + + This creates the `backend` namespace and launches Diana into that namespace. You can change this to any namespace name you prefer. You may want to use separate namespaces for test versus production deployments, to separate the Diana backend from other deployments, or both. diff --git a/docs/neon_os/On_the_MarkII.md b/docs/neon_os/On_the_MarkII.md index e20ebafa..ad5fd2a5 100644 --- a/docs/neon_os/On_the_MarkII.md +++ b/docs/neon_os/On_the_MarkII.md @@ -1,9 +1,12 @@ # Neon OS on the Mark II -This section is for content specific to the Neon AI private personal assistant on the Mycroft Mark II Device +This section is for content specific to the Neon AI private personal assistant on the Mycroft Mark II Device. ## Making an Additional Boot Drive Summary: -To create an additional bootable drive using your Mark II, plug a second USB or an SSD into the right hand blue port, and say "Hey Neon, make bootable media" then follow the prompts. When finished, shut down your device, move the new drive into the first port and plug it back in. +To create an additional bootable drive using your Mark II, plug a second USB or +an SSD into the right hand blue port, and say "Hey Neon, make bootable media" +then follow the prompts. When finished, shut down your device, move the new drive +into the first port and plug it back in. ### Detailed Instructions **Supplies needed:** @@ -29,15 +32,18 @@ Select the alert by touching the alert icon, and then the words of the alert its 8. Unplug your original drive, and move the new drive over into the upper left USB port. 9. Plug power back in and Neon will boot up from the new drive. +> If you do not have a functioning Mark 2 device, see the + [Installation Instructions](./neon_os_installation.md#installing-a-downloaded-image-to-a-usb-drive). -### Troubleshooting and Tech Support with the Neon OS on the Mycroft Mark II + +### Troubleshooting and Tech Support Here is our troubleshooting walk-through, and I am also available for a personal tech support video call if you prefer more in-person assistance. **The first things to check are the power and your USB boot drive:** -​ **Start by unplugging your Mark II.** +**Start by unplugging your Mark II.** 1. The boot drive (either a USB memory key or SSD) should be securely plugged into the top left USB port, which is port 0. 2. There should be no other USB drives plugged in for the first boot. @@ -83,39 +89,11 @@ Here is our troubleshooting walk-through, and I am also available for a personal -**How to image or re-image a drive:** - -1. Download the Neon OS to your computer from [here](https://2222.us/app/files/neon_images/pi/mycroft_mark_2/recommended_mark_2.img.xz) - or use the link [here on the Neon.AI webpage](https://neon.ai/NeonAIforMycroftMarkII). This takes several minutes or more, depending on your connection speed. - -2. Download a (free) imaging program, if you don't have one already. We suggest [Raspberry Pi Imager](https://www.raspberrypi.com/software/) or [Balena Etcher](https://www.balena.io/etcher). - -3. Plug your blank or nonfunctional USB 3.0 or greater drive or SSD drive into your computer. - -4. Open your imager program (we suggest [Raspberry Pi Imager](https://www.raspberrypi.com/software/) or [Balena Etcher](https://www.balena.io/etcher)). - -5. If using Raspberry Pi Imager: - -6. 1. Under the 'Operating System' menu, select 'Use Custom'. - 2. Locate and select the Neon OS image you downloaded. - 3. Under 'Storage', select the drive you intend to write to. - 4. Click 'Write' and wait for the image to be written and verified. This takes several minutes, depending on your system. - -7. If using Balena Etcher - -8. 1. Under the '+', choose 'Flash from file'. - 2. Locate and select the Neon OS image you downloaded. - 3. Under 'Select target', select the drive you intend to write to. - 4. Click 'Flash' and wait for the image to be written and verified. This takes several minutes, depending on your system. - -9. Remove the USB or SSD drive from your computer. - -10. Disconnect power from your Mark II. - -11. Plug the newly imaged USB drive into the top left USB port on your Mark II (Port 0). - -12. Reconnect power to your Mark II. +#### How to image or re-image a drive +See the [Installation Instructions](./neon_os_installation.md#installing-a-downloaded-image-to-a-usb-drive) +for instructions on how to create a Neon OS drive. -13. After starting up, you will be guided through connecting to WiFi. +> After starting up, you will be guided through connecting to WiFi. diff --git a/docs/neon_os/neon_debos.md b/docs/neon_os/neon_debos.md index 0a20dc12..6bfda0d4 100644 --- a/docs/neon_os/neon_debos.md +++ b/docs/neon_os/neon_debos.md @@ -1,11 +1,11 @@ # Embedded device images -This repo contains [debos](https://github.com/go-debos/debos) recipes for building base images for embedded voice assistant +This repo contains [debos](https://github.com/go-debos/debos) recipes for building OS images for embedded voice assistant devices. Images generated here are intended to include all dependencies, drivers, and OS-level configuration that an assistant device might need, such as Camera Drivers, wifi-connect, QT packages, Vocal Fusion Drivers, etc. ## Available recipes -- debian-base-image-rpi4.yml: Debian Bookworm image with updated RPi kernel, RPi userland binaries, libcamera, - wifi-connect, SJ-201/Vocalfusion drivers, and a Splash Screen. +- `debian-neon-image.yml`: Default image that runs Neon on an edge device. +- `debian-node-image.yml`: Node image that connects to a central Neon instance. ## Repository Structure Each directory contains numbered files or directories; earlier numbers correspond to earlier build stages, and diff --git a/docs/neon_os/neon_image_recipe.md b/docs/neon_os/neon_image_recipe.md index 40300c31..529c413f 100644 --- a/docs/neon_os/neon_image_recipe.md +++ b/docs/neon_os/neon_image_recipe.md @@ -1,5 +1,5 @@ # neon-image-recipe -Make a Pi image from scratch. +*DEPRECATED PROJECT* Make a Pi image from scratch. - [Core Configuration](#core_configuration) - Base configuration of ubuntu server - [Network Manager](#network_manager) - Configures networking to allow for wifi configuration via [wifi-connect](https://github.com/balena-os/wifi-connect). diff --git a/docs/neon_os/neon_os_installation.md b/docs/neon_os/neon_os_installation.md index 2f3c1ea3..180ef2d8 100644 --- a/docs/neon_os/neon_os_installation.md +++ b/docs/neon_os/neon_os_installation.md @@ -48,6 +48,7 @@ Pi device. ## Using Neon OS To use Neon OS: + 1. Turn off and unplug your Mark2. 2. Remove any USB drives and plug your Neon OS drive into the upper left (blue) USB 3 port at the back of your Mark2. 3. Plug your Mark2 back in and [get started](./using_neon_os.md) \ No newline at end of file diff --git a/docs/neon_os/neon_os_updates.md b/docs/neon_os/neon_os_updates.md index c1835a74..96f8f96c 100644 --- a/docs/neon_os/neon_os_updates.md +++ b/docs/neon_os/neon_os_updates.md @@ -46,6 +46,7 @@ you can connect via SSH to start the update. ### Update via on-device terminal If you have a USB keyboard available, you can open a terminal on your Neon device to start the update. + 1. Connect a USB keyboard to your Neon device. 2. Press `ctrl`+`shift`+`F1` to open a terminal. 3. Tap or click on the terminal. diff --git a/docs/operations/git/triage_issues.md b/docs/operations/git/triage_issues.md index a75d775e..d37993cd 100644 --- a/docs/operations/git/triage_issues.md +++ b/docs/operations/git/triage_issues.md @@ -10,9 +10,11 @@ This process applies in the following situations: ### Process - Open the new issue on GitHub. - Read the issue comment and verify it is valid and complete. - - If this is a duplicate issue, apply the `duplicate` tag, close it with a comment linking the existing issue. - - If the issue is mis-categorized as a bug or feature, update the PR title. - - If the issue is in the wrong repository, transfer it as appropriate. + + - If this is a duplicate issue, apply the `duplicate` tag, close it with a comment linking the existing issue. + - If the issue is mis-categorized as a bug or feature, update the PR title. + - If the issue is in the wrong repository, transfer it as appropriate. + - If you know about more context (i.e. a chat thread or forum post), add it to the issue description. - If more information is needed for debugging, reply to the issue asking the author to clarify. - Verify the correct labels are applied (`bug`, `enhancement`, `documentation`, etc.) diff --git a/docs/operations/libraries/workflow_review_alpha.md b/docs/operations/libraries/workflow_review_alpha.md index 5a5457a5..5c2a5eb7 100644 --- a/docs/operations/libraries/workflow_review_alpha.md +++ b/docs/operations/libraries/workflow_review_alpha.md @@ -8,17 +8,18 @@ This process applies when reviewing a PR to the `dev` branch of a `library` modu - Complete the following. Note any issues in Review Comments before leaving a review to `Request Changes`. If there are no comments or the comments do not require code changes, then you *may* `Approve` the PR. - - Review changes to imports and verify dependency minimum versions are accurate. - - Ensure code changes have adequate unit test coverage. - - Ensure there are no breaking changes. - - If changes replace or could replace an existing method, ensure a deprecation - warning is logged in the replaced method (either `deprecated` decorator or - `log_deprecation` call). - - If tests are modified, make sure newly deprecated methods are still tested and - that changes do not remove any test cases. - - Highlight any added `TODO` or existing `TODO` comments related to the changes. - > It is up to the PR author and reviewer to decide if a `TODO` must be completed - before merging OR if an issue can be created to address it in a later PR. + + - Review changes to imports and verify dependency minimum versions are accurate. + - Ensure code changes have adequate unit test coverage. + - Ensure there are no breaking changes. + - If changes replace or could replace an existing method, ensure a deprecation + warning is logged in the replaced method (either `deprecated` decorator or + `log_deprecation` call). + - If tests are modified, make sure newly deprecated methods are still tested and + that changes do not remove any test cases. + - Highlight any added `TODO` or existing `TODO` comments related to the changes. + > It is up to the PR author and reviewer to decide if a `TODO` must be completed + before merging OR if an issue can be created to address it in a later PR. - Ensure the PR title and body are completed. Make any revisions necessary or work with the PR author to make those changes. diff --git a/docs/operations/libraries/workflow_stable_release.md b/docs/operations/libraries/workflow_stable_release.md index fb427589..133c8d94 100644 --- a/docs/operations/libraries/workflow_stable_release.md +++ b/docs/operations/libraries/workflow_stable_release.md @@ -8,18 +8,22 @@ This process applies when pushing a stable release for a `library`. - Verify the current alpha version is used in any projects that depend on the proposed changes. - Compare the latest alpha release to the latest stable release to determine the `release type`: - - If any breaking changes are present, the next version will be a `major` release. - - If any non-breaking functional changes are present, the next version will be a `minor` release. - - If no functional changes are present (i.e. only bugfixes or optimizations), the next version - will be a `patch` release. + + - If any breaking changes are present, the next version will be a `major` release. + - If any non-breaking functional changes are present, the next version will be a `minor` release. + - If no functional changes are present (i.e. only bugfixes or optimizations), the next version + will be a `patch` release. + - If this is a `major` release: - - Ensure that any deprecated methods had deprecation warnings in the previous - stable release. + + - Ensure that any deprecated methods had deprecation warnings in the previous + stable release. > If they did not, create a PR to replace the removed methods and add a deprecation warning and start this process over. - - Ensure that anything marked for deprecation in this release has been removed. + - Ensure that anything marked for deprecation in this release has been removed. > If there is code marked for deprecation in this release, create a PR to - remove the relevant code and unit tests and start this process over. + remove the relevant code and unit tests and start this process over. + - Look at package requirements to verify there are no alpha dependencies. > If there are any alpha dependencies, create an alpha release with no alpha dependencies and start this process over. diff --git a/docs/operations/skills/workflow_review.md b/docs/operations/skills/workflow_review.md index ccfec19f..9ceef55c 100644 --- a/docs/operations/skills/workflow_review.md +++ b/docs/operations/skills/workflow_review.md @@ -16,10 +16,12 @@ This process applies when reviewing a PR to the `dev` or `master` branch of any > It is up to the PR author and reviewer to decide if a `TODO` must be completed before merging OR if an issue can be created to address it in a later PR. - If reviewing a `Stable Release`: - - Validate there are no alpha dependencies - - Validate that the skill works as expected in an alpha deployment (i.e. Iris, HANA, or Neon OS). - If the skill is not deployed to any of those, test agaomst a local installation. - - Ensure the skill is not generating any `ERROR` or `WARNING` logs. + + - Validate there are no alpha dependencies + - Validate that the skill works as expected in an alpha deployment (i.e. Iris, HANA, or Neon OS). + If the skill is not deployed to any of those, test agaomst a local installation. + - Ensure the skill is not generating any `ERROR` or `WARNING` logs. + - Leave a review to `Approve` or `Request Changes`. If reviewing a draft or if unable to test changes, leave a `Comment` review indicating why it isn't an Approval, i.e. "Unable to test." or "Noted pending TODO" diff --git a/docs/operations/skills/workflow_stable_release.md b/docs/operations/skills/workflow_stable_release.md index 57725663..60a4a624 100644 --- a/docs/operations/skills/workflow_stable_release.md +++ b/docs/operations/skills/workflow_stable_release.md @@ -9,10 +9,12 @@ This process applies when pushing a stable release for a skill. `NeonCore` dependencies (if applicable). - Validate skill functionality in a Neon OS and/or Iris deployment (as applicable). - Compare the latest alpha release to the latest stable release to determine the `release type`: - - If any breaking changes are present, the next version will be a `major` release. - - If any non-breaking functional changes are present, the next version will be a `minor` release. - - If no functional changes are present (i.e. only bugfixes or optimizations), the next version - will be a `patch` release. + + - If any breaking changes are present, the next version will be a `major` release. + - If any non-breaking functional changes are present, the next version will be a `minor` release. + - If no functional changes are present (i.e. only bugfixes or optimizations), the next version + will be a `patch` release. + - Look at package requirements to verify there are no alpha dependencies. > If there are any alpha dependencies, create an alpha release with no alpha dependencies and start this process over. diff --git a/mkdocs.yml b/mkdocs.yml index bc2ed145..85a24a4a 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -32,8 +32,7 @@ nav: - Using Neon OS: neon_os/using_neon_os.md - Updating: neon_os/neon_os_updates.md - Neon OS on the Mark II: neon_os/On_the_MarkII.md - - Debos Base Images: neon_os/neon_debos.md - - Neon Image Recipes: neon_os/neon_image_recipe.md + - Debos Images: neon_os/neon_debos.md - Developer References: neon_os/developers.md - Tips: neon_os/tips.md - DIANA: