From a984b1c7d3c881e12de76587d27ab3f29c6dd66c Mon Sep 17 00:00:00 2001
From: Emil Shanaty <65846814+emil28092005@users.noreply.github.com>
Date: Tue, 3 Feb 2026 23:40:18 +0300
Subject: [PATCH] Update README.md

---
 infra/jenkins/README.md | 86 +++++++++++++++++++++--------------------
 1 file changed, 44 insertions(+), 42 deletions(-)

diff --git a/infra/jenkins/README.md b/infra/jenkins/README.md
index a5c8dfc..b391608 100644
--- a/infra/jenkins/README.md
+++ b/infra/jenkins/README.md
@@ -1,13 +1,15 @@
-# Jenkins (Controller + Docker Agent) Setup (Docker Compose)
+# Jenkins Controller + Docker Agent (Docker Compose)
 
-This directory contains a minimal Jenkins setup using a dedicated **controller** and a separate inbound **agent** intended for Docker-based workloads.
+This directory contains a minimal Jenkins setup running as Docker containers:
+- `jenkins-controller`: Jenkins UI + configuration (no builds should run here).
+- `jenkins-agent-docker`: inbound agent used for Docker-based pipelines (label: `docker-agent`).
 
-The goal is to keep the controller responsible for orchestration and configuration, while all builds run on the agent labeled `docker`.
+The goal is to keep the controller responsible for orchestration/configuration while all CI jobs run on the dedicated agent.
 
 ## Prerequisites
-- Docker Engine installed on the host
-- Docker Compose available as `docker compose`
-- A host directory `/opt/shagram` (used by pipelines as a shared location for source code and deployment files)
+- Docker Engine installed on the host.
+- Docker Compose available as `docker compose`.
+- A host directory `/opt/shagram` (used by pipelines as a shared location for source code and deployment files).
 
 ## Start Jenkins
 From the repository root:
@@ -20,59 +22,59 @@ docker compose ps
 
 Jenkins UI will be available at:
 
-- http://<server-ip>:8080
-
-### Initial admin password
-Retrieve the initial password with:
-
-```bash
-docker exec -it jenkins-controller cat /var/jenkins_home/secrets/initialAdminPassword
+```text
+http://<server-ip>:8080
 ```
 
-## Disable builds on the built-in node (Executors = 0)
+## Initial admin password
+Retrieve the initial password:
+
+```bash
+docker exec -it jenkins-controller \
+  cat /var/jenkins_home/secrets/initialAdminPassword
+```
+
+## Disable builds on the controller
 To ensure builds do not run on the controller:
+1. Open Jenkins UI.
+2. Go to: `Manage Jenkins` → `Manage Nodes and Clouds`.
+3. Open: `Built-In Node` → `Configure`.
+4. Set **Number of executors** to `0`.
+5. Save.
 
-1. Open Jenkins UI
-2. Go to: **Manage Jenkins → Manage Nodes and Clouds**
-3. Open **Built-In Node → Configure**
-4. Set **Number of executors** to `0`
-5. Save
-
-## Create an inbound agent node (docker-agent)
+## Configure the inbound agent node
 Create a dedicated node for running pipelines:
-
-1. Go to: **Manage Jenkins → Manage Nodes and Clouds → New Node**
+1. `Manage Jenkins` → `Manage Nodes and Clouds` → `New Node`.
 2. Set:
-   - **Node name**: `docker-agent`
-   - **Type**: Permanent Agent
-   - **Remote root directory**: `/home/jenkins/agent`
-   - **Labels**: `docker`
-   - **Usage**: Only build jobs with label expressions matching this node
-3. Save
+   - Node name: `docker-agent`
+   - Type: `Permanent Agent`
+   - Remote root directory: `/home/jenkins/agent`
+   - Labels: `docker-agent` (must match your Jenkinsfile `agent { label ... }`)
+   - Usage: “Only build jobs with label expressions matching this node”
+3. Save.
 
 After saving, open the agent page:
+- `Manage Nodes and Clouds` → `docker-agent`
 
-- **Manage Nodes and Clouds → docker-agent**
+On that page Jenkins will show the inbound connection details, including the **secret** required by the inbound agent container.
 
-On that page, Jenkins provides the inbound connection details, including the **secret** required by the inbound agent container.
+## Set agent secret in Compose
+Edit `infra/jenkins/compose.yaml` and replace the placeholder with the real secret value shown on the `docker-agent` node page:
 
-## Configure the agent secret in Compose
-Edit `infra/jenkins/compose.yaml` and replace:
+- `JENKINS_SECRET=PASTE_ME`
 
-- `JENKINS_SECRET=__PASTE_ME__`
-
-with the real secret value shown on the `docker-agent` node page.
-
-Restart only the agent container:
+Then restart only the agent container:
 
 ```bash
 docker compose up -d --force-recreate jenkins-agent-docker
 docker logs -f jenkins-agent-docker
 ```
 
-## Verification
-- In Jenkins UI: **Manage Nodes and Clouds**, the node `docker-agent` should be **Online**
-- Any pipeline using `agent { label 'docker' }` should execute on this agent
+Verification:
+- In Jenkins UI, the node `docker-agent` should become **Online**.
+- Any pipeline using `agent { label 'docker-agent' }` should execute on this agent.
 
 ## Security note
-The Docker agent container mounts `/var/run/docker.sock`, which effectively grants high-level control over the Docker host. Use this setup only in trusted environments and limit access to Jenkins accordingly.
+The Docker agent mounts `/var/run/docker.sock`, which effectively grants high-level control over the Docker host.
+
+Use this setup only in trusted environments and limit access to Jenkins accordingly.