On Premise Docker Compose v2

A. Ringkasan & Definition of Done

Panduan ini menjalankan AlurKerja on-premises di mesin lokal menggunakan alurkerja-cli — CLI untuk operasional AlurKerja dengan command utama build-alurkerja. Command ini berjalan dua fase: Setup (3 step tetap) lalu Install yang dirakit sesuai konfigurasi — step yang tidak relevan (mis. Start postgres saat memakai database eksternal) tidak muncul sama sekali. Pipeline idempoten: step yang sudah selesai otomatis di-SKIP, jadi kalau gagal di tengah cukup jalankan ulang setelah masalahnya diatasi — tidak ada yang dikerjakan dua kali.

Definition of Done (DoD) — instalasi dianggap selesai bila:

• Pipeline build-alurkerja selesai sampai step Summary dan menampilkan daftar URL akses.
• Semua container dalam state running (docker compose ps tanpa Exited/Restarting).
• Aplikasi dapat diakses di http://localhost:8100 dan Keycloak di http://sso.localhost:8100.

Estimasi waktu eksekusi: ±20 menit untuk build pertama, paling lama di pull image (tergantung kecepatan internet). CLI menampilkan estimasi total di awal, estimasi per step di header-nya, dan durasi aktual tiap step selesai.

B. Prasyarat

Langkah 1–4 memastikan environment siap. Hentikan dan perbaiki bila ada langkah yang gagal — jangan lanjut sebelum prasyarat terpenuhi.

1. Verifikasi Docker Desktop berjalan

Aksi

docker version --format '{{.Server.Version}}'
docker compose version

Expected output

Versi Docker Engine dan Docker Compose version v2.x tampil tanpa error.

Jika gagal: pastikan Docker Desktop sudah terinstall dan dalam keadaan berjalan (ikon whale aktif). Di Linux, Docker Engine + plugin docker-compose-plugin juga bisa dipakai. Pipeline membutuhkan docker compose (V2, plugin) — bawaan Docker Desktop terbaru.

2. Verifikasi Git terpasang

Aksi

git --version

Expected output

git version 2.x.x atau lebih baru.

Jika gagal: install Git dari git-scm.com (Windows) atau xcode-select --install / Homebrew (macOS).

3. Verifikasi akun Harbor

Aksi

Pastikan kamu punya username + password Harbor yang valid (dipakai CLI untuk docker login dan pull image).

Expected output

Credential Harbor tersedia.

Jika gagal: minta credential Harbor ke tim Javan — registry image AlurKerja terpusat di harbor.merapi.javan.id.

4. Verifikasi free storage minimal 8 GB

Aksi

Pastikan drive tempat folder download punya minimal 8 GB free — image docker ±5 GB (29 image: postgres, keycloak, nginx, minio, mailpit, service AlurKerja, dll.) + ruang ekstrak saat pull + volume + code.

Get-PSDrive C   # lihat kolom Free — sesuaikan huruf drive tujuan

df -h ~   # lihat kolom Avail

Expected output

Free space drive tujuan minimal 8 GB.

Perhatian: CLI juga menampilkan kebutuhan ini di awal dan memberi warning kalau drive folder download kurang dari 8 GB.

C. Instalasi & Jalankan CLI

Langkah 5 punya dua cabang — pilih salah satu: 5.1 instalasi cepat (otomatis) atau 5.2 download manual. Keduanya berakhir sama: CLI terpasang dan pipeline build-alurkerja berjalan.

Perhatian: pipeline idempoten — aman dijalankan ulang kapan pun. Step yang sudah selesai ditandai SKIP.

5.1. Instalasi cepat (otomatis)

Aksi

Jalankan installer satu baris sesuai OS. Installer mendeteksi OS & arsitektur, mengunduh binary yang cocok, memasangnya ke PATH sebagai alurkerja, lalu langsung menjalankan build-alurkerja — tidak perlu Step 5.2, langsung lanjut ke Step 6:

irm https://docs.alurkerja.com/install.ps1 | iex

curl -fsSL https://docs.alurkerja.com/install.sh | bash

Expected output

Pesan Terpasang: <path> tampil, lalu pipeline build-alurkerja langsung berjalan.

Perhatian: perlu menjalankan ulang nanti? CLI sudah terpasang di PATH — cukup jalankan alurkerja build-alurkerja. Pipeline idempoten — aman dijalankan ulang kapan pun; step yang sudah selesai ditandai SKIP.

5.2. Download manual & jalankan binary

Aksi

Alternatif bila tidak memakai instalasi cepat (Step 5.1). Download binary sesuai OS:

Di macOS/Linux, beri permission executable (dan lepas quarantine di macOS):

chmod +x ./alurkerja-darwin-arm64
xattr -d com.apple.quarantine ./alurkerja-darwin-arm64   # macOS saja

Lalu jalankan command build-alurkerja dari binary yang di-download:

.\alurkerja-windows-amd64.exe build-alurkerja

./alurkerja-darwin-arm64 build-alurkerja

Expected output

File binary ter-download, lalu pipeline mulai berjalan dan menampilkan fase Setup.

D. Eksekusi Pipeline build-alurkerja

6. Isi input yang diminta

Aksi

Semua kredensial bisa lewat prompt interaktif (password tersembunyi) atau flag. Input utama:

Lalu di Setup features (Setup step 3) muncul satu layar toggle untuk 5 resource: panah atas/bawah pindah baris, enter/spasi mengganti local↔external, enter di Continue melanjutkan (terminal non-interaktif: menu bernomor per fitur). Default semua local (container bawaan) — untuk instalasi standar cukup langsung Continue. Resource yang di-set external ditanya detail koneksinya (langsung dites, fail-fast) dan container bawaannya tidak dijalankan:

Di akhir wizard ada pertanyaan Application secrets: generate otomatis (default) atau masukkan 4 secret existing — --tenant-encryption-key, --tenant-encryption-iv, --jwt-secret, --jwt-refresh-secret (base64, input tersembunyi). Wajib memakai secret yang sama saat memakai database bekas instalasi sebelumnya, karena data terenkripsi butuh kunci yang sama. All-or-nothing: isi keempatnya atau tidak sama sekali (parsial = error).

Referensi lengkap semua variabel .env — termasuk mana yang di-generate otomatis oleh installer dan mana yang diisi user — ada di Section H.

Expected output

Semua prompt terisi dan layar fitur dikonfirmasi — pipeline lanjut ke fase Install dengan estimasi total dan daftar step hasil rakitan.

Perhatian: fitur yang sudah ditentukan lewat flag tidak muncul lagi di layar toggle. Pada instalasi existing (.env sudah ada), CLI menawarkan Do nothing (konfigurasi saat ini dipertahankan) atau Reconfigure features. Kembali ke mode local kapan pun — nilai .env terkait dikembalikan ke bawaan lokal otomatis. Detail lengkap tiap mode external (nilai .env yang ditulis, perilaku container) ada di README repo alurkerja-cli.

7. Pantau pipeline sampai selesai

Aksi

Biarkan pipeline berjalan. Fase Setup selalu 3 step:

Fase Install dirakit dari hasil Setup — jumlah step menyesuaikan konfigurasi:

Alur untuk mode default (semua resource local):

Expected output

Step Summary tampil dengan daftar URL akses.

Jika gagal: baca pesan errornya, perbaiki penyebabnya (mis. Docker belum jalan), lalu jalankan ulang command yang sama — step yang sudah beres di-SKIP. Lihat juga Section F.

E. Verifikasi & Akses Pertama Kali

8. Validasi semua container running

Aksi

Dari folder download (lihat lokasi yang dipilih di Step 6):

docker compose ps

Expected output

Semua container berstatus running/healthy — tidak ada Exited atau Restarting.

Jika gagal: kalau ada container yang crash loop, cek log: docker compose logs --tail=50 <service>.

9. Akses aplikasi

Aksi

Buka URL berikut di browser (sesuai output Summary). Port diambil dari .env: AK_PORT_NGINX untuk semua URL http (default 8100) dan AK_PORT_POSTGRES untuk database (default 8101) — resource yang di-set eksternal tampil dengan alamat eksternalnya:

Expected output

Halaman App ter-render di http://localhost:8100 dan admin console Keycloak dapat diakses di http://sso.localhost:8100.

Perhatian: kalau suatu saat instalasi lokal ini sudah tidak dipakai dan ingin dihapus tuntas (stack, volume, folder download, image), ikuti Section I. Cleanup Instalasi Lokal.

F. Troubleshooting

• Gagal di tengah? Baca pesan errornya, perbaiki penyebabnya (mis. Docker belum jalan), lalu jalankan ulang — step yang sudah beres di-SKIP.
• Port bentrok? Step Cek port bentrok menyebutkan pemegang portnya. Stack AlurKerja lama dengan nama berbeda: matikan dengan docker compose -p <nama-project> down; proses non-Docker: tutup aplikasinya dulu.
• Proses terputus saat init database? Cukup jalankan ulang — step Load public & camunda schema selalu diulang dan idempoten. Kasus sangat jarang: init_db terputus tepat setelah membuat keycloak_db tapi sebelum schema camunda dibuat → drop database keycloak_db lalu jalankan ulang.
• Error $'\r': command not found saat setup Keycloak: hasil download lama masih ber-CRLF (dari versi CLI lama). Hapus folder download lalu jalankan ulang — download baru selalu LF.

Lihat juga Handbook Troubleshooting untuk daftar lebih luas.

G. Logbook Instalasi

Template berikut sinkron 1:1 dengan nomor langkah di halaman ini.

H. Variabel Environment

Referensi status semua variabel .env (file tunggal di root folder download). Status ditentukan bukan sekadar "ada isinya di .env" — tapi dari nalar: apakah service benar-benar berhenti/rusak tanpanya, atau tetap jalan dengan fallback/fitur nonaktif. Variabel alias (mis. DB_USER=${POSTGRES_USER}) mengikuti status sumbernya dan ditandai (alias, otomatis) — tidak perlu diisi manual terpisah.

• Wajib — tanpa nilai yang benar, service terkait gagal start atau fitur intinya patah.
• Optional — sudah ada default yang aman, atau memang integrasi/fitur tambahan yang boleh dikosongkan (fitur terkait nonaktif secara aman, bukan error).
• Tanda (installer: …) — nilai ini di-generate/ditulis otomatis oleh installer alurkerja-cli (build-alurkerja): nilai Keycloak dari setup-keycloak.sh dan application secrets dari step Generate secrets. Jangan diisi manual duluan — installer hanya mengisi nilai yang masih kosong/placeholder dan tidak pernah me-rotate nilai yang sudah ada. Variabel tanpa tanda ini diisi user (langsung di .env, atau lewat wizard/flag installer untuk mode eksternal). Instalasi manual tanpa CLI: semua diisi sendiri.

1. Database Configuration (PostgreSQL)

Prasyarat Schema Database (public.sql) — Extension pgvector

config/public.sql (schema utama) butuh extension pgvector (vector) dan pg_trgm aktif di server PostgreSQL sebelum dijalankan — dipakai untuk kolom embedding (knowledge_chunks) dan pencarian trigram. Script ini sudah punya pre-flight check di baris awal yang akan gagal dengan pesan jelas kalau extension belum tersedia, daripada error samar di tengah jalan.

Postgres internal (docker-compose bawaan): sudah otomatis tersedia — service postgres di docker-compose.yml memakai image pgvector/pgvector:pg16 (bukan postgres:16-alpine polos). Tidak perlu langkah tambahan.

Postgres eksternal (mode --database external / managed sendiri): pgvector harus sudah terpasang/aktif di server tersebut sebelum menjalankan public.sql:

• Managed cloud Postgres (AWS RDS/Aurora, Supabase, Neon, Google Cloud SQL, Azure Database for PostgreSQL Flexible Server, dll) — pgvector biasanya sudah tersedia dari provider, cukup pastikan bisa CREATE EXTENSION vector; (script ini sudah melakukannya otomatis).
• Server self-managed (VM/bare metal sendiri) — install manual dulu mengikuti dokumentasi resmi pgvector.

