feat: add getting-started trail and crafty local testing guide

_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

docs/_openvox_8x/getting_started.markdown

@@ -0,0 +1,198 @@
+---
+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 <AGENT_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 <YOUR_REPO_URL>
+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
+```
+
+> **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
+
+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://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).
+- **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`.

docs/_openvox_8x/getting_started_local.markdown

@@ -0,0 +1,135 @@
+---
+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/<YOUR_ORG>/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](./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
+```
+
+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/
+```
+
+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.
+
+---
+
+## 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
+```
+
+This removes all containers and volumes, giving you a clean slate for the next run.
+
+---
+
+## 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.

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.