Conversation
Why Provide a short operator path for ROSI Collector that gets readers from initial setup to first-client validation without sending them through multiple reference pages first. Impact Adds a new ROSI deployment walkthrough and links it into the docs nav. Before/After Before: ROSI docs had detailed reference pages but no compact end-to-end setup flow. After: ROSI docs include a generalized walkthrough for collector setup, client onboarding, and first validation. Technical Overview Add a new deployment walkthrough page under the ROSI Collector docs. Use the required meta block and summary slice for search and RAG. Structure the content as an operator flow with explicit outcomes, prerequisites, verification steps, and follow-up actions. Reuse an existing neutral Grafana screenshot instead of provider- specific imagery. Link the walkthrough from the ROSI Collector index and the broader deployments landing page. Register the new RST file in doc/Makefile.am for distribution. With the help of AI-Agents: Codex (cherry picked from commit 448d5e3)
rgerhards
force-pushed
the
feature/rosi-setup-walkthrough-doc
branch
from
448d5e3 to
08cc600
Compare
📖 Documentation Preview Ready!✅ Sphinx docs built and deployed for this PR. 🌐 Browse Online (Recommended):🔗 Quick Links:
🤖 This comment was generated by the docs workflow. |
Summary of ChangesHello, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request significantly enhances the ROSI Collector documentation by introducing a streamlined setup walkthrough. This new guide aims to provide users with the quickest path from initial installation to a fully functional ROSI deployment with an enrolled client, simplifying the onboarding process and reducing the need to consult multiple reference pages. Highlights
🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console. Changelog
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for GitHub and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces a valuable ROSI setup walkthrough, providing a clear, end-to-end guide for new users to quickly get a ROSI Collector running and onboard their first client. The changes correctly integrate the new documentation page into the existing structure. My feedback focuses on enhancing the clarity of the new walkthrough by explicitly guiding users to replace placeholder values with their specific environment details, which is crucial for a step-by-step guide.
| sudo TRAEFIK_DOMAIN=logs.example.com \ | ||
| TRAEFIK_EMAIL=admin@example.com \ |
There was a problem hiding this comment.
While example.com is a standard placeholder, explicitly mentioning that users should replace logs.example.com and admin@example.com with their actual domain would enhance clarity for a walkthrough aimed at new users. This helps prevent potential confusion during the initial setup.
| sudo TRAEFIK_DOMAIN=logs.example.com \ | |
| TRAEFIK_EMAIL=admin@example.com \ | |
| sudo TRAEFIK_DOMAIN=your.domain.com \ | |
| TRAEFIK_EMAIL=admin@your.domain.com \ |
|
|
||
| .. code-block:: bash | ||
|
|
||
| wget https://logs.example.com/downloads/install-rsyslog-client.sh |
There was a problem hiding this comment.
For a walkthrough, it would be beneficial to explicitly instruct users to replace logs.example.com with their actual collector domain when downloading the client setup script. This ensures they don't inadvertently try to download from the example domain.
| wget https://logs.example.com/downloads/install-rsyslog-client.sh | |
| wget https://<YOUR_COLLECTOR_DOMAIN>/downloads/install-rsyslog-client.sh |
|
|
||
| .. code-block:: bash | ||
|
|
||
| wget https://logs.example.com/downloads/install-node-exporter.sh |
There was a problem hiding this comment.
Consistent with previous suggestions, explicitly instructing users to replace logs.example.com with their actual collector domain here will improve the clarity and usability of the walkthrough for the node exporter setup.
| wget https://logs.example.com/downloads/install-node-exporter.sh | |
| wget https://<YOUR_COLLECTOR_DOMAIN>/downloads/install-node-exporter.sh |
| sudo prometheus-target add-client 198.51.100.1 \ | ||
| host=web-01 role=web env=production network=internal |
There was a problem hiding this comment.
The IP address 198.51.100.1 is an example. It would significantly improve clarity for the walkthrough to explicitly state that this should be replaced with the actual client's IP address, ensuring users configure their Prometheus targets correctly.
| sudo prometheus-target add-client 198.51.100.1 \ | |
| host=web-01 role=web env=production network=internal | |
| sudo prometheus-target add-client <CLIENT_IP_ADDRESS> \ | |
| host=web-01 role=web env=production network=internal |
Why The walkthrough had become too abstract and lost useful operator cues from the earlier tutorial flow. Impact Adds neutral screenshots and restores more concrete setup and validation steps in the ROSI walkthrough. Before/After Before: the walkthrough was concise but light on concrete operator checkpoints and UI context. After: the walkthrough includes first-start and Grafana screenshots, init prompt guidance, firewall steps, and stronger validation detail. Technical Overview Rename and reuse two non-provider-specific screenshots from the earlier ROSI tutorial under neutral asset names. Register the new static files in doc/Makefile.am. Expand the walkthrough with key init.sh prompts, non-interactive setup, first docker compose start expectations, log checks, firewall commands, and Grafana password/query validation steps. Keep the content provider-neutral while restoring practical actionability. With the help of AI-Agents: Codex
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
2 issues found across 4 files (changes from recent commits).
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="doc/source/deployments/rosi_collector/setup_walkthrough.rst">
<violation number="1" location="doc/source/deployments/rosi_collector/setup_walkthrough.rst:164">
P3: The firewall "minimum rule set" now unconditionally opens `6514/tcp`, even though this port is only required when syslog TLS is enabled.</violation>
<violation number="2" location="doc/source/deployments/rosi_collector/setup_walkthrough.rst:232">
P2: The password-retrieval command is missing `sudo`, so it can fail with permission denied on the root-owned `.env` file.</violation>
</file>
Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.
|
|
||
| .. code-block:: bash | ||
|
|
||
| grep GRAFANA_ADMIN_PASSWORD /opt/rosi-collector/.env |
There was a problem hiding this comment.
P2: The password-retrieval command is missing sudo, so it can fail with permission denied on the root-owned .env file.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At doc/source/deployments/rosi_collector/setup_walkthrough.rst, line 232:
<comment>The password-retrieval command is missing `sudo`, so it can fail with permission denied on the root-owned `.env` file.</comment>
<file context>
@@ -170,6 +224,27 @@ Then validate from the collector side and the Grafana UI:
+
+.. code-block:: bash
+
+ grep GRAFANA_ADMIN_PASSWORD /opt/rosi-collector/.env
+
+.. figure:: /_static/rosi-setup-grafana.png
</file context>
| grep GRAFANA_ADMIN_PASSWORD /opt/rosi-collector/.env | |
| sudo grep GRAFANA_ADMIN_PASSWORD /opt/rosi-collector/.env |
| sudo ufw allow 80/tcp | ||
| sudo ufw allow 443/tcp | ||
| sudo ufw allow 10514/tcp | ||
| sudo ufw allow 6514/tcp |
There was a problem hiding this comment.
P3: The firewall "minimum rule set" now unconditionally opens 6514/tcp, even though this port is only required when syslog TLS is enabled.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At doc/source/deployments/rosi_collector/setup_walkthrough.rst, line 164:
<comment>The firewall "minimum rule set" now unconditionally opens `6514/tcp`, even though this port is only required when syslog TLS is enabled.</comment>
<file context>
@@ -116,11 +135,36 @@ You are looking for a stable state where rsyslog, Loki, Grafana, Prometheus,
+ sudo ufw allow 80/tcp
+ sudo ufw allow 443/tcp
+ sudo ufw allow 10514/tcp
+ sudo ufw allow 6514/tcp
+
+If your environment also uses a provider firewall or security group, mirror the
</file context>
| sudo ufw allow 6514/tcp | |
| # Only needed when syslog TLS is enabled: | |
| sudo ufw allow 6514/tcp |
1 participant
Why
Provide a short operator path for ROSI Collector that gets readers
from initial setup to first-client validation without sending them
through multiple reference pages first.
Impact
Adds a new ROSI deployment walkthrough and links it into the docs nav.
Before/After
Before: ROSI docs had detailed reference pages but no compact end-to-end
setup flow.
After: ROSI docs include a generalized walkthrough for collector setup,
client onboarding, and first validation.
Technical Overview
Validation
Notes
not present in this checkout, so that exact packaging check could not be run
With the help of AI-Agents: Codex