Skip to content

Commit 0b85f00

Browse files
miharpclaude
miharp
and
claude
committed
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 <mike@mikeharp.com> Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> Signed-off-by: Michael Harp <mike@mikeharp.com>
1 parent 346be08 commit 0b85f00

4 files changed

Lines changed: 347 additions & 0 deletions

File tree

‎_data/nav/openvox_8x.yml‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,12 @@
99
link: "system_requirements.html"
1010
- text: About openvox-agent
1111
link: "about_agent.html"
12+
- text: Getting started
13+
items:
14+
- text: Getting started with OpenVox
15+
link: "getting_started.html"
16+
- text: Try OpenVox locally with crafty (experimental)
17+
link: "getting_started_local.html"
1218
- text: Quick start guides
1319
items:
1420
- text: NTP quick start guide

‎docs/_openvox_8x/getting_started.markdown‎

Lines changed: 203 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,203 @@
1+
---
2+
layout: default
3+
title: "Getting started with OpenVox"
4+
---
5+
6+
# Getting started with OpenVox
7+
8+
This guide walks you through the steps to go from a fresh installation to a working
9+
infrastructure managed with Puppet code. By the end you will have an OpenVox Server,
10+
enrolled agents, and a control repository deployed with r10k.
11+
12+
---
13+
14+
**Want to try the full workflow locally first?** See
15+
[Try OpenVox locally with crafty](./getting_started_local.html) for a Docker Compose
16+
environment that mirrors these steps without needing dedicated servers.
17+
18+
---
19+
20+
## Step 1: Install OpenVox Server
21+
22+
Install OpenVox Server on the node that will compile and serve **catalogs** to your
23+
agents. A catalog is the compiled set of resources and configuration that Puppet applies
24+
to a node.
25+
26+
Follow the [OpenVox Server installation guide](/openvox-server/latest/install_from_packages.html)
27+
for full instructions. When complete, the `puppetserver` service should be running and
28+
reachable on port 8140.
29+
30+
---
31+
32+
## Step 2: Install and enroll agents
33+
34+
Install `openvox-agent` on each node you want to manage, then connect it to the server.
35+
36+
1. Review the [pre-install tasks](./install_pre.html) for system requirements and
37+
network prerequisites.
38+
2. Install the agent:
39+
- [Linux](./install_linux.html)
40+
- [Windows](./install_windows.html)
41+
- [macOS](./install_osx.html)
42+
3. Run a test check-in on the agent. This submits a certificate signing request (CSR)
43+
to the server — OpenVox uses mutual TLS so both sides must trust each other before
44+
the server will issue a catalog:
45+
46+
```bash
47+
sudo /opt/puppetlabs/bin/puppet agent --test
48+
```
49+
50+
4. Sign the certificate on the server to approve the agent:
51+
52+
```bash
53+
sudo /opt/puppetlabs/bin/puppetserver ca list
54+
sudo /opt/puppetlabs/bin/puppetserver ca sign --certname <AGENT_CERTNAME>
55+
```
56+
57+
---
58+
59+
## Step 3: Set up a control repository
60+
61+
A control repository is a Git repository that holds all your Puppet environments.
62+
Each branch becomes an [environment](./environments_about.html) on the server. r10k reads this repository and
63+
deploys branches to `/etc/puppetlabs/code/environments/`.
64+
65+
### Create the repository
66+
67+
Start by cloning the [puppetlabs/control-repo](https://github.com/puppetlabs/control-repo)
68+
template, which provides a well-structured starting point:
69+
70+
```bash
71+
git clone https://github.com/puppetlabs/control-repo.git
72+
cd control-repo
73+
```
74+
75+
Create a new empty repository on your Git host (GitHub, GitLab, Gitea, or any host your
76+
server can reach), then point the clone at it. Note that OpenVox uses `production` as
77+
the default environment — make sure your repository's default branch is named
78+
`production`, not `main`:
79+
80+
```bash
81+
git remote remove origin
82+
git remote add origin <YOUR_REPO_URL>
83+
git push -u origin production
84+
```
85+
86+
The template's key files are:
87+
88+
- **`Puppetfile`** — lists modules r10k installs into the environment. Add modules from
89+
the Puppet Forge here as your infrastructure grows.
90+
- **`environment.conf`** — configures the module path to include the `site-modules/`
91+
directory alongside Forge modules.
92+
- **`site-modules/`** — where your own roles, profiles, and custom modules live.
93+
- **`manifests/site.pp`** — the main manifest, which is the entry point for node
94+
classification.
95+
- **`data/`** — Hiera data files, pre-configured with a basic hierarchy.
96+
97+
### Install r10k
98+
99+
[r10k](https://github.com/puppetlabs/r10k) is a code deployment tool that reads your
100+
control repository and installs each branch as a Puppet environment, along with any
101+
modules listed in its Puppetfile.
102+
103+
On the OpenVox Server, install r10k using the Ruby runtime that ships with OpenVox:
104+
105+
```bash
106+
sudo /opt/puppetlabs/puppet/bin/gem install r10k
107+
```
108+
109+
---
110+
111+
Once your control repo is deployed and your infrastructure is established, consider
112+
managing r10k with the [`puppet/r10k`](https://forge.puppet.com/modules/puppet/r10k)
113+
Forge module. It installs r10k and manages `r10k.yaml` as Puppet resources, so
114+
changes to your r10k configuration go through the same code review and deployment
115+
workflow as everything else.
116+
117+
---
118+
119+
### Configure r10k
120+
121+
Create the r10k configuration directory and a minimal `r10k.yaml`:
122+
123+
```bash
124+
sudo mkdir -p /etc/puppetlabs/r10k
125+
```
126+
127+
**`/etc/puppetlabs/r10k/r10k.yaml`:**
128+
129+
```yaml
130+
cachedir: '/var/cache/r10k'
131+
sources:
132+
control:
133+
remote: 'https://github.com/your-org/control-repo'
134+
basedir: '/etc/puppetlabs/code/environments'
135+
```
136+
137+
Replace the `remote` value with the URL of your control repository. If the server
138+
needs an SSH key to clone from your Git host, configure that key for the root user
139+
before running r10k.
140+
141+
### Deploy your first environment
142+
143+
Deploy all branches from the control repository:
144+
145+
```bash
146+
sudo /opt/puppetlabs/puppet/bin/r10k deploy environment -v
147+
```
148+
149+
When complete, `/etc/puppetlabs/code/environments/production/` will contain the
150+
files from your repository's `production` branch.
151+
152+
---
153+
154+
## Step 4: Write and apply Puppet code
155+
156+
With a deployed environment you are ready to write Puppet code and apply it to nodes.
157+
To confirm the full loop is working, add a `notify` resource to
158+
`manifests/site.pp` in your control repository:
159+
160+
```puppet
161+
node default {
162+
notify { 'Hello from OpenVox!':
163+
message => 'Your first Puppet catalog change is working.',
164+
}
165+
}
166+
```
167+
168+
Commit and push the change to the `production` branch of your control repository,
169+
redeploy with r10k, then run the agent:
170+
171+
```bash
172+
sudo /opt/puppetlabs/puppet/bin/r10k deploy environment production -v
173+
sudo /opt/puppetlabs/bin/puppet agent --test
174+
```
175+
176+
You should see a `Notice: Your first Puppet catalog change is working.` line in the
177+
output confirming the agent applied the updated catalog.
178+
179+
From here, a few places to go deeper:
180+
181+
- **[Hello world! Quick start guide](./quick_start_helloworld.html)** — write your first
182+
class and apply it to a node.
183+
- **[Roles and profiles](./the_roles_and_profiles_method.html)** — the recommended pattern
184+
for structuring code in larger deployments.
185+
- **[Installing modules](./modules_installing.html)** — add community modules from the
186+
Puppet Forge to your Puppetfile and deploy them with r10k.
187+
- **[Introduction to Hiera](./hiera_intro.html)** — separate your data from your code
188+
using Hiera.
189+
190+
---
191+
192+
## What's next?
193+
194+
- **Add more environments** — create a new branch in your control repository and run
195+
`r10k deploy environment -v` to deploy it. Use environments for testing changes
196+
before promoting to production.
197+
- **Automate r10k deploys** — use the [`r10k::webhook` class](https://forge.puppet.com/modules/puppet/r10k)
198+
from the `puppet/r10k` module to set up a webhook that triggers `r10k deploy environment` on every push.
199+
- **Expand your node inventory** — install agents on additional nodes and assign
200+
them classes in `manifests/site.pp` or through [node definitions](./lang_node_definitions.html).
201+
- **Classify nodes at scale** — use an [External Node Classifier](./nodes_external.html)
202+
to assign classes from an external source instead of maintaining node definitions
203+
in `manifests/site.pp`.

‎docs/_openvox_8x/getting_started_local.markdown‎

Lines changed: 131 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,131 @@
1+
---
2+
layout: default
3+
title: "Try OpenVox locally with crafty (experimental)"
4+
---
5+
6+
# Try OpenVox locally with crafty (experimental)
7+
8+
Before setting up production infrastructure you can run the full OpenVox stack —
9+
server, OpenVoxDB, an agent, and r10k — locally using Docker Compose via
10+
[voxpupuli/crafty](https://github.com/voxpupuli/crafty). This mirrors the steps in the
11+
[Getting started guide](./getting_started.html) and is a fast way to get familiar with
12+
the workflow before committing to a real installation.
13+
14+
## Prerequisites
15+
16+
- Docker and Docker Compose installed and running.
17+
- A fork of [puppetlabs/control-repo](https://github.com/puppetlabs/control-repo) on
18+
your Git host. Open the repository on GitHub and click **Fork** to create a copy
19+
under your own account. You will point the server at your fork so you can push
20+
changes and see them applied in Step 4.
21+
22+
Clone crafty and change into the OSS example directory:
23+
24+
```bash
25+
git clone https://github.com/voxpupuli/crafty
26+
cd crafty/openvox/oss
27+
```
28+
29+
---
30+
31+
## Step 1: Start the OpenVox Server
32+
33+
The server container runs r10k automatically on startup, so configure your control
34+
repository before bringing it up. Open `compose.yaml`, find the commented-out
35+
`R10K_REMOTE` line, uncomment it, and update it to point at your fork:
36+
37+
```yaml
38+
R10K_REMOTE: https://github.com/<YOUR_ORG>/control-repo.git
39+
```
40+
41+
Then start the stack. The server takes a minute to become healthy as it bootstraps
42+
its CA and runs r10k — start it now and continue reading while it initialises:
43+
44+
```bash
45+
docker compose --profile openvox up -d
46+
```
47+
48+
Check readiness at any point with:
49+
50+
```bash
51+
docker compose ps
52+
```
53+
54+
---
55+
56+
## Step 2: Install and enroll agents
57+
58+
Once all containers report healthy, run the agent container. crafty enables autosigning,
59+
so the certificate is approved automatically — no manual signing step is needed:
60+
61+
```bash
62+
docker compose --profile test run --remove-orphans testing agent -t
63+
```
64+
65+
The agent connects to the server, has its certificate signed, and applies the catalog
66+
compiled from your control repository. A successful run ends with output like:
67+
68+
```text
69+
Notice: Catalog compiled by puppet
70+
Notice: Applied catalog in 0.01 seconds
71+
```
72+
73+
---
74+
75+
## Step 3: Verify your control repository
76+
77+
The server runs r10k during startup and deploys each branch of your control repository
78+
as a Puppet environment. Verify the `production` environment was deployed:
79+
80+
```bash
81+
docker exec oss-openvoxserver-1 ls /etc/puppetlabs/code/environments/
82+
```
83+
84+
You should see a `production/` directory containing the files from your fork's
85+
`production` branch.
86+
87+
---
88+
89+
## Step 4: Write and apply Puppet code
90+
91+
The agent run in Step 2 already compiled and applied a catalog from the `production`
92+
environment. To iterate on your Puppet code:
93+
94+
1. Push a change to the `production` branch of your fork. For example, add a `notify`
95+
resource to `manifests/site.pp`:
96+
97+
```puppet
98+
node default {
99+
notify { 'Hello from OpenVox!':
100+
message => 'Your first Puppet catalog change is working.',
101+
}
102+
}
103+
```
104+
105+
2. Trigger r10k to redeploy:
106+
107+
```bash
108+
docker exec oss-openvoxserver-1 r10k deploy environment production -v
109+
```
110+
111+
3. Run the agent again to apply the updated catalog:
112+
113+
```bash
114+
docker compose --profile test run --remove-orphans testing agent -t
115+
```
116+
117+
---
118+
119+
## Tear down
120+
121+
```bash
122+
./clean.sh
123+
```
124+
125+
---
126+
127+
## Next steps
128+
129+
Once you are comfortable with the workflow, follow the
130+
[Getting started guide](./getting_started.html) to set up a production installation
131+
with real servers and agents.

‎docs/_openvox_8x/install_linux.markdown‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -84,3 +84,10 @@ and reachable.
8484

8585
If you are replacing Puppet packages on an existing host, back up `/etc/puppetlabs/`
8686
before you begin. OpenVox continues to use that configuration tree after installation.
87+
88+
## What's next?
89+
90+
You now have a running server and at least one enrolled agent. The next step is to set up
91+
a control repository so you can manage Puppet code across your infrastructure. See the
92+
[Getting started guide](./getting_started.html) for a walkthrough of control repo setup
93+
with r10k and writing your first Puppet code.

0 commit comments

Comments
 (0)