TN-004 — Implement Production-Ready CI Pipeline for Tomcat Diagnostic Service¶

Field	Value
Status	Completed
Activity Type	Implementation
Record Type	Live
Project	Tomcat Monitoring
Phase	Continuous Integration and Deployment
Activity Date	2026-09-12
Recorded Date	2026-09-12
Owner	Eddy Wiyatno
Working Mode	Write
Authorization Status	Approved
Approved By	Eddy Wiyatno
Approval Date	2026-09-12

🎯 Objective¶

Mengimplementasikan berkas pipeline (alur otomasi) deklaratif Jenkinsfile berstandar Enterprise Production-Ready pada repositori tomcat-diagnostic-service untuk mengotomatisasi siklus Continuous Integration (CI) backend analitik insiden (Node.js 24 ESM, SQLite, Nodemailer) sesuai arsitektur TM-ADR-0024, desain CI/CD TN-001, dan standarisasi repositori TN-003.

Target Utama & Kriteria Keberhasilan:

Deklarasi Pipeline as Code Deklaratif: Menyusun berkas Jenkinsfile berbasis Declarative Pipeline Syntax yang mengeksekusi tahapan CI secara terstruktur pada dedicated build agent (kontainer pekerja khusus) berlabel builder (berbasis Rootless Podman / DooD — Docker-out-of-Docker via Podman socket).
Parameterisasi Fleksibel (6 Pilar Kesiapan Enterprise): Menyediakan parameter deklaratif REGISTRY_HOST (default: localhost), IMAGE_TAG (default: versi semver), dan PUSH_IMAGE (boolean, default: false) untuk portabilitas lokal maupun remote Enterprise Container Registry (seperti Harbor atau Nexus).
Penerapan Gerbang Mutu Bertingkat (Multi-Stage Quality Gates): Mengintegrasikan 7 tahapan quality gates berurutan secara otomatis mencakup Checkout Source Code, Verifikasi Non-Root Build Agent, Static Lint & Governance (scripts/validate.sh), Unit & Schema Testing (62 suites), Build & Pin OCI Image (scripts/build.sh), Ephemeral Smoke Test (scripts/test-image.sh), dan Publish Image ke registry enterprise secara kondisional.
Pembersihan Bersih (Post-Build Workspace Hygiene): Penegakan direktif cleanWs pada blok post.always untuk mencegah penumpukan artefak sementara di build agent.

🌍 Background¶

Pada tahapan perancangan arsitektur TN-001 dan standarisasi repositori TN-003, seluruh skrip operasional pada tomcat-diagnostic-service telah diubah agar bersifat path-agnostic (bebas dari keterikatan jalur direktori lokal host) dan mendukung parameterisasi registry.

Sebelumnya, pengembang harus menjalankan perintah npm test, validate.sh, dan build.sh secara manual di terminal workstation. Dengan mengimplementasikan berkas Jenkinsfile deklaratif ini, setiap commit atau pull request (pengajuan penggabungan kode) pada repositori tomcat-diagnostic-service akan diverifikasi secara otomatis, deterministik, dan bebas intervensi manual oleh Jenkins Controller melalui gerbang pengujian berlapis (fail-fast quality gates).

📚 Scope¶

Pekerjaan implementasi pipeline CI ini mencakup:

Pembuatan Berkas Pipeline as Code:
Penulisan berkas deklaratif Jenkinsfile pada repositori tomcat-diagnostic-service.
Penyelarasan Skrip Pengujian Gambar OCI:
Pembaruan scripts/test-image.sh agar mendukung parameter REGISTRY_HOST dan IMAGE_TAG dari Jenkins environment.
Penyelarasan Validator Tata Kelola:
Pendaftaran berkas Jenkinsfile pada daftar required_files di scripts/validate.sh.
Verifikasi Lokal Seluruh Tahapan:
Eksekusi simulasi seluruh tahapan (Stages 1 s.d. 6) pada lingkungan build agent untuk memastikan kelulusan 100%.
Exclusions:
Pendaftaran fisik job multibranch pada antarmuka web Jenkins Controller (dijadwalkan pada TN-007).
Implementasi pipeline CI untuk daemon tomcat-diagnostic-event-collector (dijadwalkan pada TN-005).
Implementasi pipeline CD untuk stack orchestrator tomcat-monitoring (dijadwalkan pada TN-006).

