From 2465b14fcc6afaac6b9e0853e15501b497c863c4 Mon Sep 17 00:00:00 2001 From: EUGENE O'CONNOR Date: Fri, 27 Mar 2026 16:47:33 +0000 Subject: [PATCH 1/2] Issue: 666 - Add documentation for custom sample services - Added note in Notes section about BYO_SAMPLES feature - Created new 'Using Custom Sample Services' section with detailed instructions - Updated front matter with current date and year range - Documented requirements for custom sample services Signed-off-by: Eugene O'Connor Signed-off-by: EUGENE O'CONNOR --- docs/index.md | 38 ++++++++++++++++++++++++++++++++++++-- 1 file changed, 36 insertions(+), 2 deletions(-) diff --git a/docs/index.md b/docs/index.md index d7ab140..b9cd2ed 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,9 +1,9 @@ --- copyright: Contributors to the Open Horizon project -years: 2025 +years: 2025 - 2026 title: All-in-One Mgmt Hub description: Documentation for Horizon Management Hub -lastupdated: 2025-05-03 +lastupdated: 2026-03-27 nav_order: 2 parent: Management Hub --- @@ -23,6 +23,7 @@ Read the notes and then run the following command to deploy the Horizon componen - Support for Windows Subsystem for Linux (WSL 1&2) should also considered **experimental** at this time. WSL2's Ubuntu is based on `init.d` instead of the `systemd` used in standard Ubuntu distributions. The Open Horizon Agent requires `systemd` support so workarounds will simulate systemd usiing [this script](https://gist.githubusercontent.com/djfdyuruiry/6720faa3f9fc59bfdf6284ee1f41f950/raw/952347f805045ba0e6ef7868b18f4a9a8dd2e47a/install-sg.sh). This technique may not be stable and reliable. - Deployments can be customized by overriding environment variables in [deploy-mgmt-hub.sh](https://github.com/open-horizon/devops/blob/master/mgmt-hub/deploy-mgmt-hub.sh). The variables can be found near the top of the script, right after the usage message and command line parsing code. All `*_PW` and `*_TOKEN` environment variables and variables in the form `VAR_NAME=${VAR_NAME:-defaultvalue}` can be overridden. +- You can publish your own custom sample services during deployment by setting the `BYO_SAMPLES` environment variable to point to a text file containing GitHub URLs of your service repositories (one per line). For more information, see [Using custom sample services](#using-custom-samples). Preparation required for **Windows** operating systems: @@ -42,6 +43,39 @@ Ubuntu Server 20.04 and 22.04 are the preferred operating systems for evaluating If you wish to use the All-in-One environment in a virtual machine, please read the [VM setup notes](#setup-vm) further down for details. +### Using Custom Sample Services + +By default, the All-in-One deployment publishes a set of example services from the Open Horizon project. You can customize which sample services are published during deployment by using the `BYO_SAMPLES` (Bring Your Own Samples) environment variable. + +To use custom samples: + +1. Create a text file (for example, `samples.txt`) containing GitHub URLs of your service repositories, one per line: + + ```text + https://github.com/open-horizon/open-horizon-services/tree/main/web-helloworld-python + https://github.com/your-org/your-custom-service + ``` + {: codeblock} + +2. Set the `BYO_SAMPLES` environment variable to point to your file before running the deployment script: + + ```bash + export BYO_SAMPLES=samples.txt + curl -sSL https://raw.githubusercontent.com/open-horizon/devops/master/mgmt-hub/deploy-mgmt-hub.sh | bash + ``` + {: codeblock} + +**Requirements for custom sample services:** + +- Each service repository must contain a Makefile with the following targets: + - `publish-service`: Publishes the service definition to the Exchange + - `publish-service-policy`: Publishes the service policy + - `publish-deployment-policy`: Publishes the deployment policy +- Services must follow the Open Horizon service structure and conventions +- The deployment script will clone each repository and run `make publish-only` to publish the service + +**Note:** Custom samples are published in addition to the default Open Horizon example services. The default services include CPU, GPS, and Hello World examples. + ### What To Do Next #### Run the Automated Tests From 39dce33435337d9b781ef292453966f8f08ad712 Mon Sep 17 00:00:00 2001 From: EUGENE O'CONNOR Date: Mon, 30 Mar 2026 16:56:18 +0100 Subject: [PATCH 2/2] Issue: 666 - Refine custom samples documentation - Split first sentence into two for clarity - Removed 'one per line' detail from note - Removed 'Using Custom Sample Services' section per feedback Signed-off-by: Eugene O'Connor Signed-off-by: EUGENE O'CONNOR --- docs/index.md | 35 +---------------------------------- 1 file changed, 1 insertion(+), 34 deletions(-) diff --git a/docs/index.md b/docs/index.md index b9cd2ed..35d095e 100644 --- a/docs/index.md +++ b/docs/index.md @@ -23,7 +23,7 @@ Read the notes and then run the following command to deploy the Horizon componen - Support for Windows Subsystem for Linux (WSL 1&2) should also considered **experimental** at this time. WSL2's Ubuntu is based on `init.d` instead of the `systemd` used in standard Ubuntu distributions. The Open Horizon Agent requires `systemd` support so workarounds will simulate systemd usiing [this script](https://gist.githubusercontent.com/djfdyuruiry/6720faa3f9fc59bfdf6284ee1f41f950/raw/952347f805045ba0e6ef7868b18f4a9a8dd2e47a/install-sg.sh). This technique may not be stable and reliable. - Deployments can be customized by overriding environment variables in [deploy-mgmt-hub.sh](https://github.com/open-horizon/devops/blob/master/mgmt-hub/deploy-mgmt-hub.sh). The variables can be found near the top of the script, right after the usage message and command line parsing code. All `*_PW` and `*_TOKEN` environment variables and variables in the form `VAR_NAME=${VAR_NAME:-defaultvalue}` can be overridden. -- You can publish your own custom sample services during deployment by setting the `BYO_SAMPLES` environment variable to point to a text file containing GitHub URLs of your service repositories (one per line). For more information, see [Using custom sample services](#using-custom-samples). +- You can publish your own custom sample services during deployment by setting the `BYO_SAMPLES` environment variable to point to a text file containing GitHub URLs of your service repositories. Each URL must be on a separate line. Preparation required for **Windows** operating systems: @@ -43,39 +43,6 @@ Ubuntu Server 20.04 and 22.04 are the preferred operating systems for evaluating If you wish to use the All-in-One environment in a virtual machine, please read the [VM setup notes](#setup-vm) further down for details. -### Using Custom Sample Services - -By default, the All-in-One deployment publishes a set of example services from the Open Horizon project. You can customize which sample services are published during deployment by using the `BYO_SAMPLES` (Bring Your Own Samples) environment variable. - -To use custom samples: - -1. Create a text file (for example, `samples.txt`) containing GitHub URLs of your service repositories, one per line: - - ```text - https://github.com/open-horizon/open-horizon-services/tree/main/web-helloworld-python - https://github.com/your-org/your-custom-service - ``` - {: codeblock} - -2. Set the `BYO_SAMPLES` environment variable to point to your file before running the deployment script: - - ```bash - export BYO_SAMPLES=samples.txt - curl -sSL https://raw.githubusercontent.com/open-horizon/devops/master/mgmt-hub/deploy-mgmt-hub.sh | bash - ``` - {: codeblock} - -**Requirements for custom sample services:** - -- Each service repository must contain a Makefile with the following targets: - - `publish-service`: Publishes the service definition to the Exchange - - `publish-service-policy`: Publishes the service policy - - `publish-deployment-policy`: Publishes the deployment policy -- Services must follow the Open Horizon service structure and conventions -- The deployment script will clone each repository and run `make publish-only` to publish the service - -**Note:** Custom samples are published in addition to the default Open Horizon example services. The default services include CPU, GPS, and Hello World examples. - ### What To Do Next #### Run the Automated Tests