docs: publicize systemd orchestrator#432
Conversation
Update concepts, installation index, and the Docker Swarm installation guide to present systemd alongside Docker Swarm as a deployment model. PLAT-658
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughThe documentation now presents Docker Swarm and systemd as Control Plane deployment models, with separate installation, configuration, mTLS, navigation, and upgrade guidance. ChangesOrchestrator Documentation
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Up to standards ✅🟢 Issues
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/index.md`:
- Line 17: Synchronize systemd deployment wording with its documented preview
status: update docs/version.md accordingly, revise the feature claim in
docs/index.md lines 17-17, and update docs/installation/index.md lines 5-15 to
describe systemd consistently as a preview deployment model.
In `@docs/installation/installation.md`:
- Line 10: Update the high-availability documentation link in the installation
text to replace the generic “here” label with descriptive text identifying the
linked deployment best practices, while preserving the existing destination.
In `@docs/prerequisites/concepts.md`:
- Line 48: Update the feature-description sentence in the concepts documentation
to avoid claiming complete parity across all orchestrators. State that they
share the core API and common capabilities, while explicitly qualifying
systemd-specific limitations or linking to the relevant limitations section.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 2e1d690d-7e5d-434a-9e0c-486ebb9e46ea
📒 Files selected for processing (4)
docs/index.mddocs/installation/index.mddocs/installation/installation.mddocs/prerequisites/concepts.md
GabriellePoncey
changed the title
GabriellePoncey
changed the title
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/installation/configuration.md`:
- Around line 53-54: Update the configuration table entries for
systemd.pgbackrest_path and systemd.patroni_path to document their runtime
defaults as /usr/bin/pgbackrest and /usr/bin/patroni respectively, while
preserving that both values must be non-empty.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 537d2287-e2ff-4618-8c54-f833193d3a82
📒 Files selected for processing (7)
docs/index.mddocs/installation/configuration.mddocs/installation/installation.mddocs/prerequisites/concepts.mddocs/prerequisites/index.mddocs/using/upgrade-db.mddocs/version.md
🚧 Files skipped from review as they are similar to previous changes (2)
- docs/index.md
- docs/installation/installation.md
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/installation/mtls.md`:
- Around line 35-51: Update the deployment-specific instructions in the mTLS
documentation: scope the existing service restart guidance explicitly to
systemd, and add that Docker Swarm users must redeploy the stack after changing
environment variables or volume mounts.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 02a57cdc-7b76-46bf-afde-8a926e5e763b
📒 Files selected for processing (3)
docs/installation/configuration.mddocs/installation/mtls.mddocs/installation/upgrading.md
🚧 Files skipped from review as they are similar to previous changes (1)
- docs/installation/configuration.md
|
|
||
| * [Installing via Docker Swarm](swarm-installation.md) covers deploying the Control Plane as Docker containers across a set of hosts. This is the default, production-ready installation method. | ||
|
|
||
| * [Installing via System Packages](systemd-installation.md) covers installing the Control Plane as a native Linux service using RPM or Deb packages, without Docker. This uses systemd to manage Postgres instances directly on the host. This is a **preview feature**. |
There was a problem hiding this comment.
I'd flip the order that you present here and lead with systemd, and not frame it as "without Docker". It should be listed above it.
| | **How it works** | Control Plane and Postgres run as Docker containers | Control Plane and Postgres run as native Linux services | | ||
| | **Best for** | Container-based infrastructure | Bare metal or VMs without Docker | | ||
| | **Package format** | Docker image | RPM or Deb system packages | | ||
| | **Status** | Generally available | Preview | |
There was a problem hiding this comment.
systemd won't be in Preview when the next release lands, so let's adjust that here and elsewhere in this PR.
| @@ -1,8 +1,13 @@ | |||
| # Installing the pgEdge Control Plane | |||
| # Installing the pgEdge Control Plane (Docker Swarm) | |||
There was a problem hiding this comment.
I would mirror the naming of the systemd one here - i would use with <orchestrator rather than the parenthesis
| @@ -1,7 +1,6 @@ | |||
| # Upgrading the Control Plane | |||
|
|
|||
| # Upgrading the Control Plane (Docker Swarm) | |||
There was a problem hiding this comment.
I would split these into two articles similar to installation.
| **Docker Swarm** is the default orchestrator. Each host corresponds to a Docker Swarm node, with the Control Plane running as a Docker container. Each database instance runs as a separate Docker container within the Swarm environment. | ||
|
|
||
| We plan to support additional orchestration approaches in the near future, including direct deployment to hosts without containerization. | ||
| **systemd** is available as an alternative orchestrator for deployments on bare metal or VMs where you prefer not to use containers. With the systemd orchestrator, the Control Plane runs as a native Linux service and manages each Postgres instance as a systemd unit. This is a good fit for organizations with existing infrastructure built around system package managers, or for environments where standard Linux processes are preferred over containers. See [Installing via System Packages](../installation/systemd-installation.md) for setup instructions. |
There was a problem hiding this comment.
Another spot to flip the order - systemd is not an alternative and i dont think we should frame either as the default. systemd should be listed first and framed equally.
| We plan to support additional orchestration approaches in the near future, including direct deployment to hosts without containerization. | ||
| **systemd** is available as an alternative orchestrator for deployments on bare metal or VMs where you prefer not to use containers. With the systemd orchestrator, the Control Plane runs as a native Linux service and manages each Postgres instance as a systemd unit. This is a good fit for organizations with existing infrastructure built around system package managers, or for environments where standard Linux processes are preferred over containers. See [Installing via System Packages](../installation/systemd-installation.md) for setup instructions. | ||
|
|
||
| Both orchestrators share the same core API and capabilities: declarative database management, Patroni-based high availability, and pgBackRest backup/restore integration. The systemd orchestrator has some limitations not present in Docker Swarm; see the [systemd installation guide](../installation/systemd-installation.md#limitations) for details. |
There was a problem hiding this comment.
I would remove this line about limitations - that context isn't needed on this page from my view.
|
|
||
| The pgEdge Control Plane supports: | ||
|
|
||
| - flexible orchestrator support: run Postgres as Docker containers via **Docker Swarm**, or as native Linux services via **systemd** on bare metal or VMs without containers. |
There was a problem hiding this comment.
I would flip the order here again and put this towards the end. This page should lead with the features of the system, not with the installation method.
| - Installing Control Plane: | ||
| - Deployment Options: installation/index.md | ||
| - Installing Control Plane on Your Host: installation/installation.md | ||
| - Installing Control Plane on Your Host: installation/swarm-installation.md |
There was a problem hiding this comment.
The names here should be the same as the title of the page (in general, unless there it a length problem).
| ``` | ||
|
|
||
|
|
||
| //include with installation guide |
There was a problem hiding this comment.
Is this an artifact for a future PR? or just accidentally included?
|
Ordering is mixed. Most pages lead with systemd, but the comparison table at index.md:9 still puts Docker Swarm in the first column (and disagrees with the bullets at index.md:19 to 21 in the same file), and version.md lists Docker Swarm first at line 16 before systemd at line 18. Please put systemd first in the index.md:9 table and swap version.md:16 and 18 so the order matches the rest. |
| The Control Plane is architected to support multiple orchestrators, giving you flexibility in how database instances are deployed and managed. | ||
|
|
||
| For the Docker Swarm orchestrator, each host corresponds to a Docker Swarm node, with the Control Plane running as a Docker container. Each database instance runs as a separate Docker container within the Swarm environment. | ||
| **systemd**he Control Plane and Postgres instances run as native Linux services managed by systemd units. This is a good fit for organizations that prefer system package managers over containers. See [Installing via System Packages](../installation/systemd-installation.md) for setup instructions. |
There was a problem hiding this comment.
Can you fix this. The word "The" got mangled
| # Installing the pgEdge Control Plane via System Packages | ||
|
|
||
| !!! warning "Preview Feature" | ||
| !!! tip "Preview Feature" |
There was a problem hiding this comment.
This page still has a "Preview Feature" tip,
| @@ -1,8 +1,13 @@ | |||
| # Installing the pgEdge Control Plane | |||
| # Installing the pgEdge Control Plane with Swarm | |||
There was a problem hiding this comment.
The four install/upgrade page titles name the orchestrators four different ways: "with Swarm" (swarm-installation.md:1), "via System Packages" (systemd-installation.md:1), "with Docker Swarm" (swarm-upgrading.md:1), and "with systemd" (systemd-upgrading.md:1). Please use one pattern, for example "with Docker Swarm" and "with systemd" for both install and upgrade, and update the matching mkdocs.yml nav labels (lines 62, 64, 65, 67) to keep them in sync.
|
Thanks for the updates. Ordering, titles, and Preview look good now. Two things from last round are still open: concepts.md:46 ("Docker Swarm Orchestrator in which…" is missing a verb, should be "is an orchestrator") and systemd-installation.md:30 (typos "Postgress" and "it's", should be "Postgres" and "its"). Fix those two and it is good to go. Everything technical still checks out. |
3 participants
Summary
Update concepts, installation index, and the Docker Swarm installation guide to present systemd alongside Docker Swarm as a deployment model.
Changes
-Rewrite the Orchestrators section in concepts.md to describe
both orchestrators and who each is suited for; qualify the
feature parity claim with a link to systemd-specific limitations
table and accurate descriptions; remove the stale "only RPMs"
caveat
systemd-installation.md; update all cross-doc links and
mkdocs.yml nav accordingly
(swarm-installation.md) and add a tip callout pointing readers to
the systemd path; fix bare "here" link to use descriptive text
section (now covered in prerequisites/index.md)
alongside the Docker Swarm upgrade guide; add missing Deb package
upgrade section
(2377, 7946, 4789) in prerequisites/index.md
not supported on systemd clusters
missing systemd.* settings (instance_data_dir, pgbackrest_path,
patroni_path) to the configuration reference with verified
defaults
systemd recovery guidance is not yet available
command to mtls.md
PLAT-658