From 5fafca326177b8b5ff2d762078d3185faa337ad5 Mon Sep 17 00:00:00 2001 From: Lynn Duke Date: Mon, 31 Mar 2025 14:34:02 -0500 Subject: [PATCH 1/3] add missing setup documentation --- README.md | 141 ++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 105 insertions(+), 36 deletions(-) diff --git a/README.md b/README.md index dea3d86..4137815 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,101 @@ ![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/deeep-network/ansible_collections/badge) -# Setting Up Local Machine +# Overview +Developing with bedrock requires a virtual machine, a habitat account, and other dependencies. +- [Overview](#overview) +- [Virtual Machine Setup](#virtual-machine-setup) + - [Background](#background) + - [macos (apple silicon)](#macos-apple-silicon) + - [orbstack - docs](#orbstack---docs) + - [linux/windows/macos (intel)](#linuxwindowsmacos-intel) + - [multipass - docs](#multipass---docs) + - [linux/windows/macos](#linuxwindowsmacos) + - [UTM - docs](#utm---docs) +- [Create Chef Habitat Account](#create-chef-habitat-account) + - [Create a Habitat Builder Account](#create-a-habitat-builder-account) + - [Create an Origin](#create-an-origin) + - [Create Personal Access Token](#create-personal-access-token) +- [Install pipx](#install-pipx) + - [MacOS](#macos) + - [Linux](#linux) + - [Other Install Methods](#other-install-methods) + - [Install Ansible](#install-ansible) + - [Verify Ansible collections](#verify-ansible-collections) + - [Install Molecule](#install-molecule) + - [Post Installation](#post-installation) +- [Getting Started](#getting-started) +- [Next Steps](#next-steps) + +# Virtual Machine Setup +You'll need to install virtualization software to run and develop on a virtual machine created by bedrock. + +## Background +On the DeEEP Device - the main Ansible Controller is the Device itself which in turn can manage the VM's (via Incus). Each VM is also an independent Ansible Controller for itself. This setup requires every role to be `localhost` first when developed. This isn't the normal way Ansible is meant to be used (push model) so there are some gotchas and things we do that are slightly out of the norm. Being `localhost` first however provides the VMs the ability to configure themselves when necessary. It's also important to note that if it works via `localhost` it will always work being pushed (not always the case in reverse). -We leverage pipx to ensure that all programs and librarys we depend on can be installed globally and isolated with venvs out of the box. It's also supported by MacOS, Linux, and Windows. +> [!NOTE] For testing, we skip the Incus layer. Meaning the Ansible Controller for tests is your local machine (acting like the Device). Pushing directly to the VM running locally (managed by Orbstack, multipass, KVM, or LXD). This is meant to simplify the testing process. Especially since MacOS support for intel based CPU architecture is not well supported. + +As such, depending on your development environment pick the most convenient virtualization software. Usually based on OS and CPU + +--- + +### macos (apple silicon) + +#### orbstack - [docs](https://docs.orbstack.dev/install) + +```bash +brew install orbstack +``` + +--- + +### linux/windows/macos (intel) + +#### multipass - [docs](https://multipass.run/install) + +```bash +brew install --cask multipass +``` + +```bash +snap install multipass +``` + +--- + +### linux/windows/macos + +> not well tested, tread carefully + +#### UTM - [docs](https://mac.getutm.app/) + +```bash +brew install --cask utm +``` + +# Create Chef Habitat Account +### Create a Habitat Builder Account + +For local development of Chef Habitat packages you’ll want to create your own Chef Habitat Builder account. It’s similar to a GitHub or a Docker repo, but stores Habitat Packages. (.hart files) -## Install pipx +Set up your builder account at [bldr.habitat.sh](http://bldr.habitat.sh). (You’ll need a GitHub account to sign up) + +### Create an Origin + +Once signed into your habitat builder account, create a new origin by clicking the ‘Create Origin’ button. This origin will be used for local development of habitat packages. + +Name your origin (perhaps use your full name). Set to “Private artifacts” and click “Save & Continue” + +### Create Personal Access Token + +Head to your profile and create an personal access token. Set this token to the environment on your host machine. + +```bash +export HAB_AUTH_TOKEN='your-token-here' +``` + +# Install pipx + +We leverage pipx to ensure that all programs and librarys we depend on can be installed globally and isolated with venvs out of the box. It's also supported by MacOS, Linux, and Windows. ### MacOS @@ -59,48 +150,26 @@ or source ~/.zshrc ``` ---- - -## Setup for Local Virtual Machines -On the DeEEP Device - the main Ansible Controller is the Device itself which in turn can manage the VM's (via Incus). Each VM is also an independent Ansible Controller for itself. This setup requires every role to be `localhost` first when developed. This isn't the normal way Ansible is meant to be used (push model) so there are some gotchas and things we do that are slightly out of the norm. Being `localhost` first however provides the VMs the ability to configure themselves when necessary. It's also important to note that if it works via `localhost` it will always work being pushed (not always the case in reverse). -> [!NOTE] For testing, we skip the Incus layer. Meaning the Ansible Controller for tests is your local machine (acting like the Device). Pushing directly to the VM running locally (managed by Orbstack, multipass, KVM, or LXD). This is meant to simplify the testing process. Especially since MacOS support for intel based CPU architecture is not well supported. +# Getting Started -As such, depending on your development environment pick the most convenient virtualization software. Usually based on OS and CPU +> **Important**: Before proceeding, ensure you have set your `HAB_AUTH_TOKEN` environment variable. This token is required for authenticating with the Habitat Builder service and is expected to be set before continuing. +> +> ```bash +> export HAB_AUTH_TOKEN='your-token-here' +> ``` ---- - -### macos (apple silicon) - -#### orbstack - [docs](https://docs.orbstack.dev/install) +From the root of the bedrock repo run the following command: ```bash -brew install orbstack +molecule create ``` ---- +This will create the virtual machine and install the needed dependencies. -### linux/windows/macos (intel) +# Next Steps -#### multipass - [docs](https://multipass.run/install) +Develop a new service with [coral-reef](https://github.com/deeep-network/coral-reef) -```bash -brew install --cask multipass -``` -```bash -snap install multipass -``` - ---- - -### linux/windows/macos - -> not well tested, tread carefully - -#### UTM - [docs](https://mac.getutm.app/) - -```bash -brew install --cask utm -``` From ce181126e40393e387de38a23a6f9e0b7acc512f Mon Sep 17 00:00:00 2001 From: Lynn Duke Date: Mon, 31 Mar 2025 14:45:16 -0500 Subject: [PATCH 2/3] add troubleshooting step and format cleanup --- README.md | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 4137815..a917a5b 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,7 @@ ![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/deeep-network/ansible_collections/badge) -# Overview -Developing with bedrock requires a virtual machine, a habitat account, and other dependencies. - [Overview](#overview) - [Virtual Machine Setup](#virtual-machine-setup) - - [Background](#background) - [macos (apple silicon)](#macos-apple-silicon) - [orbstack - docs](#orbstack---docs) - [linux/windows/macos (intel)](#linuxwindowsmacos-intel) @@ -26,10 +23,13 @@ Developing with bedrock requires a virtual machine, a habitat account, and other - [Getting Started](#getting-started) - [Next Steps](#next-steps) +# Overview + +Developing with bedrock requires a virtual machine, a habitat account, and other dependencies. + # Virtual Machine Setup -You'll need to install virtualization software to run and develop on a virtual machine created by bedrock. +You'll need to install virtualization software on your host machine to run bedrock. -## Background On the DeEEP Device - the main Ansible Controller is the Device itself which in turn can manage the VM's (via Incus). Each VM is also an independent Ansible Controller for itself. This setup requires every role to be `localhost` first when developed. This isn't the normal way Ansible is meant to be used (push model) so there are some gotchas and things we do that are slightly out of the norm. Being `localhost` first however provides the VMs the ability to configure themselves when necessary. It's also important to note that if it works via `localhost` it will always work being pushed (not always the case in reverse). > [!NOTE] For testing, we skip the Incus layer. Meaning the Ansible Controller for tests is your local machine (acting like the Device). Pushing directly to the VM running locally (managed by Orbstack, multipass, KVM, or LXD). This is meant to simplify the testing process. Especially since MacOS support for intel based CPU architecture is not well supported. @@ -166,7 +166,11 @@ From the root of the bedrock repo run the following command: molecule create ``` -This will create the virtual machine and install the needed dependencies. +This will create the virtual machine and install the needed dependencies. You can follow the creation process (or troubleshoot it) on the VM: + +```bash +sudo tail -f /var/log/cloud-init-output.log +``` # Next Steps From 59ebfc9d9d5bd636d4956d85437831832b4f269b Mon Sep 17 00:00:00 2001 From: Lynn Duke Date: Mon, 31 Mar 2025 15:18:04 -0500 Subject: [PATCH 3/3] add orb cli help --- README.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index a917a5b..64ae018 100644 --- a/README.md +++ b/README.md @@ -166,12 +166,13 @@ From the root of the bedrock repo run the following command: molecule create ``` -This will create the virtual machine and install the needed dependencies. You can follow the creation process (or troubleshoot it) on the VM: +This will create the virtual machine and install the needed dependencies. You can follow the creation process (or troubleshoot it) on the VM. For example, if using OrbStack, you can shell into the VM with the orb cli and follow the cloud-init logs: ```bash -sudo tail -f /var/log/cloud-init-output.log +> orb -m bedrock -u nerdnode +$bedrock> sudo tail -f /var/log/cloud-init-output.log ``` - +[More Orb Commands](https://docs.orbstack.dev/machines/commands) # Next Steps Develop a new service with [coral-reef](https://github.com/deeep-network/coral-reef)