fix: inaccuracies in installation guides on 26.04 - #306
Merged
Conversation
Add .github/agents/ custom agent definitions, one per installation guide, capturing the live-testing methodology (real LXD containers/VMs, real Juju models, real FIPS/Ubuntu Pro tokens) used to audit and fix these guides for 26.04+, so future re-tests can be run consistently.
The manual-installation guide's "Configure Landscape services" section dropped guidance on running multiple instances of a service when the obsolete /etc/default/landscape-server RUN_MSGSERVER="N" style flags were removed (those don't exist on 26.04). Restore equivalent guidance using the current mechanism: the `workers` field in each service's section of /etc/landscape/service.conf (see canonical/landscape/settings/service.py's ServiceSettingsMixin and canonical/landscape/runtime/worker_runner.py in landscape-server, which spawns exactly `workers` processes per service). Per-service enable/disable is unaffected and still systemd/lsctl-based (no `enabled` field exists in service.conf), so that part of the guide was already accurate.
Undo an earlier accidental revert of the Global Administrator account section wording, which was an intentional edit.
Undo an earlier accidental revert of the shortened postgresql-contrib note in manual-installation.md, which was an intentional edit.
There was a problem hiding this comment.
Pull request overview
Updates Landscape installation/setup documentation to match behavior verified by live end-to-end testing on Ubuntu 26.04+ (and related supported releases), and adds per-guide “tester agent” definitions to make future re-validation repeatable.
Changes:
- Corrects multiple installation guide steps/config examples for current packages and charms (PostgreSQL packaging,
service.confsections/keys, systemd/service management, HAProxy channel/routing behavior). - Improves client install/registration guidance for TLS trust (documenting
--ssl-public-keyfor self-signed/private CAs) and clarifies config-management registration behavior. - Adds
.github/agents/tester-*.agent.mdfiles capturing the live-testing methodology per guide.
Reviewed changes
Copilot reviewed 21 out of 21 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/reuse/landscape-ppa-name-description.md | Adds a reusable description for a LANDSCAPE_PPA_NAME variable (suffix form) used by the LXD/cloud-init flow. |
| docs/how-to-guides/landscape-installation-and-set-up/quickstart-installation.md | Aligns post-install access wording with the guide’s $FQDN variable usage. |
| docs/how-to-guides/landscape-installation-and-set-up/manual-installation.md | Fixes 26.04-specific package guidance, service.conf section/key naming, and updates service/worker configuration guidance. |
| docs/how-to-guides/landscape-installation-and-set-up/juju-installation.md | Clarifies legacy vs 26.04+ charm/bundle deployment paths and HAProxy hostname-based routing behavior. |
| docs/how-to-guides/landscape-installation-and-set-up/juju-ha-installation.md | Updates HAProxy channel guidance, bundle examples, and documents hostname routing requirements for access. |
| docs/how-to-guides/landscape-installation-and-set-up/install-on-fips-compliant-machines.md | Adds apt pinning guidance to avoid dependency mismatches under Ubuntu Pro/ESM on FIPS-oriented installs. |
| docs/how-to-guides/landscape-installation-and-set-up/install-landscape-in-an-air-gapped-or-offline-environment.md | Adjusts offline installation steps to include required snaps and installs local .deb sets via APT for dependency resolution. |
| docs/how-to-guides/landscape-installation-and-set-up/install-landscape-client.md | Documents --ssl-public-key for registration against self-signed/private CA servers and clarifies when it’s required. |
| docs/how-to-guides/landscape-installation-and-set-up/install-in-a-lxd-container.md | Fixes the cloud-init variable name used to select the Landscape PPA and switches to a matching reusable include. |
| docs/how-to-guides/landscape-installation-and-set-up/disa-stig.md | Fixes multiple hardening/config examples (TLS SANs, loopback addressing, RabbitMQ TLS/node settings, and removes stale knowledge DB references). |
| docs/how-to-guides/landscape-installation-and-set-up/configure-landscape-client.md | Replaces the config-management registration flow description with a landscape-config --silent-based approach. |
| .github/agents/tester-quickstart-installation.agent.md | Adds a repeatable live-test procedure for the quickstart guide. |
| .github/agents/tester-manual-installation.agent.md | Adds a repeatable live-test procedure for the manual installation guide. |
| .github/agents/tester-juju-installation.agent.md | Adds a repeatable live-test procedure for the Juju installation guide. |
| .github/agents/tester-juju-ha-installation.agent.md | Adds a repeatable live-test procedure for the Juju HA installation guide. |
| .github/agents/tester-install-landscape-client.agent.md | Adds a repeatable live-test procedure for the landscape-client install/registration guide. |
| .github/agents/tester-install-in-a-lxd-container.agent.md | Adds a repeatable live-test procedure for the LXD/cloud-init installation guide. |
| .github/agents/tester-fips-install.agent.md | Adds a repeatable live-test procedure for the FIPS-compliant install guide. |
| .github/agents/tester-disa-stig.agent.md | Adds a repeatable live-test procedure for the DISA STIG guide. |
| .github/agents/tester-configure-landscape-client.agent.md | Adds a repeatable live-test procedure for the client configuration guide. |
| .github/agents/tester-airgap-install.agent.md | Adds a repeatable live-test procedure for the offline/air-gapped install guide. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
# Conflicts: # docs/how-to-guides/landscape-installation-and-set-up/disa-stig.md
- juju-ha-installation.md: fix broken {ref} cross-reference (missing
required space before the target, e.g. "text <target>" not
"text<target>"), which prevented the reference from resolving.
- disa-stig.md: remove two orphaned `landscape_maintenance` references.
Upstream's PR canonical#281 already removed the `landscape_maintenance`/
`set_user` extension content from this guide (it narrowed scope to
FIPS-certified 22.04 only), so these leftover mentions from our
branch's older content referenced a role the guide no longer sets up
anywhere, which is what the review correctly flagged as inconsistent.
jansdhillon
added a commit
to jansdhillon/landscape-documentation
that referenced
this pull request
Aug 19, 2026
- juju-ha-installation.md: fix broken {ref} cross-reference (missing
required space before the target, e.g. "text <target>" not
"text<target>"), which prevented the reference from resolving.
- disa-stig.md: remove two orphaned `landscape_maintenance` references.
Upstream's PR canonical#281 already removed the `landscape_maintenance`/
`set_user` extension content from this guide (it narrowed scope to
FIPS-certified 22.04 only), so these leftover mentions from our
branch's older content referenced a role the guide no longer sets up
anywhere, which is what the review correctly flagged as inconsistent.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
jansdhillon
force-pushed
the
lndeng-4552
branch
from
August 19, 2026 21:16
410df3a to
09de9ac
Compare
…nstallation.md Remove confusing latest/stable vs latest/beta channel guidance for the deprecated legacy landscape-scalable bundle. State plainly that the bundle is deprecated and should not be used for new deployments, consolidating what were two separate 'deprecated' sections into one.
The merge with upstream/main (536b2f7) accidentally took upstream's stale <LANDSCAPE_IP_ADDRESS>/32 placeholder for the pg_hba.conf cert-auth example, discarding our branch's correct loopback-based fix. Since this all-in-one deployment guide has Landscape connect to PostgreSQL via host = localhost, the pg_hba.conf entries must match 127.0.0.1/::1, not the server's external IP - live-verified in a real LXD container that the placeholder-IP approach breaks connections while the loopback entries work.
YanisaHS
requested changes
Aug 20, 2026
YanisaHS
reviewed
Aug 20, 2026
Collaborator
|
I only scanned through the agents tests part though, LMK if you want me to look at that closer. Edit: Thinking about it again, should the test agents just be in another PR so someone (maybe me, but presumably an engineer) can look at them more closely? |
- configure-landscape-client.md: remove redundant note about landscape-config triggering registration (already covered elsewhere), and move the --silent advantage explanation up to the 'Use landscape-config' section where --silent is first introduced. - disa-stig.md: reword the ambiguous 'all-in-one deployment' phrase to explicitly state Landscape, PostgreSQL, and RabbitMQ run on the same host; move the [schema] SSL settings explanation out of a service.conf comment and into the surrounding prose. - install-landscape-client.md: remove an em dash per reviewer preference. - juju-installation.md: remove em dashes from the HAProxy routing bullets, and clarify the landscape-scalable bundle was deprecated in 26.04 (rather than just currently deprecated with no date) to make clear when. - manual-installation.md: clarify the postgresql-contrib note is about PostgreSQL 18 (packaged with Resolute), not a blanket Ubuntu-version based limitation, since users can install other PostgreSQL versions.
# Conflicts: # docs/.custom_wordlist.txt
Confirmed against the actual snapcraft.yaml sources in canonical/landscape-go (outbox/snap/snapcraft.yaml and debarchive/snap/snapcraft.yaml): both snaps declare base: core22, not core24. Also confirmed via 'snap info' against a locally installed landscape-outbox snap. This corrects the air-gapped/offline installation guide's snap download/install commands, and resolves YanisaHS's PR canonical#306 review comment questioning the FIPS core22 vs core24 discrepancy - these snaps are in fact core22-based, consistent with the FIPS guide's existing core22 requirement.
Contributor
Author
Sure |
…al#310 The .github/agents/tester-*.agent.md files were split out into PR canonical#310 per review feedback, so they can be reviewed independently of the documentation fixes in this PR.
YanisaHS
approved these changes
Aug 21, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
https://warthogs.atlassian.net/browse/LNDENG-4552
I also added some agents for testing in the future https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/create-custom-agents-for-cli
Every installation/setup guide under
docs/how-to-guides/landscape-installation-and-set-up/was live-tested end-to-end against real targets (LXD containers, real Juju models via../landscape-server-operator, and a real FIPS-enabled Ubuntu Pro VM) rather than reviewed by reading alone. Bugs found this way were fixed; the diff was then minimized to keep only independently-confirmed changes.Bugs found & fixed
manual-installation.mdpostgresql-contribdoesn't exist on Resolute - package guidance made release-agnostic.[appserver], not[landscape]./etc/default/landscape-serverno longer hasRUN_ALL/RUN_MSGSERVERflags on current packages - onlyRUN_CRON/UPGRADE_SCHEMAremain.install-landscape-client.md--ssl-public-key; the guide didn't document this and registration silently failed without it.install-in-a-lxd-container.mdLANDSCAPE_PPA), so the profile-driven install silently used the wrong PPA.configure-landscape-client.mdRUN=1) registration flow description didn't match observed behavior on current releases - corrected and simplified.juju-installation.md/juju-ha-installation.mdlandscape-scalableon Charmhub has no26.04/*channel - clarified legacy vs. current-channel deploy paths.2.8/edge→2.8/stable.quickstart-installation.mddisa-stig.mdDNS:localhostSAN or localhost TLS connections fail verification.pg_hba.confexample using the server's real IP is wrong for this all-in-one guide - corrected to loopback addressing.NODENAME=rabbit@localhostand a localhost TLS listener.landscape-standalone-knowledgepackage references.26.04branch (canonical/landscape-server#1478), so no workaround note was needed - the straightforward cert-auth-from-the-start flow is correct as documented.install-landscape-in-an-air-gapped-or-offline-environment.mdinstall-on-fips-compliant-machines.mdConfirmed false alarms (no changes needed)
debarchive-repository-management.mdandconfigure-outbox.mdwere reviewed and tested; no inaccuracies found.configure-postfix.md,configure-rabbitmq.md,create-saas-account.mdreviewed; no inaccuracies found.Validation
make htmlrun clean after every change.Tooling added
.github/agents/tester-*.agent.md: one custom tester agent definition per guide, capturing the live-testing methodology (real LXD containers/VMs, real Juju models, real FIPS/Pro tokens) used for this audit, so future re-tests of these guides can be run consistently.