Updates to Workbench Documentation#206
Conversation
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (3)
✅ Files skipped from review due to trivial changes (3)
WalkthroughThis PR reorganizes and expands documentation: new architecture overview and README updates; added installation guides (binary, source, Docker) and an installation overview; expanded collector configuration and systemd docs; added admin health-verification guide; updated mkdocs navigation. ChangesDocumentation Reorganization and Expansion
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
Suggested reviewers
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 inconclusive)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
⚔️ Resolve merge conflicts
Comment |
Up to standards ✅🟢 Issues
|
…s.yml and updates the installation.md file - it includes the steps required to make the workbench run as of 5/13/2026 with the supporting services in a UTM VM and the client running on a Mac host. The whole configuration is on the localhost
dpage
left a comment
dpage
left a comment
There was a problem hiding this comment.
The substantive content here is exactly what was missing — this resolves #69. The nginx setup, the ai-dba-server -add-user step, the client file deployment, and the allow_internal_networks guidance together close the gap that made a fresh install dead-end at the login page, so I'd love to see this land.
A few documentation-style nits below before un-drafting — none of them are blockers, just cleanup:
-
Broken cross-reference. The "Using Binary Files to Install Workbench" section links to
docs/getting-started/quick-start.md, but that file isn't in this PR and doesn't exist in the docs tree, so it will 404 once the site is built. Either add the page, or repoint the cross-reference at the binary-install steps already in this file. -
Hard-coded versioned external links. The
secret_file/password_filebullets in "Building AI DBA Workbench from Source Code" point athttps://docs.pgedge.com/ai-dba-workbench/v1-0-0-beta1/.... These will rot at the next release. The style guide prefers local relative links when one is available —configuration/collector.md#security-optionsetc. would survive version bumps for free. -
User=placeholder vs. RPM/DEB row. The three systemd unit examples now useUser=user_name, but the deployment-paths table two paragraphs earlier still documentsRun-as user: pgedgefor the RPM/DEB column. Keepinguser_nameas the placeholder is right for the GitHub-release method this section is documenting — but it's worth one short note that the RPM/DEB packages create and use thepgedgeuser automatically, so package-method installers shouldn't hand-edit the unit files. -
Sample
systemctl statusoutput. The collector/alerter status blocks bake in a specific hostname (n1), the beta version string (v1.0.0-beta1), and concrete timestamps. The style guide says sample output should match actual output, which is fine if these were captured from a real run — just want to confirm they weren't hand-written, and flag that thev1.0.0-beta1string in particular will go stale at release. -
Duplicated verification content. The new
docs/getting-started/verify_health.md(Checking the Collector / Server / Alerter / Metrics Collection) is essentially the same content as the new "Verifying the State of Individual Components" section ininstallation.md. Two copies will drift. Suggest keepingverify_health.mdas the canonical home and replacing the duplicated section ininstallation.mdwith a short pointer to it — bonus, it keepsinstallation.mdfrom growing too long.
Thanks for tackling this — the install path is meaningfully better with these changes.
…ction to include overview page; renamed files
…ions for verifying health and systemd configurations (refactored into other content)
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 14
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (3)
docs/getting-started/docker.md (1)
99-107:⚠️ Potential issue | 🟠 Major | ⚡ Quick winAvoid documenting plaintext passwords in CLI arguments.
Using
-password "YourPass123!"encourages secrets in shell history and process
lists. Prefer interactive prompt flow or secret-file/env-based input.🤖 Prompt for 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. In `@docs/getting-started/docker.md` around lines 99 - 107, The documented CLI invocation for ai-dba-server exposes a plaintext password via the -password flag; update the example to avoid embedding secrets by removing the -password "YourPass123!" argument and instead demonstrate a secure option such as using an interactive prompt, reading the password from a file/secret (e.g., a -password-file flag) or from an environment variable, and keep the rest of the command (ai-dba-server, -config, -add-user, -username, -full-name, -email) intact so readers see how to add a user without leaking credentials.README.md (1)
214-230:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winNormalize README footer text to required exact end format.
The required README closing lines are present semantically, but not in the
exact required form (split lines and final-line formatting differ). Please make
the footer match the mandated sentences exactly, with the license sentence as
the final line.As per coding guidelines, "
**/README.md: At the end of each README.md, include an Issues link: 'To report an issue with the software, visit:', a Developer link: 'We welcome your project contributions; for more information, see docs/developer-guide/contributing.md.', an online docs link: 'For more information, visit docs.pgedge.com', and License (final line): 'This project is licensed under the PostgreSQL License.'"🤖 Prompt for 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. In `@README.md` around lines 214 - 230, The README footer currently has the right content but not the exact required phrasing/line breaks; replace the current closing block with these exact lines in order: "To report an issue with the software, visit: [GitHub Issues](https://github.com/pgEdge/ai-dba-workbench/issues)", "We welcome your project contributions; for more information, see docs/developer-guide/contributing.md.", "For more information, visit [docs.pgedge.com](https://docs.pgedge.com)", and ensure the final line is exactly "This project is licensed under the [PostgreSQL License](LICENSE.md)."; update README.md so those sentences appear verbatim and with the License sentence as the last line.docs/getting-started/configuration/collector.md (1)
273-275:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winAdd a blank line before the nested list at Line 274.
The nested numbered list starts immediately after
- Default: ...without the
required blank line.Suggested fix
- Default: Searches in order: + 1. The per-user config directory atAs per coding guidelines "**/*.md: Leave a blank line before the first item in
any list or sub-list in markdown."🤖 Prompt for 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. In `@docs/getting-started/configuration/collector.md` around lines 273 - 275, The markdown nested numbered list after the line "- Default: Searches in order:" is missing a required blank line; insert a single empty line between the "- Default: Searches in order:" line and the following nested numbered list (the "1. The per-user config directory at `~/.config/pgedge/ai-dba-collector.secret` on Linux" item) so the sub-list is properly separated according to the Markdown guideline.
🧹 Nitpick comments (1)
mkdocs.yml (1)
66-67: ⚡ Quick winLink the dedicated architecture page in nav to avoid orphaned docs.
docs/architecture.mdis introduced in this PR, but navigation currently routes
“Architecture Overview” toindex.mdonly. Consider addingarchitecture.mdas
a visible nav item (or linking to it fromindex.md) so the new page is
discoverable.🤖 Prompt for 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. In `@mkdocs.yml` around lines 66 - 67, The nav entry for "Architecture Overview" in mkdocs.yml currently points only to index.md, leaving docs/architecture.md orphaned; update mkdocs.yml's nav so the "Architecture Overview" item either links directly to architecture.md (e.g., "Architecture Overview: architecture.md") or add a new visible nav entry for architecture.md, or alternatively add a hyperlink from index.md to docs/architecture.md so the new page is discoverable; edit the nav block in mkdocs.yml and/or add the link in index.md accordingly.
🤖 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/admin-guide/verify_health.md`:
- Around line 18-36: The fenced code blocks in verify_health.md are missing
language identifiers (e.g., the blocks showing the systemd output
"pgedge-ai-dba-collector.service ...", the curl response '{"status":"ok"...}',
and the alerter service output), which violates the markdown guideline; update
each multiline fenced block (the blocks containing the systemd logs, the curl -s
http://localhost:8080/health response, and other similar examples referenced
around lines 50-53 and 67-88) by adding a language tag such as ```text at the
opening fence so all code blocks have language identifiers and markdown linting
passes.
- Around line 20-36: Several lines in the sample output and prose exceed the
79-character markdown wrap limit (notably the systemd/status lines such as
"pgEdge AI DBA Workbench Collector v1.0.0-beta1 starting...", "Configuration
loaded from: /etc/pgedge/ai-dba-collector.yaml", and the "Main PID: 59722 ..."
block); hard-wrap all markdown paragraphs and lines inside the fenced output
block to 79 characters or less while preserving the fenced code block formatting
and the exact text content (only inserting line breaks, not altering wording),
so the status lines and timestamps remain intact but are line-wrapped to comply
with the repo guideline.
In `@docs/getting-started/binary_install.md`:
- Around line 380-407: The sample uses inconsistent names: change the datastore
name `database: ai-workbench` to match the earlier `ai_workbench` identifier and
update `secret_file: /etc/ai-workbench/secret.secret` to the exact server secret
path/name used elsewhere (the previously generated server secret), ensuring
`username`, `password_file`, `port` remain correct; search for `database`,
`secret_file`, and `password_file` in this diff to locate and make the values
consistent with the rest of the configuration to avoid connection/auth failures.
- Line 440: Update the runtime message string that currently reads "The server
is running as a background process; press `Enter` to view your prompt." to
reference the alerter component instead—change "server" to "alerter" so the
message reads "The alerter is running as a background process; press `Enter` to
view your prompt." Locate and edit the exact text string in the alerter section
that matches the current sentence to correct the component name.
- Around line 75-96: The documentation uses inconsistent secret-file paths:
`/etc/ai-workbench` vs `/etc/pgedge`, causing the `mkdir`, `openssl ... | tee`,
and `chmod` steps to target different directories; pick one canonical directory
(e.g., `/etc/ai-workbench`) and make all commands consistent—update the `mkdir
-p` target, the `openssl ... | tee /.../server.secret` target, and the `chmod
/.../server.secret` target so they all reference the same directory and filename
(`server.secret`), and ensure any mention of `password.txt` uses the same chosen
directory as well.
- Around line 16-31: Update the mismatched architecture in the docs: change the
prerequisite or the example filenames so they match (either require Linux arm64
instead of "Linux x86_64" or replace the example tarballs
ai-dba-collector-linux-arm64.tar.gz, ai-dba-server-linux-arm64.tar.gz,
ai-dba-alerter-linux-arm64.tar.gz with the x86_64 equivalents); ensure the text
around "A Linux x86_64 system is available to host the server-side components."
and the three tar filenames are consistent.
In `@docs/getting-started/configuration/collector.md`:
- Line 11: The document's heading hierarchy jumps from H1 to H3 at the locations
around the current "File Location" and the heading at the other flagged spot;
change those H3 headings (###) to H2 (##) so there is a single H1 and subsequent
H2 sections per the markdown guideline; locate the headings text "File Location"
and the other flagged heading and update their level to H2 to restore proper
progression.
- Around line 421-424: Insert a single blank line before the Markdown list that
begins with "- `datastore.host`" so the list is separated from the preceding
paragraph; locate the paragraph immediately before the list in
docs/getting-started/configuration/collector.md and add one empty line above the
"- `datastore.host`" list item to comply with the Markdown guideline.
In `@docs/getting-started/configuration/configure_systemd.md`:
- Line 64: Change the heading "Configuring the Alerter Service" from an H3 (###)
to an H2 (##) so it is parallel with the Collector/Server sections; update the
line containing that exact heading text to use two hash marks (##) to comply
with the project's markdown guideline of one H1 and multiple H2s.
In `@docs/getting-started/docker.md`:
- Around line 114-115: Update the stale anchor in the markdown link that
currently points to "installation.md#installation-paths-by-method" so it targets
the installation overview page instead (e.g., change the target to
"installation.md#installation-overview" or to the new overview page path
"installation/overview.md"); locate the link text in
docs/getting-started/docker.md and replace the old anchor with the new overview
target so the link resolves to the installation overview.
In `@docs/getting-started/installation_overview.md`:
- Around line 83-85: Reflow the paragraph that begins "The installation guides
linked above share the details required to get a minimal deployment of the
Workbench installed and serving content..." so no line exceeds 79 characters;
break sentences into multiple lines at word boundaries (preserve punctuation and
links) to comply with the repository rule for Markdown files (wrap all markdown
files at 79 characters or less).
- Around line 39-40: Replace the non-descriptive link label "here" in the
sentence "are used in the Docker deployment method documented [here](docker.md)"
with a descriptive phrase such as "the Docker deployment guide" or "Docker
deployment documentation" so the link reads e.g. "documented in the Docker
deployment guide (docker.md)"; update the link text accordingly to improve
accessibility and match the markdown style guidelines.
In `@README.md`:
- Around line 19-83: The TOC has nested lists that start immediately after
parent bullets (e.g., "Installation and Configuration:", "User Guide:",
"Alerts:", "Developer's Guide:" etc.); insert a single blank line between each
parent bullet line and its first nested list item so every sub-list begins after
an empty line, ensuring consistency for all nested sections shown in the diff
(Installation and Configuration, User Guide, Administrator's Guide, Developer's
Guide and their sub-sections).
- Line 21: The Table of Contents entry for "[Installation]" points to
docs/getting-started/installation.md which no longer exists; update the
README.md TOC link target to docs/getting-started/installation_overview.md
(replace the href for the "[Installation]" link) so the navigation points to the
current installation_overview.md file.
---
Outside diff comments:
In `@docs/getting-started/configuration/collector.md`:
- Around line 273-275: The markdown nested numbered list after the line "-
Default: Searches in order:" is missing a required blank line; insert a single
empty line between the "- Default: Searches in order:" line and the following
nested numbered list (the "1. The per-user config directory at
`~/.config/pgedge/ai-dba-collector.secret` on Linux" item) so the sub-list is
properly separated according to the Markdown guideline.
In `@docs/getting-started/docker.md`:
- Around line 99-107: The documented CLI invocation for ai-dba-server exposes a
plaintext password via the -password flag; update the example to avoid embedding
secrets by removing the -password "YourPass123!" argument and instead
demonstrate a secure option such as using an interactive prompt, reading the
password from a file/secret (e.g., a -password-file flag) or from an environment
variable, and keep the rest of the command (ai-dba-server, -config, -add-user,
-username, -full-name, -email) intact so readers see how to add a user without
leaking credentials.
In `@README.md`:
- Around line 214-230: The README footer currently has the right content but not
the exact required phrasing/line breaks; replace the current closing block with
these exact lines in order: "To report an issue with the software, visit:
[GitHub Issues](https://github.com/pgEdge/ai-dba-workbench/issues)", "We welcome
your project contributions; for more information, see
docs/developer-guide/contributing.md.", "For more information, visit
[docs.pgedge.com](https://docs.pgedge.com)", and ensure the final line is
exactly "This project is licensed under the [PostgreSQL License](LICENSE.md).";
update README.md so those sentences appear verbatim and with the License
sentence as the last line.
---
Nitpick comments:
In `@mkdocs.yml`:
- Around line 66-67: The nav entry for "Architecture Overview" in mkdocs.yml
currently points only to index.md, leaving docs/architecture.md orphaned; update
mkdocs.yml's nav so the "Architecture Overview" item either links directly to
architecture.md (e.g., "Architecture Overview: architecture.md") or add a new
visible nav entry for architecture.md, or alternatively add a hyperlink from
index.md to docs/architecture.md so the new page is discoverable; edit the nav
block in mkdocs.yml and/or add the link in index.md accordingly.
🪄 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: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: f003b467-45a8-4611-a7c5-9ba4374caf4f
⛔ Files ignored due to path filters (3)
docs/images/add_server.pngis excluded by!**/*.pngdocs/images/connected_server.pngis excluded by!**/*.pngdocs/images/workbench_login.pngis excluded by!**/*.png
📒 Files selected for processing (13)
README.mddocs/admin-guide/verify_health.mddocs/architecture.mddocs/getting-started/binary_install.mddocs/getting-started/build_from_source.mddocs/getting-started/configuration/collector.mddocs/getting-started/configuration/configure_systemd.mddocs/getting-started/docker.mddocs/getting-started/installation.mddocs/getting-started/installation_overview.mddocs/getting-started/quick-start.mddocs/index.mdmkdocs.yml
💤 Files with no reviewable changes (2)
- docs/getting-started/installation.md
- docs/getting-started/quick-start.md
| - A Linux x86_64 system is available to host the server-side components. | ||
|
|
||
| ## Installing the Binaries | ||
|
|
||
| Download the latest release from the | ||
| [GitHub releases page](https://github.com/pgEdge/ai-dba-workbench/releases). | ||
| The release archive includes the collector, server, and alerter binaries | ||
| and pre-built web client files. After downloading the files, extract the | ||
| archives and copy the files into a deployment directory. In the following | ||
| example, the `tar` and `cp` commands install the binary and client files | ||
| to the `/opt/ai-workbench` directory: | ||
|
|
||
| ```bash | ||
| tar xzf ai-dba-collector-linux-arm64.tar.gz | ||
| tar xzf ai-dba-server-linux-arm64.tar.gz | ||
| tar xzf ai-dba-alerter-linux-arm64.tar.gz |
There was a problem hiding this comment.
Architecture mismatch: x86_64 prereq vs arm64 binaries in commands.
The guide requires Linux x86_64 but the example downloads/extracts
*-linux-arm64.tar.gz. This will fail for users following the stated
prerequisite.
🤖 Prompt for 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.
In `@docs/getting-started/binary_install.md` around lines 16 - 31, Update the
mismatched architecture in the docs: change the prerequisite or the example
filenames so they match (either require Linux arm64 instead of "Linux x86_64" or
replace the example tarballs ai-dba-collector-linux-arm64.tar.gz,
ai-dba-server-linux-arm64.tar.gz, ai-dba-alerter-linux-arm64.tar.gz with the
x86_64 equivalents); ensure the text around "A Linux x86_64 system is available
to host the server-side components." and the three tar filenames are consistent.
| - Installation and Configuration: | ||
| - [Quick Start Guide](docs/getting-started/quick-start.md) | ||
| - [Installation](docs/getting-started/installation.md) | ||
| - [Docker Deployment](docs/getting-started/docker.md) | ||
| - Configuring the Workbench: | ||
| - [Configuring the Server](docs/getting-started/configuration/server.md) | ||
| - [Configuring the Collector](docs/getting-started/configuration/collector.md) | ||
| - [Configuring the Alerter](docs/getting-started/configuration/alerter.md) | ||
| - [Configuring the Web Client](docs/getting-started/configuration/client.md) | ||
| - User Guide: | ||
| - [Using the Workbench](docs/user-guide/index.md) | ||
| - Monitoring Dashboards: | ||
| - [Dashboard Overview](docs/user-guide/dashboards/index.md) | ||
| - [Estate Dashboard](docs/user-guide/dashboards/estate.md) | ||
| - [Cluster Dashboard](docs/user-guide/dashboards/cluster.md) | ||
| - [Server Dashboard](docs/user-guide/dashboards/server.md) | ||
| - [Database Dashboard](docs/user-guide/dashboards/database.md) | ||
| - [Object Dashboard](docs/user-guide/dashboards/object.md) | ||
| - Alerts: | ||
| - [Understanding Alerts](docs/user-guide/alerts/index.md) | ||
| - [Alert Reference](docs/user-guide/alerts/rule-reference.md) | ||
| - [AI Alert Analysis](docs/user-guide/alerts/ai-analysis.md) | ||
| - [Blackout Management](docs/user-guide/blackouts.md) | ||
| - AI Features: | ||
| - [AI Overview](docs/user-guide/ai/overview.md) | ||
| - [Ask Ellie](docs/user-guide/ai/ask-ellie.md) | ||
| - [Connecting MCP Clients](docs/user-guide/ai/mcp-clients.md) | ||
| - [MCP Tools](docs/user-guide/mcp-tools.md) | ||
| - Administrator's Guide: | ||
| - [Overview](docs/admin-guide/index.md) | ||
| - [Users & Authentication](docs/admin-guide/authentication.md) | ||
| - [Connection Management](docs/admin-guide/connections.md) | ||
| - [Alert Rules & Thresholds](docs/admin-guide/alert-rules.md) | ||
| - [Notification Channels](docs/admin-guide/notification-channels.md) | ||
| - [Probe Configuration](docs/admin-guide/probes.md) | ||
| - REST API: | ||
| - [API Reference](docs/admin-guide/api/reference.md) | ||
| - [API Browser](docs/admin-guide/api/browser.md) | ||
| - [Server Information](docs/admin-guide/api/server-info.md) | ||
| - [Metrics API](docs/admin-guide/api/metrics.md) | ||
| - Developer's Guide: | ||
| - [Overview](docs/developer-guide/index.md) | ||
| - [Contributing](docs/developer-guide/contributing.md) | ||
| - Collector Architecture: | ||
| - [Architecture](docs/developer-guide/collector/architecture.md) | ||
| - [Schema Design](docs/developer-guide/collector/schema.md) | ||
| - [Schema Management](docs/developer-guide/collector/schema-management.md) | ||
| - [Scheduler](docs/developer-guide/collector/scheduler.md) | ||
| - [Probes](docs/developer-guide/collector/probes.md) | ||
| - [Adding Probes](docs/developer-guide/collector/adding-probes.md) | ||
| - [Probe Reference](docs/developer-guide/collector/probe-reference.md) | ||
| - [pg_settings Usage](docs/developer-guide/collector/pg-settings-usage.md) | ||
| - [Testing](docs/developer-guide/collector/testing.md) | ||
| - Alerter Architecture: | ||
| - [Architecture](docs/developer-guide/alerter/architecture.md) | ||
| - [Anomaly Detection](docs/developer-guide/alerter/anomaly-detection.md) | ||
| - [Adding Rules](docs/developer-guide/alerter/adding-rules.md) | ||
| - [Cron Expressions](docs/developer-guide/alerter/cron-expressions.md) | ||
| - [Testing](docs/developer-guide/alerter/testing.md) | ||
| - Server Architecture: | ||
| - [Architecture](docs/developer-guide/server/architecture.md) | ||
| - Client Architecture: | ||
| - [Architecture](docs/developer-guide/client/architecture.md) | ||
| - Design: | ||
| - [Node Role Probe](docs/developer-guide/design/node-role-probe.md) |
There was a problem hiding this comment.
Add blank lines before nested list items in the TOC.
Several nested lists start immediately after a parent bullet (for example after
“Installation and Configuration:”, “User Guide:”, “Alerts:”, etc.). Insert a
blank line before each sub-list’s first item to match the markdown style rule.
As per coding guidelines, "Leave a blank line before the first item in any list or sub-list in markdown."
🤖 Prompt for 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.
In `@README.md` around lines 19 - 83, The TOC has nested lists that start
immediately after parent bullets (e.g., "Installation and Configuration:", "User
Guide:", "Alerts:", "Developer's Guide:" etc.); insert a single blank line
between each parent bullet line and its first nested list item so every sub-list
begins after an empty line, ensuring consistency for all nested sections shown
in the diff (Installation and Configuration, User Guide, Administrator's Guide,
Developer's Guide and their sub-sections).
dpage
left a comment
dpage
left a comment
There was a problem hiding this comment.
Summary
This is a substantial documentation reorganization (+1640 / −1087 across 16 files): the old quick-start.md and installation.md are deleted; new pages binary_install.md, build_from_source.md, installation_overview.md, configure_systemd.md, verify_health.md, and architecture.md are added; mkdocs.yml, README.md, docs/index.md, docker.md, and collector.md are reworked. The information architecture is a clear improvement, and the prose generally follows the style guide. However, the PR ships with a cluster of broken links pointing at the deleted files, several setup-breaking inconsistencies inside binary_install.md (which CodeRabbit also flagged), and a stray duplicate page that isn't wired into the nav. The CodeRabbit findings on the new pages are mostly valid and worth incorporating.
Issues Found
🔴 Must Fix
1. Broken links to deleted quick-start.md and installation.md — multiple files.
This PR deletes both pages but leaves five navigation references behind:
README.md:20—[Quick Start Guide](docs/getting-started/quick-start.md)README.md:21—[Installation](docs/getting-started/installation.md)README.md:143—[the Workbench](docs/getting-started/quick-start.md)docs/index.md:59—[Quick Start](getting-started/quick-start.md)docs/getting-started/docker.md:114—[installation paths table](installation.md#installation-paths-by-method)(CodeRabbit also flagged this)
All five render as 404s on the built site. Repoint to binary_install.md (the de-facto new quick-start) and installation_overview.md (which now hosts the deployment-paths table).
2. binary_install.md secret-file paths are mutually inconsistent (CodeRabbit).
Lines 75–96 say both files live under /etc/ai-workbench, then mkdir -p /etc/pgedge, then write to /etc/pgedge/server.secret, then chmod 600 /etc/ai-workbench/server.secret — three different paths in five lines. A user following this verbatim ends up with a chmod failure and a secret in the wrong place. Pick one canonical directory (the rest of the doc, the systemd unit examples, and verify_health.md all assume /etc/pgedge/) and make all three commands agree.
3. binary_install.md alerter sample uses mismatched datastore/secret names (CodeRabbit).
Around lines 360–407: database: ai-workbench (hyphen) contradicts the earlier ai_workbench (underscore) used everywhere else, and secret_file: /etc/ai-workbench/secret.secret doesn't match any file actually created in the guide. Both are immediate connect/auth failures for anyone copy-pasting the snippet.
4. binary_install.md architecture mismatch (CodeRabbit).
Line 16 requires "A Linux x86_64 system" as a prerequisite; lines 28–30 then untar *-linux-arm64.tar.gz. Either relax the prerequisite, or change the tarball names to linux-amd64.
🟡 Should Fix
5. docs/architecture.md duplicates docs/index.md and is orphaned from the nav.
Both files are ~75 lines and identical except for the title and the final "Where to Start" section. mkdocs.yml references index.md as "Architecture Overview" but does not list architecture.md. Either delete architecture.md, or — if the intent was to split the home page from the architecture page — wire architecture.md into the nav and replace index.md with a shorter landing page. As it stands, the two will drift.
6. binary_install.md:440 says "The server is running…" inside the alerter section (CodeRabbit).
Same sentence appears verbatim under both the server and alerter blocks; the alerter one should say "alerter".
7. build_from_source.md Alice example output contradicts input.
Lines 92–104: the user enters Full name (optional): Alice Baker, but the confirmation block prints Full Name: Alice. Sample output should match actual output (project style guide). Change the confirmation to Full Name: Alice Baker.
8. verify_health.md fenced output blocks lack language tags (CodeRabbit).
The three large status-output blocks (around lines 18, 50, 67) open with bare rather than ````text ````, which violates the project's "use fenced code blocks with language tags" rule and trips markdownlint.
🟢 Suggestion
9. Heading-hierarchy nits (CodeRabbit).
configuration/collector.md:11,30jumps H1 → H3 ("File Location", "File Format"). Promote to H2.configuration/configure_systemd.md:64has### Configuring the Alerter Servicewhile Collector/Server peers are H2. Promote to H2.
10. Line-wrap nits to 79 cols (CodeRabbit).
A handful of paragraphs in verify_health.md (around lines 20, 69–88, 108) and installation_overview.md (around line 85) exceed 79 chars. The bulk of the PR already respects the rule; these are isolated misses.
11. installation_overview.md:40 uses bare "here" link text (CodeRabbit).
Style/accessibility nit — use descriptive link text such as "the Docker deployment guide".
12. README.md nested-list blank lines (CodeRabbit).
Several TOC sub-lists ("Installation and Configuration:", "User Guide:", "Alerts:", "REST API:", etc.) start immediately after their parent bullet. The style guide requires a blank line before the first item of any sub-list.
13. configure_systemd.md is missing a trailing newline.
Diff shows \ No newline at end of file.
ℹ️ Note
14. The README TOC mixes in-document anchors with file-path links.
The new TOC lists internal sections (Components, Installing, Testing) alongside what is essentially a duplicate of the mkdocs.yml nav (docs/user-guide/dashboards/estate.md, etc.). That's a lot of surface to keep in sync with the site nav by hand — every future doc reshuffle will need both updated, and the README's value as a "what's in this repo" snapshot blurs into a second nav. Worth a conversation about whether the README should keep just the in-document sections plus a single pointer to the rendered docs site, rather than mirror the full tree.
Checklist
- Correctness — prose intent is sound; structural reorganisation is an improvement
- Security — no security-relevant content changed
- Documentation — broken cross-links and setup-breaking config samples need fixing before merge
There was a problem hiding this comment.
Actionable comments posted: 1
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (22)
docs/getting-started/binary_install.md (12)
115-125: 🛠️ Refactor suggestion | 🟠 Major | ⚡ Quick winWrap lines to 79 characters or less.
Lines 115, 116, and 123 exceed the 79-character limit. As per coding guidelines, all markdown files should wrap at 79 characters or less.
📏 Proposed rewrap
-Copy the example configuration file to the system configuration directory -before editing the settings. In the following example, the `cp` command -copies the example collector configuration file to `/etc/pgedge`: +Copy the example configuration file to the system configuration +directory before editing the settings. In the following example, the +`cp` command copies the example collector configuration file to +`/etc/pgedge`:-Update the configuration file to describe the deployment. The following -example shows the minimum settings required for a local development +Update the configuration file to describe the deployment. The +following example shows the minimum settings required for a local +development🤖 Prompt for 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. In `@docs/getting-started/binary_install.md` around lines 115 - 125, Wrap the long lines in the markdown section containing the "Copy the example configuration file..." paragraph and the code block that shows the sudo cp command so no line exceeds 79 characters; specifically reflow the prose lines (the paragraph starting "Copy the example configuration file..." and the paragraph starting "Update the configuration file...") and break or shorten the long inline command/example string (the backticked sudo cp example) so each resulting line is <=79 characters while preserving wording and code content.
498-500: 🛠️ Refactor suggestion | 🟠 Major | ⚡ Quick winWrap line 498 to 79 characters or less.
Line 498 exceeds the 79-character limit. As per coding guidelines, all markdown files should wrap at 79 characters or less.
📏 Proposed rewrap
-After logging in, select the `+` next to the DATABASE SERVERS heading -in the left navigation panel. The Workbench adds a new server definition +After logging in, select the `+` next to the DATABASE SERVERS +heading in the left navigation panel. The Workbench adds a new server definition🤖 Prompt for 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. In `@docs/getting-started/binary_install.md` around lines 498 - 500, The sentence "After logging in, select the `+` next to the DATABASE SERVERS heading in the left navigation panel. The Workbench adds a new server definition entry." on line with "After logging in, select the `+` next to the DATABASE SERVERS heading..." exceeds 79 chars; reflow it to wrap at 79 characters or less (e.g., split into two short lines) while preserving the exact meaning and inline code formatting (`+`, `DATABASE SERVERS`, "Workbench"). Ensure no line exceeds 79 characters.
140-140:⚠️ Potential issue | 🔴 Critical | ⚡ Quick winSecret file path mismatch will cause authentication failure.
The collector configuration references
secret_file: /etc/pgedge/ai-dba-server.secretbut the guide creates the secret at/etc/ai-workbench/server.secret(line 93). This mismatch will cause the collector to fail on startup when it cannot find the secret file.🔐 Proposed fix
-secret_file: /etc/pgedge/ai-dba-server.secret +secret_file: /etc/ai-workbench/server.secret🤖 Prompt for 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. In `@docs/getting-started/binary_install.md` at line 140, The docs have a secret file path mismatch: the collector config sets secret_file to /etc/pgedge/ai-dba-server.secret but the guide creates the secret at /etc/ai-workbench/server.secret; update the documentation so both references match (either change the collector config example's secret_file value or change the secret creation step) to use a single canonical path; ensure you update the occurrence of secret_file and the creation instruction (the two unique symbols to edit are the literal "secret_file: /etc/pgedge/ai-dba-server.secret" and the secret creation line that references "/etc/ai-workbench/server.secret") so readers and the collector use the same file path.
220-232: 🛠️ Refactor suggestion | 🟠 Major | ⚡ Quick winWrap line 221 to 79 characters or less.
Line 221 exceeds the 79-character limit. As per coding guidelines, all markdown files should wrap at 79 characters or less.
📏 Proposed rewrap
-By default, the server blocks connections to internal and private IP -addresses. To monitor a PostgreSQL instance on the same host or local -network, set the `allow_internal_networks` property to `true` in the +By default, the server blocks connections to internal and private IP +addresses. To monitor a PostgreSQL instance on the same host or +local network, set the `allow_internal_networks` property to `true` in the🤖 Prompt for 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. In `@docs/getting-started/binary_install.md` around lines 220 - 232, The second sentence in the introductory paragraph ("addresses. To monitor a PostgreSQL instance on the same host or local network, set the `allow_internal_networks` property to `true` in the server configuration file:") exceeds 79 characters; reflow that sentence into lines <=79 characters while preserving meaning and the YAML snippet that follows—edit the paragraph containing "By default, the server blocks connections to internal and private IP addresses." and the subsequent sentence so each Markdown line is wrapped at or below 79 columns.
348-360: 🛠️ Refactor suggestion | 🟠 Major | ⚡ Quick winWrap lines to 79 characters or less.
Lines 348, 352, 353, and 359 exceed the 79-character limit. As per coding guidelines, all markdown files should wrap at 79 characters or less.
📏 Proposed rewrap
-The alerter connects to the same datastore database as the collector and -server. Configure the alerter using a YAML configuration file or +The alerter connects to the same datastore database as the collector +and server. Configure the alerter using a YAML configuration file or-[alerter configuration](configuration/alerter.md) reference to review the -available options. In the following example, the `cp` command copies the -sample alerter configuration file from the Downloads folder to `/etc/pgedge`: +[alerter configuration](configuration/alerter.md) reference to review +the available options. In the following example, the `cp` command +copies the sample alerter configuration file from the Downloads folder +to `/etc/pgedge`:-Update the configuration file to describe the deployment; the following -example shows the minimum datastore settings: +Update the configuration file to describe the deployment; the +following example shows the minimum datastore settings:🤖 Prompt for 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. In `@docs/getting-started/binary_install.md` around lines 348 - 360, Wrap all prose lines in the alerter installation section to 79 characters or less; specifically reflow the paragraph that starts "The alerter connects to the same datastore database..." and the sentences containing the example cp command and the subsequent "Update the configuration file..." line so no individual line exceeds 79 characters, preserving the inline code snippets (`cp ~/Downloads/examples/ai-dba-alerter.yaml` and `/etc/pgedge/ai-dba-alerter.yaml`) and the YAML filename `ai-dba-alerter.yaml` intact while keeping markdown formatting and code fences unchanged.
73-80: 🛠️ Refactor suggestion | 🟠 Major | ⚡ Quick winWrap line 75 to 79 characters or less.
Line 75 exceeds the 79-character limit. As per coding guidelines, all markdown files should wrap at 79 characters or less.
📏 Proposed rewrap
-datastore database. Both files are saved in the `/etc/ai-workbench` -directory; the complete paths are: +datastore database. Both files are saved in the +`/etc/ai-workbench` directory; the complete paths are:🤖 Prompt for 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. In `@docs/getting-started/binary_install.md` around lines 73 - 80, Rewrap the long paragraph that lists the Workbench secret and password files so no line exceeds 79 characters; specifically break the sentence(s) containing the paths '/etc/ai-workbench/server.secret' and '/etc/ai-workbench/password.txt' into shorter lines (soft-wrap at or before 79 columns) while preserving the bullet list and exact path strings and punctuation.
167-176: 🛠️ Refactor suggestion | 🟠 Major | ⚡ Quick winWrap lines to 79 characters or less.
Lines 167, 168, and 175 exceed the 79-character limit. As per coding guidelines, all markdown files should wrap at 79 characters or less.
📏 Proposed rewrap
-Copy the server configuration file to the system configuration directory -before editing the settings. In the following example, the `cp` command -copies the sample configuration file to the `/etc/pgedge` directory: +Copy the server configuration file to the system configuration +directory before editing the settings. In the following example, the +`cp` command copies the sample configuration file to the +`/etc/pgedge` directory:-The sample configuration file specifies the minimum settings for a local -development environment: +The sample configuration file specifies the minimum settings for a +local development environment:🤖 Prompt for 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. In `@docs/getting-started/binary_install.md` around lines 167 - 176, Several markdown lines exceed the 79-character wrap limit; reflow the paragraph text and the inline code example so no line is longer than 79 characters (wrap the sentence starting "Copy the server configuration file..." and the sentence beginning "The sample configuration file..." and break the long bash code line containing sudo cp ~/Downloads/examples/ai-dba-server.yaml /etc/pgedge/ai-dba-server.yaml into wrapped lines in the file docs/getting-started/binary_install.md), preserving the inline code and path strings (`cp`, `~/Downloads/examples/ai-dba-server.yaml`, `/etc/pgedge/ai-dba-server.yaml`) and Markdown formatting.
444-446: 🛠️ Refactor suggestion | 🟠 Major | ⚡ Quick winWrap lines to 79 characters or less.
Lines 444 and 445 exceed the 79-character limit. As per coding guidelines, all markdown files should wrap at 79 characters or less.
📏 Proposed rewrap
-The server does not include a static file service; install and configure -[nginx](https://nginx.org/en/docs/) to serve the client files and proxy -API requests to the server before running the Workbench. +The server does not include a static file service; install and +configure [nginx](https://nginx.org/en/docs/) to serve the client +files and proxy API requests to the server before running the +Workbench.🤖 Prompt for 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. In `@docs/getting-started/binary_install.md` around lines 444 - 446, The two long lines starting with "The server does not include a static file service; install and configure [nginx]" should be hard-wrapped so no line exceeds 79 characters; update the paragraph in binary_install.md (the sentence mentioning nginx serving client files and proxying API requests) to wrap to 79 columns while preserving links and sentence content, breaking at natural word boundaries and keeping the markdown link syntax intact.
509-511: 🛠️ Refactor suggestion | 🟠 Major | ⚡ Quick winWrap lines to 79 characters or less.
Lines 509 and 510 exceed the 79-character limit. As per coding guidelines, all markdown files should wrap at 79 characters or less.
📏 Proposed rewrap
-- The [systemd configuration](configuration/configure_systemd.md) guide - provides details about setting up systemd service management for users that - did not use pgEdge packages when installing. +- The [systemd configuration](configuration/configure_systemd.md) + guide provides details about setting up systemd service management + for users that did not use pgEdge packages when installing.🤖 Prompt for 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. In `@docs/getting-started/binary_install.md` around lines 509 - 511, The two long lines containing the sentence starting "The [systemd configuration](configuration/configure_systemd.md) guide provides details..." in docs/getting-started/binary_install.md exceed the 79-character limit; reflow that paragraph so every line is 79 characters or fewer (e.g., break the sentence into two lines before or after the link and continuing clause), preserving the markdown link and punctuation and updating the wrapped text in place.
461-462: 🛠️ Refactor suggestion | 🟠 Major | ⚡ Quick winWrap line 461 to 79 characters or less.
Line 461 exceeds the 79-character limit. As per coding guidelines, all markdown files should wrap at 79 characters or less.
📏 Proposed rewrap
-Add the following code to the nginx configuration file to set the proxy -rules and file root for the installation: +Add the following code to the nginx configuration file to set the +proxy rules and file root for the installation:🤖 Prompt for 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. In `@docs/getting-started/binary_install.md` around lines 461 - 462, Line "Add the following code to the nginx configuration file to set the proxy rules and file root for the installation:" exceeds 79 characters; reflow this sentence into multiple lines wrapping at 79 characters or less (preserve wording and punctuation), for example breaking after natural phrase boundaries so each line is ≤79 chars; update the markdown so the wrapped sentence replaces the long single line.
49-59: 🛠️ Refactor suggestion | 🟠 Major | ⚡ Quick winWrap lines to 79 characters or less.
Lines 50 and 58 exceed the 79-character limit. As per coding guidelines, all markdown files should wrap at 79 characters or less.
📏 Proposed rewrap
-Use a PostgreSQL client to create a database for the datastore; the -collector, server, and alerter share this database. Connect to the PostgreSQL -server with `psql`: +Use a PostgreSQL client to create a database for the datastore; the +collector, server, and alerter share this database. Connect to the +PostgreSQL server with `psql`:-Then, create the datastore database. In the following example, the -`CREATE DATABASE` and `GRANT` statements create the `ai_workbench` database -and `ai_workbench` user: +Then, create the datastore database. In the following example, the +`CREATE DATABASE` and `GRANT` statements create the `ai_workbench` +database and `ai_workbench` user:🤖 Prompt for 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. In `@docs/getting-started/binary_install.md` around lines 49 - 59, Rewrap the markdown paragraphs so no line exceeds 79 characters: break long sentences in the paragraph that introduces the psql command and the paragraph describing the `CREATE DATABASE` and `GRANT` statements into multiple lines at word boundaries (keep the fenced code block with `psql -U postgres -h localhost` and the literal `CREATE DATABASE` / `GRANT` examples intact), ensuring each wrapped line is ≤79 chars and punctuation/spacing remains correct.
454-455:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winGrammar error: "creates" should be "create".
Line 454 contains a subject-verb agreement error: "we use
vito creates" should be "we usevito create".✏️ Proposed fix
-Then, in the following example, we use `vi` to creates the nginx +Then, in the following example, we use `vi` to create the nginx🤖 Prompt for 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. In `@docs/getting-started/binary_install.md` around lines 454 - 455, Fix the grammar in the sentence "we use `vi` to creates the nginx configuration file" by changing "creates" to "create" so it reads "we use `vi` to create the nginx configuration file"; update the sentence in the docs/getting-started binary_install.md content where that exact phrase appears.docs/getting-started/docker.md (10)
38-40:⚠️ Potential issue | 🟠 Major | ⚡ Quick winAdd blank line before numbered list.
A blank line must precede the first item in this numbered list. As per coding guidelines, leave a blank line before the first item in any list or sub-list in markdown.
📝 Proposed fix
Container Registry. + 1. Clone the repository to obtain the configuration files.🤖 Prompt for 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. In `@docs/getting-started/docker.md` around lines 38 - 40, Insert a blank line between the "Container Registry." paragraph and the numbered list that starts with "1. Clone the repository to obtain the configuration files." so the markdown has an empty line preceding the first list item (i.e., place a single newline after "Container Registry.").
131-131:⚠️ Potential issue | 🟠 Major | ⚡ Quick winWrap line to 79 characters or less.
This line exceeds the 79-character limit (82 characters). As per coding guidelines, all markdown files must wrap at 79 characters or less.
📝 Proposed fix
-reference to a specific commit. The publishing workflow produces the following +reference to a specific commit. The publishing workflow produces the +following tag types:🤖 Prompt for 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. In `@docs/getting-started/docker.md` at line 131, The markdown line "reference to a specific commit. The publishing workflow produces the following" exceeds the 79-character wrap limit; edit that sentence in the docs so it wraps at 79 characters or less by inserting a line break at a natural boundary (for example after "commit." or after "publishing workflow") to produce two shorter lines preserving the original wording and punctuation.
132-134:⚠️ Potential issue | 🟠 Major | ⚡ Quick winAdd blank line before list.
A blank line must precede the first item in this list. As per coding guidelines, leave a blank line before the first item in any list or sub-list in markdown.
📝 Proposed fix
tag types: + - The `latest` tag points to the most recent stable release and updates only🤖 Prompt for 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. In `@docs/getting-started/docker.md` around lines 132 - 134, Add a blank line before the first list item under the "tag types:" section so the markdown has an empty line between the heading/text ("tag types:") and the first bullet ("- The `latest` tag points to the most recent stable release and updates only"); update the section containing that bullet to insert a single empty line immediately above the "- The `latest` tag..." line.
274-274:⚠️ Potential issue | 🟠 Major | ⚡ Quick winWrap line to 79 characters or less.
This line exceeds the 79-character limit (80 characters). As per coding guidelines, all markdown files must wrap at 79 characters or less.
📝 Proposed fix
-In the following example, the datastore binds to port 5433 instead of 5432. +In the following example, the datastore binds to port 5433 instead of +5432.🤖 Prompt for 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. In `@docs/getting-started/docker.md` at line 274, The markdown sentence "In the following example, the datastore binds to port 5433 instead of 5432." exceeds the 79-character wrap limit; edit that line in docs/getting-started/docker.md so it wraps at or below 79 characters (for example split into two lines like "In the following example, the datastore binds to port 5433" and "instead of 5432.") ensuring the content and punctuation remain unchanged.
19-21:⚠️ Potential issue | 🟠 Major | ⚡ Quick winAdd blank line before list.
A blank line must precede the first item in this list. As per coding guidelines, leave a blank line before the first item in any list or sub-list in markdown.
📝 Proposed fix
The following software must be installed before proceeding. + - [Docker Engine](https://docs.docker.com/engine/install/)🤖 Prompt for 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. In `@docs/getting-started/docker.md` around lines 19 - 21, Insert a single blank line between the paragraph "The following software must be installed before proceeding." and the beginning of the list (the line starting with "- [Docker Engine](https://docs.docker.com/engine/install/)") so the markdown has an empty line before the first list item; update the docs/getting-started/docker.md content by adding that blank line directly above the "- [Docker Engine]" list entry.
160-162:⚠️ Potential issue | 🟠 Major | ⚡ Quick winAdd blank line before list.
A blank line must precede the first item in this list. As per coding guidelines, leave a blank line before the first item in any list or sub-list in markdown.
📝 Proposed fix
The `docker/config/` directory contains configuration files for each service. + - The `ai-dba-server.yaml` file configures the MCP🤖 Prompt for 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. In `@docs/getting-started/docker.md` around lines 160 - 162, The markdown list under the sentence "The `docker/config/` directory contains configuration files for each service." is missing a blank line before the first list item; insert a single blank line between that sentence and the hyphenated list so the first item (`- The `ai-dba-server.yaml` file configures the MCP`) is preceded by an empty line, ensuring the list renders correctly in the docs/getting-started/docker.md file.
262-264:⚠️ Potential issue | 🟠 Major | ⚡ Quick winWrap line to 79 characters or less.
Line 262 exceeds the 79-character limit (83 characters). As per coding guidelines, all markdown files must wrap at 79 characters or less.
📝 Proposed fix
-Ensure that the `POSTGRES_PASSWORD` environment variable is set before starting +Ensure that the `POSTGRES_PASSWORD` environment variable is set before +starting the services. The PostgreSQL container requires this variable on first🤖 Prompt for 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. In `@docs/getting-started/docker.md` around lines 262 - 264, The markdown sentence "Ensure that the `POSTGRES_PASSWORD` environment variable is set before starting the services. The PostgreSQL container requires this variable on first initialization." exceeds 79 chars; wrap it to 79 characters or less by breaking it into two or more lines (e.g., split after "set" or "services.") so each line is <=79 characters and preserve the inline code token `POSTGRES_PASSWORD`; update the paragraph containing `POSTGRES_PASSWORD` accordingly.
160-160:⚠️ Potential issue | 🟠 Major | ⚡ Quick winWrap line to 79 characters or less.
This line exceeds the 79-character limit (80 characters). As per coding guidelines, all markdown files must wrap at 79 characters or less.
📝 Proposed fix
-The `docker/config/` directory contains configuration files for each service. +The `docker/config/` directory contains configuration files for each +service.🤖 Prompt for 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. In `@docs/getting-started/docker.md` at line 160, The markdown line "The `docker/config/` directory contains configuration files for each service." exceeds 79 characters; edit that sentence in docs/getting-started/docker.md (the line containing `docker/config/`) to wrap at 79 characters or less by breaking it into two shorter lines or rephrasing (e.g., "The `docker/config/` directory contains\nconfiguration files for each service.") so no line is longer than 79 characters.
288-289:⚠️ Potential issue | 🟠 Major | ⚡ Quick winWrap line to 79 characters or less.
Line 288 exceeds the 79-character limit (81 characters). As per coding guidelines, all markdown files must wrap at 79 characters or less.
📝 Proposed fix
-The server may fail to connect if the database has not finished initializing. +The server may fail to connect if the database has not finished +initializing. The server container depends on the PostgreSQL health check, but network🤖 Prompt for 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. In `@docs/getting-started/docker.md` around lines 288 - 289, The markdown line "The server container depends on the PostgreSQL health check, but network" exceeds 79 chars; wrap it to 79 chars or less by splitting into two lines (for example after "health check," so the first line reads "The server container depends on the PostgreSQL health check," and the next line starts "but network"), ensuring the sentence remains intact and each resulting line is ≤79 characters.
8-15:⚠️ Potential issue | 🟠 Major | ⚡ Quick winWrap lines to 79 characters or less.
Several lines in this note block exceed the 79-character limit. As per coding guidelines, all markdown files must wrap at 79 characters or less.
Lines that exceed the limit:
- Line 9: 80 characters
- Line 10: 80 characters
🤖 Prompt for 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. In `@docs/getting-started/docker.md` around lines 8 - 15, The paragraph starting "RPM and DEB packages are available from the [pgEdge Enterprise Repository]" contains lines longer than 79 characters; reflow that paragraph so every line is <=79 chars (e.g., break after the repository link and before "are used in the Docker deployment method" and before "pgEdge packages create and use the `pgedge` user automatically"), preserving links and inline code formatting and keeping the same wording and sentence boundaries.
🤖 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/getting-started/docker.md`:
- Line 114: The markdown line containing the link "[installation paths
table](installation_overview.md#supported-installation-methods)" is 93
characters and must be wrapped to 79 chars or less; edit that line in
docs/getting-started/docker.md by breaking it into multiple wrapped lines (for
example split before the link or after the link text) so the rendered markdown
stays the same but no single line exceeds 79 characters, ensuring the link text
and target remain unchanged.
---
Outside diff comments:
In `@docs/getting-started/binary_install.md`:
- Around line 115-125: Wrap the long lines in the markdown section containing
the "Copy the example configuration file..." paragraph and the code block that
shows the sudo cp command so no line exceeds 79 characters; specifically reflow
the prose lines (the paragraph starting "Copy the example configuration file..."
and the paragraph starting "Update the configuration file...") and break or
shorten the long inline command/example string (the backticked sudo cp example)
so each resulting line is <=79 characters while preserving wording and code
content.
- Around line 498-500: The sentence "After logging in, select the `+` next to
the DATABASE SERVERS heading in the left navigation panel. The Workbench adds a
new server definition entry." on line with "After logging in, select the `+`
next to the DATABASE SERVERS heading..." exceeds 79 chars; reflow it to wrap at
79 characters or less (e.g., split into two short lines) while preserving the
exact meaning and inline code formatting (`+`, `DATABASE SERVERS`, "Workbench").
Ensure no line exceeds 79 characters.
- Line 140: The docs have a secret file path mismatch: the collector config sets
secret_file to /etc/pgedge/ai-dba-server.secret but the guide creates the secret
at /etc/ai-workbench/server.secret; update the documentation so both references
match (either change the collector config example's secret_file value or change
the secret creation step) to use a single canonical path; ensure you update the
occurrence of secret_file and the creation instruction (the two unique symbols
to edit are the literal "secret_file: /etc/pgedge/ai-dba-server.secret" and the
secret creation line that references "/etc/ai-workbench/server.secret") so
readers and the collector use the same file path.
- Around line 220-232: The second sentence in the introductory paragraph
("addresses. To monitor a PostgreSQL instance on the same host or local network,
set the `allow_internal_networks` property to `true` in the server configuration
file:") exceeds 79 characters; reflow that sentence into lines <=79 characters
while preserving meaning and the YAML snippet that follows—edit the paragraph
containing "By default, the server blocks connections to internal and private IP
addresses." and the subsequent sentence so each Markdown line is wrapped at or
below 79 columns.
- Around line 348-360: Wrap all prose lines in the alerter installation section
to 79 characters or less; specifically reflow the paragraph that starts "The
alerter connects to the same datastore database..." and the sentences containing
the example cp command and the subsequent "Update the configuration file..."
line so no individual line exceeds 79 characters, preserving the inline code
snippets (`cp ~/Downloads/examples/ai-dba-alerter.yaml` and
`/etc/pgedge/ai-dba-alerter.yaml`) and the YAML filename `ai-dba-alerter.yaml`
intact while keeping markdown formatting and code fences unchanged.
- Around line 73-80: Rewrap the long paragraph that lists the Workbench secret
and password files so no line exceeds 79 characters; specifically break the
sentence(s) containing the paths '/etc/ai-workbench/server.secret' and
'/etc/ai-workbench/password.txt' into shorter lines (soft-wrap at or before 79
columns) while preserving the bullet list and exact path strings and
punctuation.
- Around line 167-176: Several markdown lines exceed the 79-character wrap
limit; reflow the paragraph text and the inline code example so no line is
longer than 79 characters (wrap the sentence starting "Copy the server
configuration file..." and the sentence beginning "The sample configuration
file..." and break the long bash code line containing sudo cp
~/Downloads/examples/ai-dba-server.yaml /etc/pgedge/ai-dba-server.yaml into
wrapped lines in the file docs/getting-started/binary_install.md), preserving
the inline code and path strings (`cp`,
`~/Downloads/examples/ai-dba-server.yaml`, `/etc/pgedge/ai-dba-server.yaml`) and
Markdown formatting.
- Around line 444-446: The two long lines starting with "The server does not
include a static file service; install and configure [nginx]" should be
hard-wrapped so no line exceeds 79 characters; update the paragraph in
binary_install.md (the sentence mentioning nginx serving client files and
proxying API requests) to wrap to 79 columns while preserving links and sentence
content, breaking at natural word boundaries and keeping the markdown link
syntax intact.
- Around line 509-511: The two long lines containing the sentence starting "The
[systemd configuration](configuration/configure_systemd.md) guide provides
details..." in docs/getting-started/binary_install.md exceed the 79-character
limit; reflow that paragraph so every line is 79 characters or fewer (e.g.,
break the sentence into two lines before or after the link and continuing
clause), preserving the markdown link and punctuation and updating the wrapped
text in place.
- Around line 461-462: Line "Add the following code to the nginx configuration
file to set the proxy rules and file root for the installation:" exceeds 79
characters; reflow this sentence into multiple lines wrapping at 79 characters
or less (preserve wording and punctuation), for example breaking after natural
phrase boundaries so each line is ≤79 chars; update the markdown so the wrapped
sentence replaces the long single line.
- Around line 49-59: Rewrap the markdown paragraphs so no line exceeds 79
characters: break long sentences in the paragraph that introduces the psql
command and the paragraph describing the `CREATE DATABASE` and `GRANT`
statements into multiple lines at word boundaries (keep the fenced code block
with `psql -U postgres -h localhost` and the literal `CREATE DATABASE` / `GRANT`
examples intact), ensuring each wrapped line is ≤79 chars and
punctuation/spacing remains correct.
- Around line 454-455: Fix the grammar in the sentence "we use `vi` to creates
the nginx configuration file" by changing "creates" to "create" so it reads "we
use `vi` to create the nginx configuration file"; update the sentence in the
docs/getting-started binary_install.md content where that exact phrase appears.
In `@docs/getting-started/docker.md`:
- Around line 38-40: Insert a blank line between the "Container Registry."
paragraph and the numbered list that starts with "1. Clone the repository to
obtain the configuration files." so the markdown has an empty line preceding the
first list item (i.e., place a single newline after "Container Registry.").
- Line 131: The markdown line "reference to a specific commit. The publishing
workflow produces the following" exceeds the 79-character wrap limit; edit that
sentence in the docs so it wraps at 79 characters or less by inserting a line
break at a natural boundary (for example after "commit." or after "publishing
workflow") to produce two shorter lines preserving the original wording and
punctuation.
- Around line 132-134: Add a blank line before the first list item under the
"tag types:" section so the markdown has an empty line between the heading/text
("tag types:") and the first bullet ("- The `latest` tag points to the most
recent stable release and updates only"); update the section containing that
bullet to insert a single empty line immediately above the "- The `latest`
tag..." line.
- Line 274: The markdown sentence "In the following example, the datastore binds
to port 5433 instead of 5432." exceeds the 79-character wrap limit; edit that
line in docs/getting-started/docker.md so it wraps at or below 79 characters
(for example split into two lines like "In the following example, the datastore
binds to port 5433" and "instead of 5432.") ensuring the content and punctuation
remain unchanged.
- Around line 19-21: Insert a single blank line between the paragraph "The
following software must be installed before proceeding." and the beginning of
the list (the line starting with "- [Docker
Engine](https://docs.docker.com/engine/install/)") so the markdown has an empty
line before the first list item; update the docs/getting-started/docker.md
content by adding that blank line directly above the "- [Docker Engine]" list
entry.
- Around line 160-162: The markdown list under the sentence "The
`docker/config/` directory contains configuration files for each service." is
missing a blank line before the first list item; insert a single blank line
between that sentence and the hyphenated list so the first item (`- The
`ai-dba-server.yaml` file configures the MCP`) is preceded by an empty line,
ensuring the list renders correctly in the docs/getting-started/docker.md file.
- Around line 262-264: The markdown sentence "Ensure that the
`POSTGRES_PASSWORD` environment variable is set before starting the services.
The PostgreSQL container requires this variable on first initialization."
exceeds 79 chars; wrap it to 79 characters or less by breaking it into two or
more lines (e.g., split after "set" or "services.") so each line is <=79
characters and preserve the inline code token `POSTGRES_PASSWORD`; update the
paragraph containing `POSTGRES_PASSWORD` accordingly.
- Line 160: The markdown line "The `docker/config/` directory contains
configuration files for each service." exceeds 79 characters; edit that sentence
in docs/getting-started/docker.md (the line containing `docker/config/`) to wrap
at 79 characters or less by breaking it into two shorter lines or rephrasing
(e.g., "The `docker/config/` directory contains\nconfiguration files for each
service.") so no line is longer than 79 characters.
- Around line 288-289: The markdown line "The server container depends on the
PostgreSQL health check, but network" exceeds 79 chars; wrap it to 79 chars or
less by splitting into two lines (for example after "health check," so the first
line reads "The server container depends on the PostgreSQL health check," and
the next line starts "but network"), ensuring the sentence remains intact and
each resulting line is ≤79 characters.
- Around line 8-15: The paragraph starting "RPM and DEB packages are available
from the [pgEdge Enterprise Repository]" contains lines longer than 79
characters; reflow that paragraph so every line is <=79 chars (e.g., break after
the repository link and before "are used in the Docker deployment method" and
before "pgEdge packages create and use the `pgedge` user automatically"),
preserving links and inline code formatting and keeping the same wording and
sentence boundaries.
🪄 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: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 37e37b02-7ae9-4010-ac47-16dda12899a1
📒 Files selected for processing (5)
docs/admin-guide/verify_health.mddocs/getting-started/binary_install.mddocs/getting-started/configuration/configure_systemd.mddocs/getting-started/docker.mddocs/getting-started/installation_overview.md
✅ Files skipped from review due to trivial changes (3)
- docs/getting-started/configuration/configure_systemd.md
- docs/getting-started/installation_overview.md
- docs/admin-guide/verify_health.md
| The `/usr/local/bin/` path in the command above is specific to Docker | ||
| container images. Manual installs and RPM/DEB packages use different | ||
| binary locations. See the | ||
| [installation paths table](installation_overview.md#supported-installation-methods) |
There was a problem hiding this comment.
Wrap line to 79 characters or less.
This line exceeds the 79-character limit (93 characters). As per coding guidelines, all markdown files must wrap at 79 characters or less.
📝 Proposed fix
- [installation paths table](installation_overview.md#supported-installation-methods)
+ [installation paths table](
+ installation_overview.md#supported-installation-methods)
for details.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| [installation paths table](installation_overview.md#supported-installation-methods) | |
| [installation paths table]( | |
| installation_overview.md#supported-installation-methods) |
🤖 Prompt for 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.
In `@docs/getting-started/docker.md` at line 114, The markdown line containing the
link "[installation paths
table](installation_overview.md#supported-installation-methods)" is 93
characters and must be wrapped to 79 chars or less; edit that line in
docs/getting-started/docker.md by breaking it into multiple wrapped lines (for
example split before the link or after the link text) so the rendered markdown
stays the same but no single line exceeds 79 characters, ensuring the link text
and target remain unchanged.
2 participants
Updating documentation for consistency, etc...
Summary by CodeRabbit