Skip to content

Commit 08cc600

Browse files
rgerhardsrgerhards
committed
doc: add ROSI setup walkthrough
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)
1 parent 1464698 commit 08cc600

File tree

4 files changed

+201
-0
lines changed

4 files changed

+201
-0
lines changed

‎doc/Makefile.am‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -305,6 +305,7 @@ EXTRA_DIST = \
305305
source/deployments/rosi_collector/index.rst \
306306
source/deployments/rosi_collector/installation.rst \
307307
source/deployments/rosi_collector/rosi-architecture.svg \
308+
source/deployments/rosi_collector/setup_walkthrough.rst \
308309
source/deployments/rosi_collector/troubleshooting.rst \
309310
source/development/architecture.rst \
310311
source/development/coding_practices.rst \

‎doc/source/deployments/index.rst‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,9 @@ monitoring stack including:
3030

3131
:doc:`Get started with ROSI Collector <rosi_collector/index>`
3232

33+
For the shortest operator path from fresh host to first client, use
34+
:doc:`ROSI Collector Setup Walkthrough <rosi_collector/setup_walkthrough>`.
35+
3336
For the beginner-level ROSI rationale (freedom of choice and avoiding
3437
vendor lock-in), see :doc:`../getting_started/rosi_for_beginners`.
3538

‎doc/source/deployments/rosi_collector/index.rst‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -140,10 +140,13 @@ All external access goes through Traefik, which handles TLS termination.
140140
Documentation Contents
141141
----------------------
142142

143+
If you want the fastest end-to-end path, start with :doc:`setup_walkthrough`.
144+
143145
.. toctree::
144146
:maxdepth: 1
145147
:caption: ROSI Collector Guide
146148

149+
setup_walkthrough
147150
architecture
148151
installation
149152
client_setup

‎doc/source/deployments/rosi_collector/setup_walkthrough.rst‎

