From 0b85f0080fdfd3d70c3224f62836ebd738b857c9 Mon Sep 17 00:00:00 2001 From: Michael Harp Date: Wed, 27 May 2026 14:26:46 -0400 Subject: [PATCH 1/2] feat: add getting-started trail and crafty local testing guide Adds a four-step getting-started walkthrough (issue #214) covering OpenVox Server install, agent enrollment, control repo setup with r10k, and writing first Puppet code. Includes a companion guide for running the full stack locally with crafty/Docker Compose. Adds a "What's next?" pointer to install_linux so post-install readers find the trail. Nav updated with a new "Getting started" section. Part of #214 Signed-off-by: Michael Harp Co-Authored-By: Claude Sonnet 4.6 Signed-off-by: Michael Harp --- _data/nav/openvox_8x.yml | 6 + docs/_openvox_8x/getting_started.markdown | 203 ++++++++++++++++++ .../getting_started_local.markdown | 131 +++++++++++ docs/_openvox_8x/install_linux.markdown | 7 + 4 files changed, 347 insertions(+) create mode 100644 docs/_openvox_8x/getting_started.markdown create mode 100644 docs/_openvox_8x/getting_started_local.markdown diff --git a/_data/nav/openvox_8x.yml b/_data/nav/openvox_8x.yml index 0b755337b..8f9c9106b 100644 --- a/_data/nav/openvox_8x.yml +++ b/_data/nav/openvox_8x.yml @@ -9,6 +9,12 @@ link: "system_requirements.html" - text: About openvox-agent link: "about_agent.html" +- text: Getting started + items: + - text: Getting started with OpenVox + link: "getting_started.html" + - text: Try OpenVox locally with crafty (experimental) + link: "getting_started_local.html" - text: Quick start guides items: - text: NTP quick start guide diff --git a/docs/_openvox_8x/getting_started.markdown b/docs/_openvox_8x/getting_started.markdown new file mode 100644 index 000000000..c9f5cfc90 --- /dev/null +++ b/docs/_openvox_8x/getting_started.markdown @@ -0,0 +1,203 @@ +--- +layout: default +title: "Getting started with OpenVox" +--- + +# Getting started with OpenVox + +This guide walks you through the steps to go from a fresh installation to a working +infrastructure managed with Puppet code. By the end you will have an OpenVox Server, +enrolled agents, and a control repository deployed with r10k. + +--- + +**Want to try the full workflow locally first?** See +[Try OpenVox locally with crafty](./getting_started_local.html) for a Docker Compose +environment that mirrors these steps without needing dedicated servers. + +--- + +## Step 1: Install OpenVox Server + +Install OpenVox Server on the node that will compile and serve **catalogs** to your +agents. A catalog is the compiled set of resources and configuration that Puppet applies +to a node. + +Follow the [OpenVox Server installation guide](/openvox-server/latest/install_from_packages.html) +for full instructions. When complete, the `puppetserver` service should be running and +reachable on port 8140. + +--- + +## Step 2: Install and enroll agents + +Install `openvox-agent` on each node you want to manage, then connect it to the server. + +1. Review the [pre-install tasks](./install_pre.html) for system requirements and + network prerequisites. +2. Install the agent: + - [Linux](./install_linux.html) + - [Windows](./install_windows.html) + - [macOS](./install_osx.html) +3. Run a test check-in on the agent. This submits a certificate signing request (CSR) + to the server — OpenVox uses mutual TLS so both sides must trust each other before + the server will issue a catalog: + + ```bash + sudo /opt/puppetlabs/bin/puppet agent --test + ``` + +4. Sign the certificate on the server to approve the agent: + + ```bash + sudo /opt/puppetlabs/bin/puppetserver ca list + sudo /opt/puppetlabs/bin/puppetserver ca sign --certname + ``` + +--- + +## Step 3: Set up a control repository + +A control repository is a Git repository that holds all your Puppet environments. +Each branch becomes an [environment](./environments_about.html) on the server. r10k reads this repository and +deploys branches to `/etc/puppetlabs/code/environments/`. + +### Create the repository + +Start by cloning the [puppetlabs/control-repo](https://github.com/puppetlabs/control-repo) +template, which provides a well-structured starting point: + +```bash +git clone https://github.com/puppetlabs/control-repo.git +cd control-repo +``` + +Create a new empty repository on your Git host (GitHub, GitLab, Gitea, or any host your +server can reach), then point the clone at it. Note that OpenVox uses `production` as +the default environment — make sure your repository's default branch is named +`production`, not `main`: + +```bash +git remote remove origin +git remote add origin +git push -u origin production +``` + +The template's key files are: + +- **`Puppetfile`** — lists modules r10k installs into the environment. Add modules from + the Puppet Forge here as your infrastructure grows. +- **`environment.conf`** — configures the module path to include the `site-modules/` + directory alongside Forge modules. +- **`site-modules/`** — where your own roles, profiles, and custom modules live. +- **`manifests/site.pp`** — the main manifest, which is the entry point for node + classification. +- **`data/`** — Hiera data files, pre-configured with a basic hierarchy. + +### Install r10k + +[r10k](https://github.com/puppetlabs/r10k) is a code deployment tool that reads your +control repository and installs each branch as a Puppet environment, along with any +modules listed in its Puppetfile. + +On the OpenVox Server, install r10k using the Ruby runtime that ships with OpenVox: + +```bash +sudo /opt/puppetlabs/puppet/bin/gem install r10k +``` + +--- + +Once your control repo is deployed and your infrastructure is established, consider +managing r10k with the [`puppet/r10k`](https://forge.puppet.com/modules/puppet/r10k) +Forge module. It installs r10k and manages `r10k.yaml` as Puppet resources, so +changes to your r10k configuration go through the same code review and deployment +workflow as everything else. + +--- + +### Configure r10k + +Create the r10k configuration directory and a minimal `r10k.yaml`: + +```bash +sudo mkdir -p /etc/puppetlabs/r10k +``` + +**`/etc/puppetlabs/r10k/r10k.yaml`:** + +```yaml +cachedir: '/var/cache/r10k' +sources: + control: + remote: 'https://github.com/your-org/control-repo' + basedir: '/etc/puppetlabs/code/environments' +``` + +Replace the `remote` value with the URL of your control repository. If the server +needs an SSH key to clone from your Git host, configure that key for the root user +before running r10k. + +### Deploy your first environment + +Deploy all branches from the control repository: + +```bash +sudo /opt/puppetlabs/puppet/bin/r10k deploy environment -v +``` + +When complete, `/etc/puppetlabs/code/environments/production/` will contain the +files from your repository's `production` branch. + +--- + +## Step 4: Write and apply Puppet code + +With a deployed environment you are ready to write Puppet code and apply it to nodes. +To confirm the full loop is working, add a `notify` resource to +`manifests/site.pp` in your control repository: + +```puppet +node default { + notify { 'Hello from OpenVox!': + message => 'Your first Puppet catalog change is working.', + } +} +``` + +Commit and push the change to the `production` branch of your control repository, +redeploy with r10k, then run the agent: + +```bash +sudo /opt/puppetlabs/puppet/bin/r10k deploy environment production -v +sudo /opt/puppetlabs/bin/puppet agent --test +``` + +You should see a `Notice: Your first Puppet catalog change is working.` line in the +output confirming the agent applied the updated catalog. + +From here, a few places to go deeper: + +- **[Hello world! Quick start guide](./quick_start_helloworld.html)** — write your first + class and apply it to a node. +- **[Roles and profiles](./the_roles_and_profiles_method.html)** — the recommended pattern + for structuring code in larger deployments. +- **[Installing modules](./modules_installing.html)** — add community modules from the + Puppet Forge to your Puppetfile and deploy them with r10k. +- **[Introduction to Hiera](./hiera_intro.html)** — separate your data from your code + using Hiera. + +--- + +## What's next? + +- **Add more environments** — create a new branch in your control repository and run + `r10k deploy environment -v` to deploy it. Use environments for testing changes + before promoting to production. +- **Automate r10k deploys** — use the [`r10k::webhook` class](https://forge.puppet.com/modules/puppet/r10k) + from the `puppet/r10k` module to set up a webhook that triggers `r10k deploy environment` on every push. +- **Expand your node inventory** — install agents on additional nodes and assign + them classes in `manifests/site.pp` or through [node definitions](./lang_node_definitions.html). +- **Classify nodes at scale** — use an [External Node Classifier](./nodes_external.html) + to assign classes from an external source instead of maintaining node definitions + in `manifests/site.pp`. diff --git a/docs/_openvox_8x/getting_started_local.markdown b/docs/_openvox_8x/getting_started_local.markdown new file mode 100644 index 000000000..9aa7ca08e --- /dev/null +++ b/docs/_openvox_8x/getting_started_local.markdown @@ -0,0 +1,131 @@ +--- +layout: default +title: "Try OpenVox locally with crafty (experimental)" +--- + +# Try OpenVox locally with crafty (experimental) + +Before setting up production infrastructure you can run the full OpenVox stack — +server, OpenVoxDB, an agent, and r10k — locally using Docker Compose via +[voxpupuli/crafty](https://github.com/voxpupuli/crafty). This mirrors the steps in the +[Getting started guide](./getting_started.html) and is a fast way to get familiar with +the workflow before committing to a real installation. + +## Prerequisites + +- Docker and Docker Compose installed and running. +- A fork of [puppetlabs/control-repo](https://github.com/puppetlabs/control-repo) on + your Git host. Open the repository on GitHub and click **Fork** to create a copy + under your own account. You will point the server at your fork so you can push + changes and see them applied in Step 4. + +Clone crafty and change into the OSS example directory: + +```bash +git clone https://github.com/voxpupuli/crafty +cd crafty/openvox/oss +``` + +--- + +## Step 1: Start the OpenVox Server + +The server container runs r10k automatically on startup, so configure your control +repository before bringing it up. Open `compose.yaml`, find the commented-out +`R10K_REMOTE` line, uncomment it, and update it to point at your fork: + +```yaml +R10K_REMOTE: https://github.com//control-repo.git +``` + +Then start the stack. The server takes a minute to become healthy as it bootstraps +its CA and runs r10k — start it now and continue reading while it initialises: + +```bash +docker compose --profile openvox up -d +``` + +Check readiness at any point with: + +```bash +docker compose ps +``` + +--- + +## Step 2: Install and enroll agents + +Once all containers report healthy, run the agent container. crafty enables autosigning, +so the certificate is approved automatically — no manual signing step is needed: + +```bash +docker compose --profile test run --remove-orphans testing agent -t +``` + +The agent connects to the server, has its certificate signed, and applies the catalog +compiled from your control repository. A successful run ends with output like: + +```text +Notice: Catalog compiled by puppet +Notice: Applied catalog in 0.01 seconds +``` + +--- + +## Step 3: Verify your control repository + +The server runs r10k during startup and deploys each branch of your control repository +as a Puppet environment. Verify the `production` environment was deployed: + +```bash +docker exec oss-openvoxserver-1 ls /etc/puppetlabs/code/environments/ +``` + +You should see a `production/` directory containing the files from your fork's +`production` branch. + +--- + +## Step 4: Write and apply Puppet code + +The agent run in Step 2 already compiled and applied a catalog from the `production` +environment. To iterate on your Puppet code: + +1. Push a change to the `production` branch of your fork. For example, add a `notify` + resource to `manifests/site.pp`: + + ```puppet + node default { + notify { 'Hello from OpenVox!': + message => 'Your first Puppet catalog change is working.', + } + } + ``` + +2. Trigger r10k to redeploy: + + ```bash + docker exec oss-openvoxserver-1 r10k deploy environment production -v + ``` + +3. Run the agent again to apply the updated catalog: + + ```bash + docker compose --profile test run --remove-orphans testing agent -t + ``` + +--- + +## Tear down + +```bash +./clean.sh +``` + +--- + +## Next steps + +Once you are comfortable with the workflow, follow the +[Getting started guide](./getting_started.html) to set up a production installation +with real servers and agents. diff --git a/docs/_openvox_8x/install_linux.markdown b/docs/_openvox_8x/install_linux.markdown index 1e8df65ba..4d626ca65 100644 --- a/docs/_openvox_8x/install_linux.markdown +++ b/docs/_openvox_8x/install_linux.markdown @@ -84,3 +84,10 @@ and reachable. If you are replacing Puppet packages on an existing host, back up `/etc/puppetlabs/` before you begin. OpenVox continues to use that configuration tree after installation. + +## What's next? + +You now have a running server and at least one enrolled agent. The next step is to set up +a control repository so you can manage Puppet code across your infrastructure. See the +[Getting started guide](./getting_started.html) for a walkthrough of control repo setup +with r10k and writing your first Puppet code. From cb91f26d41bbf3cacd29d73a2635a8b9c2f00750 Mon Sep 17 00:00:00 2001 From: Michael Harp Date: Thu, 28 May 2026 06:45:48 -0400 Subject: [PATCH 2/2] docs: address review feedback on getting-started trail - Wrap long line in Step 3 control repo intro - Convert puppet/r10k aside from HR-sandwich to blockquote tip - Point r10k::webhook link directly to GitHub README anchor - Note default container name in crafty Step 3 - Explain what clean.sh removes in Tear down section - Link "autosigning" in crafty guide to ssl_autosign doc Co-Authored-By: Claude Sonnet 4.6 Signed-off-by: Michael Harp --- docs/_openvox_8x/getting_started.markdown | 19 +++++++------------ .../getting_started_local.markdown | 8 ++++++-- 2 files changed, 13 insertions(+), 14 deletions(-) diff --git a/docs/_openvox_8x/getting_started.markdown b/docs/_openvox_8x/getting_started.markdown index c9f5cfc90..2f799973e 100644 --- a/docs/_openvox_8x/getting_started.markdown +++ b/docs/_openvox_8x/getting_started.markdown @@ -59,8 +59,8 @@ Install `openvox-agent` on each node you want to manage, then connect it to the ## Step 3: Set up a control repository A control repository is a Git repository that holds all your Puppet environments. -Each branch becomes an [environment](./environments_about.html) on the server. r10k reads this repository and -deploys branches to `/etc/puppetlabs/code/environments/`. +Each branch becomes an [environment](./environments_about.html) on the server. +r10k reads this repository and deploys branches to `/etc/puppetlabs/code/environments/`. ### Create the repository @@ -106,15 +106,10 @@ On the OpenVox Server, install r10k using the Ruby runtime that ships with OpenV sudo /opt/puppetlabs/puppet/bin/gem install r10k ``` ---- - -Once your control repo is deployed and your infrastructure is established, consider -managing r10k with the [`puppet/r10k`](https://forge.puppet.com/modules/puppet/r10k) -Forge module. It installs r10k and manages `r10k.yaml` as Puppet resources, so -changes to your r10k configuration go through the same code review and deployment -workflow as everything else. - ---- +> **Tip:** Once your infrastructure is established, consider managing r10k with the +> [`puppet/r10k`](https://forge.puppet.com/modules/puppet/r10k) Forge module. It +> installs r10k and manages `r10k.yaml` as Puppet resources, so changes to your r10k +> configuration go through the same code review and deployment workflow as everything else. ### Configure r10k @@ -194,7 +189,7 @@ From here, a few places to go deeper: - **Add more environments** — create a new branch in your control repository and run `r10k deploy environment -v` to deploy it. Use environments for testing changes before promoting to production. -- **Automate r10k deploys** — use the [`r10k::webhook` class](https://forge.puppet.com/modules/puppet/r10k) +- **Automate r10k deploys** — use the [`r10k::webhook` class](https://github.com/voxpupuli/puppet-r10k#webhook) from the `puppet/r10k` module to set up a webhook that triggers `r10k deploy environment` on every push. - **Expand your node inventory** — install agents on additional nodes and assign them classes in `manifests/site.pp` or through [node definitions](./lang_node_definitions.html). diff --git a/docs/_openvox_8x/getting_started_local.markdown b/docs/_openvox_8x/getting_started_local.markdown index 9aa7ca08e..141af0224 100644 --- a/docs/_openvox_8x/getting_started_local.markdown +++ b/docs/_openvox_8x/getting_started_local.markdown @@ -55,8 +55,9 @@ docker compose ps ## Step 2: Install and enroll agents -Once all containers report healthy, run the agent container. crafty enables autosigning, -so the certificate is approved automatically — no manual signing step is needed: +Once all containers report healthy, run the agent container. crafty enables +[autosigning](./ssl_autosign.html), so the certificate is approved automatically — +no manual signing step is needed: ```bash docker compose --profile test run --remove-orphans testing agent -t @@ -81,6 +82,7 @@ as a Puppet environment. Verify the `production` environment was deployed: docker exec oss-openvoxserver-1 ls /etc/puppetlabs/code/environments/ ``` +The container is named `oss-openvoxserver-1` by default; adjust if yours differs. You should see a `production/` directory containing the files from your fork's `production` branch. @@ -122,6 +124,8 @@ environment. To iterate on your Puppet code: ./clean.sh ``` +This removes all containers and volumes, giving you a clean slate for the next run. + --- ## Next steps