diff --git a/_data/nav/openvox_8x.yml b/_data/nav/openvox_8x.yml index 6cd79bfb4..1f7038321 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..2f799973e --- /dev/null +++ b/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 + ``` + +--- + +## 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 +``` + +> **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`. diff --git a/docs/_openvox_8x/getting_started_local.markdown b/docs/_openvox_8x/getting_started_local.markdown new file mode 100644 index 000000000..141af0224 --- /dev/null +++ b/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//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. 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.