📋 Prerequisites¶

Runtime Podman rootless aktif pada agent eksekusi (builder).
Image dasar localhost/nodejs:24.18.0 dan base image digest immutable tersedia.
Repositori tomcat-diagnostic-service dalam status bersih (clean working tree) pasca-standarisasi TN-003.
Persetujuan Implementation Scope untuk penulisan berkas CI pipeline.

⚖️ Execution Decision¶

Mengadopsi keputusan arsitektur TM-ADR-0024: - Memilih model Decoupled Component CI untuk repositori mikrokomponen backend tomcat-diagnostic-service agar memberikan fast feedback loop (siklus umpan balik pengujian cepat dalam hitungan detik) secara mandiri tanpa membebani repositori orkestrator stack. - Menggunakan pola Docker-out-of-Docker (DooD) via Rootless Podman Socket pada agent pekerja (builder) untuk menjamin keamanan tanpa hak akses sudo atau eskalasi hak istimewa (privilege escalation).

🧭 Implementation Plan¶

Tahap	Rencana
Create Declarative Jenkinsfile	Menulis berkas deklaratif `Jenkinsfile` dengan 7 tahapan (stages) dan parameter enterprise.
Update Image Smoke Test and Validator	Menyesuaikan `scripts/test-image.sh` untuk portabilitas registry dan mendaftarkan `Jenkinsfile` pada `scripts/validate.sh`.
Verify Local Pipeline Stage Execution	Mengeksekusi seluruh tahapan pipeline secara lokal untuk memastikan kelulusan deterministik 100%.

⚙️ Implementation¶

flowchart TD
    subgraph CI_Pipeline["Diagnostic Service CI Pipeline (Jenkinsfile)"]
        S1["Stage 1: Checkout Source<br/>(Git SCM & Core Files)"]
        S2["Stage 2: Verify Agent<br/>(Rootless: true)"]
        S3["Stage 3: Static Lint<br/>& Governance (validate.sh)"]
        S4["Stage 4: Unit & Schema<br/>Testing (npm test / 62 suites)"]
        S5["Stage 5: Build & Pin<br/>OCI Image (build.sh)"]
        S6["Stage 6: Ephemeral<br/>Smoke Test (test-image.sh)"]
        S7["Stage 7: Publish Image<br/>(Conditional: PUSH_IMAGE)"]
        P1["Post Actions:<br/>cleanWs & Notification"]

        S1 --> S2 --> S3 --> S4 --> S5 --> S6 --> S7 --> P1
    end

Create Declarative Jenkinsfile¶

Membuat berkas deklaratif Jenkinsfile pada root repositori tomcat-diagnostic-service:

Menentukan agen target:
```
agent {
    label 'builder'
}
```

Mendefinisikan parameter konfigurasi:

parameters {
    string(name: 'REGISTRY_HOST', defaultValue: 'localhost', description: 'Enterprise Container Registry host')
    string(name: 'IMAGE_TAG', defaultValue: '', description: 'Custom OCI Image Tag (kosongkan untuk semver VERSION)')
    booleanParam(name: 'PUSH_IMAGE', defaultValue: false, description: 'Mendorong OCI image ke Enterprise Registry')
}

Menyusun blok tahapan eksekusi (stages) mencakup checkout, verifikasi rootless agent, linting statis, pengujian unit Node.js (62 suites), pembangunan OCI image, smoke test ephemeral container, dan publikasi image registry.

Menambahkan blok pembersihan pada post.always:

post {
    always {
        cleanWs deleteDirs: true, notFailBuild: true
    }
    success {
        echo "✔ DIAGNOSTIC SERVICE CI PIPELINE BERHASIL DISELESAIKAN DENGAN SUKSES!"
    }
    failure {
        echo "✘ DIAGNOSTIC SERVICE CI PIPELINE GAGAL PADA SALAH SATU QUALITY GATE."
    }
}

Expected Result

Berkas Jenkinsfile terbuat dengan sintaksis deklaratif Jenkins yang valid dan terstruktur rapi.

Update Image Smoke Test and Validator¶

Menyelaraskan skrip pendukung pengujian dan validator governance di tomcat-diagnostic-service:

Memperbarui scripts/test-image.sh untuk membaca variabel REGISTRY_HOST dan IMAGE_TAG:

REGISTRY_HOST="${REGISTRY_HOST:-localhost}"
IMAGE_TAG="${IMAGE_TAG:-${version}}"
image="${REGISTRY_HOST}/${project_name}:${IMAGE_TAG}"

Mendaftarkan Jenkinsfile ke dalam daftar berkas wajib pada scripts/validate.sh:

required_files=(
    AGENTS.md
    .containerignore
    Containerfile
    Jenkinsfile
    LICENSE
    README.md
    ...
)

Expected Result

Skrip scripts/test-image.sh dapat menguji OCI image dengan namespace/tag fleksibel, dan scripts/validate.sh memvalidasi keberadaan Jenkinsfile sebagai kontrak baku repositori.

Verify Local Pipeline Stage Execution¶

Mengeksekusi simulasi seluruh tahapan pipeline CI secara berurutan pada runtime Podman:

Validasi governance dan metadata:
```
bash scripts/validate.sh
```

Eksekusi pengujian unit terisolasi (62 suites):

podman run --rm \
    --userns=keep-id \
    --volume "$(pwd):/app:ro,Z" \
    --workdir /app \
    localhost/nodejs:24.18.0 \
    npm test

Pembangunan OCI image:
```
bash scripts/build.sh
```
Verifikasi OCI image (ephemeral smoke test):
```
bash scripts/test-image.sh
```

Expected Result

Seluruh tahapan pipeline CI dieksekusi tanpa kesalahan, 62 pengujian unit lulus 100%, OCI image berhasil dibangun dengan digest immutable, dan pengujian smoke test membuktikan integritas container image.

✅ Verification¶

Hasil eksekusi verifikasi tahapan pipeline CI pada repositori tomcat-diagnostic-service:

Tahapan Pipeline (Pipeline Stage)	Perintah Eksekusi	Hasil Aktual (Actual Result)	Status
Stage 1 — Checkout & Files	`test -f package.json VERSION CONFIG Containerfile Jenkinsfile`	Seluruh berkas kontrak inti tersedia.	🟢 PASS
Stage 2 — Agent Mode	`podman info --format '{{.Host.Security.Rootless}}'`	Output: `true` (Non-Root Execution terkonfirmasi).	🟢 PASS
Stage 3 — Static Lint	`bash scripts/validate.sh`	Static validation passed: schema, migration, source, and dependency boundaries are consistent.	🟢 PASS
Stage 4 — Unit & Schema Testing	`podman run ... npm test`	ℹ tests 62, pass 62, fail 0, skipped 0, duration: 554ms.	🟢 PASS
Stage 5 — Build & Pin Image	`bash scripts/build.sh`	Successfully built and tagged `localhost/tomcat-diagnostic-service:0.1.8` and `latest`.	🟢 PASS
Stage 6 — Ephemeral Smoke Test	`bash scripts/test-image.sh`	Metadata non-root, workingdir `/app`, OCI labels, clean file boundaries verified.	🟢 PASS

⚙️ Commands Executed¶

Seluruh perintah yang dieksekusi selama aktivitas implementasi ini dicatat dalam indeks berikut:

Kategori Tahapan	Perintah yang Dijalankan	Cakupan / Target
Pemeriksaan Repositori	`git -C /home/eddywiyatno/git/tomcat-diagnostic-service status --short`	Memastikan direktori kerja bersih sebelum perubahan
Penyusunan Jenkinsfile	Penulisan berkas `Jenkinsfile` deklaratif	Pembuatan kontrak otomasi CI backend analitik
Penyelarasan Skrip	Modifikasi `scripts/test-image.sh` dan `scripts/validate.sh`	Penyelarasan registry namespace dan governance rules
Simulasi CI Pipeline	`cd /home/eddywiyatno/git/tomcat-diagnostic-service` `./scripts/validate.sh` `podman run --rm -v $(pwd):/app:ro,Z -w /app localhost/nodejs:24.18.0 npm test` `./scripts/build.sh` `./scripts/test-image.sh`	Menjalankan seluruh tahapan CI secara berurutan
Source Control Commit	`git -C /home/eddywiyatno/git/tomcat-diagnostic-service add . && git commit -m "ci(pipeline): ..."`	Menyimpan rekaman perubahan berstandar Conventional Commits

🧾 Outcome¶

Berkas Declarative Jenkinsfile Terimplementasi: Repositori tomcat-diagnostic-service telah dilengkapi dengan berkas Jenkinsfile deklaratif berstandar enterprise yang mencakup 7 tahapan quality gates.
Kepatuhan 6 Pilar Produksi Enterprise: Pipeline mendukung portabilitas registry via parameter deklaratif, isolasi eksekusi non-root (Rootless Podman), dan pengujian kualitas menyeluruh (linting, 62 unit tests, OCI build, ephemeral smoke test).
Kesiapan Pendaftaran Job Jenkins Controller: Repositori siap diregistrasikan sebagai multibranch pipeline job pada Jenkins Controller pada tahap verifikasi akhir TN-007.

🎓 Lessons Learned¶

Keunggulan Parameterisasi Deklaratif: Menyediakan nilai default cerdas pada parameter Jenkinsfile (REGISTRY_HOST dan IMAGE_TAG) memungkinkan eksekusi pipeline berjalan mulus baik untuk build lokal workstation maupun rilis resmi ke registry enterprise kantor.
Pola Non-Root DooD Lebih Aman daripada DinD: Menghubungkan agen pekerja Jenkins ke socket Podman rootless host mengeliminasi kebutuhan hak akses privileged root serta mempercepat waktu build dengan memanfaatkan cache image host.
Pentingnya Ephemeral Smoke Test Sebelum Publikasi: Memverifikasi metadata kontainer dan runtime contract menggunakan kontainer sementara disposable sebelum mempublikasikan image ke registry mencegah penyebaran artefak yang rusak (bad artifact distribution).

⏭️ Next Steps¶

flowchart TD
    A["Completed<br/>TN-004: Diagnostic Service CI"] --> B["Next Stage<br/>TN-005: Event Collector CI<br/>(ShellCheck & Spool)"]
    B --> C["Next Stage<br/>TN-006: Stack CD Hub Pipeline<br/>(Atomic Deploy & Rollback)"]
    C --> D["Next Stage<br/>TN-007: Live Verification<br/>(Jenkins Controller)"]

Setelah implementasi CI pipeline pada tomcat-diagnostic-service selesai, langkah implementasi selanjutnya adalah:

Melanjutkan ke tahap TN-005 — Implement Production-Ready CI Pipeline for tomcat-diagnostic-event-collector untuk menulis berkas deklaratif Jenkinsfile bagi daemon pemantau event host Podman (ShellCheck, skema JSON event-record-v1, dan pengujian retensi spool).
Melanjutkan ke tahap TN-006 — Implement Stack Orchestration CD Pipeline for tomcat-monitoring untuk orkestrasi deployment platform multi-kontainer dan automated rollback.

TN-004 — Implement Production-Ready CI Pipeline for Tomcat Diagnostic Service¶

🎯 Objective¶

🌍 Background¶

📚 Scope¶

📋 Prerequisites¶

⚖️ Execution Decision¶

🧭 Implementation Plan¶

⚙️ Implementation¶

Create Declarative Jenkinsfile¶

Update Image Smoke Test and Validator¶

Verify Local Pipeline Stage Execution¶

✅ Verification¶

⚙️ Commands Executed¶

🧾 Outcome¶

🎓 Lessons Learned¶

⏭️ Next Steps¶

🔗 Related Documentation¶