Lines changed: 194 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,194 @@
1+
.. _rosi-collector-setup-walkthrough:
2+
3+
ROSI Collector Setup Walkthrough
4+
================================
5+
6+
.. meta::
7+
:description: End-to-end ROSI Collector walkthrough for standing up a collector, connecting a client, and validating logs and metrics.
8+
:keywords: rsyslog, ROSI Collector, setup, walkthrough, Grafana, Loki, Prometheus, client onboarding
9+
10+
.. summary-start
11+
12+
This walkthrough takes you from a fresh collector host to a working ROSI
13+
deployment with one enrolled client, visible logs, and basic metrics.
14+
15+
.. summary-end
16+
17+
Use this page when you want the shortest practical path to a working ROSI
18+
Collector environment. It connects the detailed guides into one operator flow:
19+
prepare the collector host, initialize the stack, enroll one client, and check
20+
that logs and metrics are visible in Grafana.
21+
22+
If you need deeper explanation for any step, jump to :doc:`installation`,
23+
:doc:`client_setup`, :doc:`grafana_dashboards`, or :doc:`troubleshooting`.
24+
25+
Outcome
26+
-------
27+
28+
At the end of this walkthrough you should have:
29+
30+
- A ROSI Collector host running Docker Compose services
31+
- One client forwarding logs to the collector
32+
- Optional host metrics visible through Prometheus and Grafana
33+
- A known-good validation path for future client onboarding
34+
35+
Before You Begin
36+
----------------
37+
38+
Prepare one Linux host for the collector and one additional Linux host to act
39+
as a client. The deployment scripts are tested on Ubuntu 24.04 LTS; nearby
40+
Debian-family distributions are the lowest-risk choice. Use a DNS name if you
41+
want browser-trusted HTTPS and simpler TLS setup for syslog clients. IP-only
42+
deployments work, but they usually rely on a self-signed certificate for the
43+
web interface.
44+
45+
Open the required network paths before you start:
46+
47+
- Collector inbound: ``80/tcp``, ``443/tcp``, ``10514/tcp``
48+
- Collector inbound when syslog TLS is enabled: ``6514/tcp``
49+
- Client inbound for metrics: ``9100/tcp``
50+
- Client inbound for impstats sidecar, if used: ``9898/tcp``
51+
52+
If your environment uses a cloud firewall or security group in addition to the
53+
host firewall, configure both layers. Avoid provider-specific assumptions and
54+
keep the allowed source ranges as narrow as your environment permits.
55+
56+
Step 1: Prepare the Collector Host
57+
----------------------------------
58+
59+
Clone the rsyslog repository and move to the ROSI Collector deployment:
60+
61+
.. code-block:: bash
62+
63+
git clone https://github.com/rsyslog/rsyslog.git
64+
cd rsyslog/deploy/docker-compose/rosi-collector
65+
66+
On a fresh host, install the baseline dependencies first:
67+
68+
.. code-block:: bash
69+
70+
sudo apt update
71+
sudo apt install -y git curl
72+
73+
If Docker is not installed yet and this is a new machine, run the bootstrap
74+
script once:
75+
76+
.. code-block:: bash
77+
78+
sudo ./scripts/install-server.sh
79+
80+
That script can install Docker and apply optional system changes. Use it only
81+
on hosts where those changes are expected. On an existing server, install
82+
Docker with your normal platform process and skip the bootstrap script.
83+
84+
Next, initialize the deployment:
85+
86+
.. code-block:: bash
87+
88+
sudo TRAEFIK_DOMAIN=logs.example.com \
89+
TRAEFIK_EMAIL=admin@example.com \
90+
./scripts/init.sh
91+
92+
The script copies the stack into the install directory, generates ``.env``,
93+
installs helper tools such as ``rosi-monitor`` and ``prometheus-target``, and
94+
can optionally configure the collector host to forward its own logs. Record the
95+
Grafana admin password shown at the end of the run.
96+
97+
Step 2: Start and Verify the Stack
98+
----------------------------------
99+
100+
Move to the generated install directory and start the services:
101+
102+
.. code-block:: bash
103+
104+
cd /opt/rosi-collector
105+
sudo docker compose up -d
106+
107+
Confirm that the core services are healthy:
108+
109+
.. code-block:: bash
110+
111+
sudo docker compose ps
112+
sudo rosi-monitor status
113+
curl http://localhost:3100/ready
114+
115+
You are looking for a stable state where rsyslog, Loki, Grafana, Prometheus,
116+
and Traefik are all up, and Loki returns ``ready``. If a service does not come
117+
up cleanly, stop here and use :doc:`troubleshooting` before onboarding clients.
118+
119+
.. figure:: /_static/dashboard-explorer.png
120+
:alt: Grafana Syslog Explorer dashboard in ROSI Collector
121+
:align: center
122+
123+
After client onboarding, Syslog Explorer is the fastest validation view.
124+
125+
Step 3: Enroll the First Client
126+
-------------------------------
127+
128+
On the client host, download the setup script from the collector and run it
129+
with elevated privileges:
130+
131+
.. code-block:: bash
132+
133+
wget https://logs.example.com/downloads/install-rsyslog-client.sh
134+
chmod +x install-rsyslog-client.sh
135+
sudo ./install-rsyslog-client.sh
136+
137+
Point the client at the collector hostname or IP and choose ``10514`` for
138+
plain TCP or ``6514`` if you already enabled TLS on the collector. The script
139+
tests the generated rsyslog configuration before it restarts the service.
140+
141+
For host metrics, install node_exporter on the client and register the target
142+
from the collector host:
143+
144+
.. code-block:: bash
145+
146+
wget https://logs.example.com/downloads/install-node-exporter.sh
147+
chmod +x install-node-exporter.sh
148+
sudo ./install-node-exporter.sh
149+
150+
sudo prometheus-target add-client 198.51.100.1 \
151+
host=web-01 role=web env=production network=internal
152+
153+
The ``add-client`` helper is the best default because it registers both node
154+
metrics and impstats sidecar metrics when present. If you only want basic host
155+
metrics, use ``prometheus-target add CLIENT_IP:9100 ...`` instead.
156+
157+
Step 4: Validate End-to-End Flow
158+
--------------------------------
159+
160+
Send a test event from the client:
161+
162+
.. code-block:: bash
163+
164+
logger "ROSI walkthrough test from $(hostname)"
165+
166+
Then validate from the collector side and the Grafana UI:
167+
168+
1. Open ``https://logs.example.com`` and sign in to Grafana.
169+
2. Open **Syslog Explorer** and narrow the time range to the last 15 minutes.
170+
3. Filter by the client hostname and confirm the test event appears.
171+
4. Open **Host Metrics Overview** and confirm that the client is visible.
172+
173+
If logs arrive but metrics do not, the most common cause is that port
174+
``9100/tcp`` is not reachable from the collector. If neither logs nor metrics
175+
arrive, verify DNS, firewall rules, and the client rsyslog restart result.
176+
177+
Production Follow-Up
178+
--------------------
179+
180+
After the first client works, repeat the same enrollment pattern for the rest
181+
of your hosts. For production hardening, the next high-value steps are:
182+
183+
- Enable syslog TLS and choose the appropriate auth mode in :doc:`installation`
184+
- Review dashboard usage and LogQL examples in :doc:`grafana_dashboards`
185+
- Use labels consistently when adding Prometheus targets
186+
- Keep one short validation checklist for every new client onboarding
187+
188+
See Also
189+
--------
190+
191+
- :doc:`installation` for the full install surface and environment variables
192+
- :doc:`client_setup` for manual forwarding and TLS client configuration
193+
- :doc:`grafana_dashboards` for dashboard behavior and query examples
194+
- :doc:`troubleshooting` for failure-oriented diagnostics

0 commit comments

Comments
 (0)