Skip to content

Retarget getting-started guides to the control-repo template - #445

Merged
tuxmea merged 3 commits into
OpenVoxProject:masterfrom
miharp:docs/control-repo-template
Aug 20, 2026
Merged

Retarget getting-started guides to the control-repo template#445
tuxmea merged 3 commits into
OpenVoxProject:masterfrom
miharp:docs/control-repo-template

Conversation

@miharp

@miharp miharp commented Aug 10, 2026

Copy link
Copy Markdown
Contributor

Part of #444

Points both getting-started guides at OpenVoxProject/control-repo-template instead of telling users to clone or fork puppetlabs/control-repo.

getting_started.markdown

  • Step 3 starts from the template: Use this template on GitHub, or clone-and-push for other Git hosts.
  • Dropped the branch-renaming caveat — the template's default branch is already production.

getting_started_local.markdown

  • Fixes a broken instruction: the guide claimed the crafty oss server container "runs r10k automatically on startup" via R10K_REMOTE. The openvoxserver:latest image has no r10k entrypoint logic, so that flow never deployed anything (details in Switch getting-started guides to OpenVoxProject/control-repo-template #444).
  • Restructured to match crafty's own r10k example: Step 1 runs a one-shot ghcr.io/voxpupuli/r10k container to populate ./openvox-code before the server starts (also gives the code directory the right ownership), Step 2 starts the stack, Step 3 enrolls the agent, and Step 4's iterate loop re-runs the same r10k container.
  • Running r10k first means the very first agent run reports the control repo's config_version (puppet-production-<commit>); the guide now shows that output.

Verification

  • Full flow tested live with Docker against the real template: r10k deploy → stack up → agent enroll/apply (Applied catalog, correct config_version on first run) → push-change iterate loop → teardown.

    Console output: r10k deploy, stack health, first agent run

    One-shot r10k container deploying the template into ./openvox-code:

    Running /container-entrypoint.d/10-create_r10k_config.sh
    INFO	 -> Deploying environment /etc/puppetlabs/code/environments/production
    WARN	 -> Overwriting local modifications to /etc/puppetlabs/code/environments/production
    INFO	 -> Environment production is now at 3a4163667db2ff8ef89878bb80e53b6e08cc7c4f
    INFO	 -> Using Puppetfile '/etc/puppetlabs/code/environments/production/Puppetfile'
    INFO	 -> Removing unmanaged path /etc/puppetlabs/code/environments/production/.resource_types/example.pp
    INFO	 -> Removing unmanaged path /etc/puppetlabs/code/environments/production/.resource_types
    

    Stack health after docker compose --profile openvox up -d:

    oss-openvoxdb-1	Up 10 seconds (healthy)
    oss-openvoxserver-1	Up 21 seconds (healthy)
    oss-postgres-1	Up 21 seconds (healthy)
    oss-puppetboard-1	Up Less than a second (health: starting)
    

    First agent run — pluginsync distributes the template's custom facts, types, and
    functions, and the catalog applies with the config_version of the deployed commit:

     Volume oss_agent-ssl Creating 
     Volume oss_agent-ssl Created 
     Container oss-testing-run-b655fc44f0b0 Creating 
     Container oss-testing-run-b655fc44f0b0 Created 
    Info: Refreshed CRL: 74:85:E3:AE:0A:56:41:AB:6E:D8:26:2F:38:4E:5F:A2:10:CD:F5:F5:95:0C:A5:B2:C9:25:A7:CD:7F:E6:8E:AD
    Info: Creating a new RSA SSL key for crafty-testing
    Info: csr_attributes file loading from /etc/puppetlabs/puppet/csr_attributes.yaml
    Info: Creating a new SSL certificate request for crafty-testing
    Info: Certificate Request fingerprint (SHA256): B7:F7:F0:12:A3:3A:04:42:65:98:5B:0F:90:B6:16:0C:57:19:4B:7D:16:1F:10:A0:38:8D:03:5B:69:0A:76:FE
    Info: Downloaded certificate for crafty-testing from https://puppet:8140/puppet-ca/v1
    Info: Using environment 'production'
    Info: Retrieving pluginfacts
    Notice: /File[/opt/puppetlabs/puppet/cache/facts.d/linux_simple_external_fact.sh]/ensure: defined content as '{sha256}6f5ec995046f6a3c4d02b7f09521e33e033a2ede0f6590ad6652891cb2c3fcf2'
    Notice: /File[/opt/puppetlabs/puppet/cache/facts.d/linux_structured_external_fact.py]/ensure: defined content as '{sha256}ecfc3d209b4210fa9869882eb1163247a95783a78c255e8c9cb4a0912a40fcb6'
    Notice: /File[/opt/puppetlabs/puppet/cache/facts.d/windows_external_fact.ps1]/ensure: defined content as '{sha256}df4ec6dc4a94bbfc62c36e009ca01237c9d7699896aa90d3c33a3430002e3d6b'
    Info: Retrieving plugin
    Notice: /File[/opt/puppetlabs/puppet/cache/lib/facter]/ensure: created
    Notice: /File[/opt/puppetlabs/puppet/cache/lib/facter/aggregate_custom_fact.rb]/ensure: defined content as '{sha256}0512a4411cd4c43c26f008c5ea3b0773a1bd2950c38339c714dcb8a9a77d9c50'
    Notice: /File[/opt/puppetlabs/puppet/cache/lib/facter/simple_custom_fact.rb]/ensure: defined content as '{sha256}9904cdeb42904c64ce47f5bd8d3503aef9aac730178676dffb77fe829816960f'
    Notice: /File[/opt/puppetlabs/puppet/cache/lib/facter/structured_custom_fact.rb]/ensure: defined content as '{sha256}4479912f7e100c07d3e2d11aa06381db627cb5e3f886c63c87f2611607362717'
    Notice: /File[/opt/puppetlabs/puppet/cache/lib/puppet]/ensure: created
    Notice: /File[/opt/puppetlabs/puppet/cache/lib/puppet/functions]/ensure: created
    Notice: /File[/opt/puppetlabs/puppet/cache/lib/puppet/functions/profile]/ensure: created
    Notice: /File[/opt/puppetlabs/puppet/cache/lib/puppet/functions/profile/upcase.rb]/ensure: defined content as '{sha256}a70a7d207923ea8289d16bcab19c881834bec8dfc80463fcfa88f4ff281f631e'
    Notice: /File[/opt/puppetlabs/puppet/cache/lib/puppet/functions/step.rb]/ensure: defined content as '{sha256}3b12fa629821ddf66621491700eb4e41344b3f4b2ceb67d0ec811d7234527687'
    Notice: /File[/opt/puppetlabs/puppet/cache/lib/puppet/provider]/ensure: created
    Notice: /File[/opt/puppetlabs/puppet/cache/lib/puppet/provider/example]/ensure: created
    Notice: /File[/opt/puppetlabs/puppet/cache/lib/puppet/provider/example/example.rb]/ensure: defined content as '{sha256}8480521833a8cc9787b3b738485409469483ac6be6651b446ae8e8b8be63a1e8'
    Notice: /File[/opt/puppetlabs/puppet/cache/lib/puppet/type]/ensure: created
    Notice: /File[/opt/puppetlabs/puppet/cache/lib/puppet/type/example.rb]/ensure: defined content as '{sha256}3a0c485e2203d981e2442801d5d1e5e7b56af3a2f93fe0a0690cf021e621d8a3'
    Info: Loading facts
    Warning: Facter: Command /opt/puppetlabs/puppet/cache/facts.d/windows_external_fact.ps1 completed with the following stderr message: /opt/puppetlabs/puppet/cache/facts.d/windows_external_fact.ps1: 7: Syntax error: "(" unexpected
    Warning: Facter: Command /opt/puppetlabs/puppet/cache/facts.d/linux_structured_external_fact.py completed with the following stderr message: env: 'python': No such file or directory
    env: use -[v]S to pass options in shebang lines
    Warning: Facter: Command /opt/puppetlabs/puppet/cache/facts.d/linux_simple_external_fact.sh completed with the following stderr message: /opt/puppetlabs/puppet/cache/facts.d/linux_simple_external_fact.sh: line 12: ruby: command not found
    Notice: Requesting catalog from puppet:8140 (172.18.0.3)
    Notice: Catalog compiled by puppet
    Info: Caching catalog for crafty-testing
    Info: Applying configuration version 'puppet-production-3a4163667db'
    Info: Creating state file /opt/puppetlabs/puppet/cache/state/state.yaml
    Notice: Applied catalog in 0.00 seconds
    

    The three Facter warnings come from the template's cross-platform example
    external facts running in a minimal Linux container (a .ps1 fact on Linux, and
    no python/ruby on the agent's PATH) — harmless, and gone on real nodes with
    those runtimes present.

  • bundle exec jekyll build passes; touched files are markdownlint-clean.

The _openvox_9x copies of both pages (currently identical, added on #430) pick up this change via the cutover content-drift port step.

Written with AI assistance (Claude); reviewed and tested by a human.

@miharp
miharp requested a review from a team as a code owner August 10, 2026 13:08
@miharp
miharp force-pushed the docs/control-repo-template branch 2 times, most recently from 751420d to e3bbcab Compare August 15, 2026 14:22
template, which provides a well-structured starting point:
Start from the
[OpenVoxProject/control-repo-template](https://github.com/OpenVoxProject/control-repo-template)
template, which provides a well-structured starting point built for OpenVox.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does this reads as "OpenVoxProject/control-repo-template template"? Maybe omit one "template" word.

@miharp
miharp force-pushed the docs/control-repo-template branch 2 times, most recently from 257757b to 6a9ed11 Compare August 20, 2026 13:45
miharp and others added 2 commits August 20, 2026 10:22
Point both guides at OpenVoxProject/control-repo-template instead of
telling users to clone or fork puppetlabs/control-repo. The template's
default branch is already production, so drop the branch-renaming
caveat.

Rework the crafty local guide's control-repo flow: the openvoxserver
image never ran r10k on startup (the R10K_REMOTE variable in the oss
compose file is unused), so deploy the code directory with the
voxpupuli/r10k container before starting the server, matching crafty's
own r10k example. Running r10k first also means the very first agent
run reports the config_version from the deployed commit. Flow verified
end-to-end against the live template with Docker.

The _openvox_9x copies pick up the same change via the cutover
content-drift port step (OpenVoxProject#430).

Part of OpenVoxProject#444

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Signed-off-by: Michael Harp <mike@mikeharp.com>
Co-authored-by: Claude <noreply@anthropic.com>
Signed-off-by: Michael Harp <mike@mikeharp.com>
@miharp
miharp force-pushed the docs/control-repo-template branch from de12a63 to 4374eb1 Compare August 20, 2026 14:22
@tuxmea
tuxmea enabled auto-merge August 20, 2026 19:45
@tuxmea
tuxmea disabled auto-merge August 20, 2026 19:46
@tuxmea
tuxmea merged commit ed1c198 into OpenVoxProject:master Aug 20, 2026
5 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants