1 files changed, 173 insertions, 0 deletions
diff --git a/doc/jenkins-cpp-build.md b/doc/jenkins-cpp-build.md
new file mode 100644
index 0000000..31d88e2
--- /dev/null
+++ b/doc/jenkins-cpp-build.md
@@ -0,0 +1,173 @@
+# Building a C++ App in Jenkins (Docker Agent)
+
+Step-by-step guide to set up a Jenkins pipeline that builds a C++ project
+using a Docker container as the build agent (DooD).
+
+
+## 1. Push your C++ project to the git server
+
+On the server, create a bare repo:
+
+```bash
+cd /var/git/repos
+git init --bare my-cpp-app.git
+chown -R 1000:1000 my-cpp-app.git
+```
+
+From your local machine, push your code:
+
+```bash
+cd /path/to/my-cpp-app
+git init
+git remote add origin ssh://git@<server-ip>/repos/my-cpp-app.git
+git add .
+git commit -m "Initial commit"
+git push -u origin master
+```
+
+
+## 2. Add a Jenkinsfile to your project
+
+Create a file called `Jenkinsfile` in the root of your C++ project.
+
+### Simple build (g++ directly)
+
+```groovy
+pipeline {
+    agent {
+        docker { image 'gcc:latest' }
+    }
+
+    stages {
+        stage('Build') {
+            steps {
+                sh 'g++ -o my_app main.cpp'
+            }
+        }
+
+        stage('Test') {
+            steps {
+                sh './my_app'
+            }
+        }
+    }
+}
+```
+
+Adjust the `g++` command to match your source files.
+
+### CMake build
+
+```groovy
+pipeline {
+    agent {
+        docker { image 'gcc:latest' }
+    }
+
+    stages {
+        stage('Configure') {
+            steps {
+                sh 'cmake -B build -S .'
+            }
+        }
+
+        stage('Build') {
+            steps {
+                sh 'cmake --build build'
+            }
+        }
+
+        stage('Test') {
+            steps {
+                sh 'cd build && ctest --output-on-failure'
+            }
+        }
+    }
+}
+```
+
+> Note: The `gcc:latest` image includes `g++`, `gcc`, `make`, and `cmake`.
+> If you need extra libraries (e.g., Boost), you can use a custom image or
+> add `apt-get install` steps.
+
+Commit and push the Jenkinsfile:
+
+```bash
+git add Jenkinsfile
+git commit -m "Add Jenkinsfile for CI"
+git push
+```
+
+
+## 3. Create the Jenkins pipeline job
+
+1. Open Jenkins at `https://jenkins.swave.lol` (or `https://swave.lol/jenkins`)
+2. Click **New Item** (top-left)
+3. Enter a name, e.g. `my-cpp-app`
+4. Select **Pipeline**, then click **OK**
+
+
+## 4. Configure the pipeline source
+
+On the job configuration page:
+
+1. Scroll down to the **Pipeline** section
+2. Change **Definition** from "Pipeline script" to **Pipeline script from SCM**
+3. Set **SCM** to **Git**
+4. In **Repository URL**, enter: `git://git-server/my-cpp-app.git`
+   - This works because Jenkins and git-server are on the same `jenkins_network` (172.23.0.0/16)
+   - `git-server` resolves to `172.23.0.3` via Docker DNS
+   - The git daemon protocol (`git://`) on port 9418 requires no credentials
+   - Alternative: `ssh://git@git-server/repos/my-cpp-app.git` (requires SSH key setup in Jenkins)
+5. Set **Branch Specifier** to `*/master` (or `*/main`, whatever your default branch is)
+6. **Script Path**: leave as `Jenkinsfile` (default)
+7. Click **Save**
+
+
+## 5. Run the build
+
+1. On the job page, click **Build Now** (left sidebar)
+2. A build number will appear under **Build History** — click it
+3. Click **Console Output** to watch the build live
+
+You will see Jenkins:
+- Pull the `gcc:latest` Docker image (first time only)
+- Spin up a temporary container on the host (DooD via `/var/run/docker.sock`)
+- Clone your repo inside the container
+- Run each stage (`Build`, `Test`)
+- Destroy the container when done
+
+
+## 6. Automatic builds (optional)
+
+### Option A — Poll SCM
+
+1. Go to job config (**Configure**)
+2. Under **Build Triggers**, check **Poll SCM**
+3. Set schedule, e.g. `H/5 * * * *` (check every 5 minutes)
+4. Click **Save**
+
+### Option B — Git post-receive hook
+
+Create a hook that notifies Jenkins immediately on push:
+
+```bash
+cat > /var/git/repos/my-cpp-app.git/hooks/post-receive << 'HOOK'
+#!/bin/bash
+curl -s "http://jenkins:8080/jenkins/git/notifyCommit?url=git://git-server/my-cpp-app.git" > /dev/null 2>&1 &
+HOOK
+chmod +x /var/git/repos/my-cpp-app.git/hooks/post-receive
+```
+
+This requires the **Git plugin** and **Poll SCM** to be enabled in the job
+config (the schedule can be empty, e.g. just `H * * * *`).
+
+
+## How DooD works
+
+Jenkins is configured with Docker-out-of-Docker: it mounts the host's
+`/var/run/docker.sock` into the Jenkins container. When the pipeline runs
+`docker { image 'gcc:latest' }`, Jenkins creates a **sibling container** on
+the host (not nested), runs the build steps inside it, and removes it after.
+The Jenkins container never needs compilers installed — everything runs in the
+ephemeral `gcc` container.