2. Keycloak Configuration

3. MinIO / Storage Configuration

4. Redis / Cache Configuration

5. Sentry Configuration

6. OpenAI Configuration

7. Email Configuration (Notification & Tenant Management)

8. JWT Configuration

9. Encryption Configuration (Tenant Settings)

10. Camunda Configuration (Migration Service)

11. GitLab Configuration (fitur tambahan — incident tracking)

12. Laravel Passport Configuration

13. Website / Application URL

14. Service Port Configuration

15. HTTP / Server Configuration

16. Router Service Specific

17. Report Service — Queue Processor

18. Generate Test Service Specific

19. Upload Configuration

20. Nginx / Domain Configuration

21. MinIO Configuration (Additional)

22. Telegram Bot Configuration

23. Onboarding Configuration

24–28. Integrasi Eksternal Opsional (kosong secara default)

Grup-grup berikut kosong di .env bawaan dan murni integrasi tambahan — aplikasi inti jalan normal tanpa ini, fitur terkait cuma nonaktif:

29. Service Camunda Configuration

30–31. Database Integrasi Eksternal (kosong secara default)

32. WhatsApp API Configuration

33. Webhook Configuration

34. Integration Configuration

35. App Configuration

36. Frontend — Runtime Injection (app-react & studio-react)

Di-inject ke conf.js saat container start via docker-entrypoint.sh.

37. Microsite Configuration (Next.js Application)

38. Frontend — Build-time Only (compro-react & simulation-react)

Bukan variabel di .env root. Image compro-react dan simulation-react tidak punya docker-entrypoint.sh untuk runtime injection, jadi VITE_* harus diisi manual di file terpisah sebelum image di-build:

• builds/compro-react/.env → VITE_API_BASEURL, VITE_API_TASKLIST_BASEURL, VITE_AUTH_METHOD, VITE_KEYCLOAK_*, VITE_SENTRY_DSN — Wajib diisi sebelum build, atau FE ini salah konfigurasi permanen sampai di-build ulang.
• builds/simulation-react/.env → VITE_KEYCLOAK_*, VITE_API_BASE_URL, VITE_SENTRY_DSN (opsional) — sama alasan.

I. Cleanup Instalasi Lokal

CLI belum menyediakan perintah teardown (down/cleanup) — jadi penghapusan tuntas dilakukan manual dengan urutan berikut: matikan stack dulu, baru hapus folder.

1. Stop stack & hapus volume

Nama project compose diambil dari field name: di docker-compose.yml — bawaan repo: alurkerja (kalau field tidak ada, compose memakai nama folder download dalam huruf kecil). Karena memakai -p, command bisa dijalankan dari folder mana pun:

docker compose -p alurkerja down -v

Expected: semua container dan volume terhapus — docker compose ls --all tidak lagi menampilkan project alurkerja.

2. Hapus folder download

Hapus folder yang dipilih di Step 6 (berisi docker-compose.yml, .env, config/):

Remove-Item -Recurse -Force D:\path\ke\folder-download

rm -rf /path/ke/folder-download

Perhatian: .env (termasuk application secrets) ikut terhapus bersama folder ini dan tidak bisa dipulihkan.

3. Logout Harbor

docker logout harbor.merapi.javan.id

4. Hapus image — opsional, mengosongkan ±5 GB

Image tetap tersimpan setelah down. Hapus semua image AlurKerja dari Harbor (command sama untuk PowerShell maupun bash):

docker rmi $(docker images -q "harbor.merapi.javan.id/alurkerja-v2/*")

Image publik pendukung (nginx, keycloak, pgvector, redis, minio, mailpit) bisa dibersihkan dengan docker image prune -a — perhatian: perintah ini menghapus semua image yang tidak dipakai container mana pun, termasuk milik project lain.

Expected akhir: docker compose ls --all tanpa project alurkerja, folder download tidak ada, dan docker images tanpa image harbor.merapi.javan.id/alurkerja-v2/*.