VPS

A. Ringkasan & Definition of Done

Panduan ini memasang AlurKerja di satu VPS Ubuntu yang masih kosong menggunakan Cloud Installer (cloud-install.sh). Satu perintah menanyakan isian yang dibutuhkan, memasang Docker dan AlurKerja CLI, membangun AlurKerja, mengaktifkan HTTPS untuk domain, lalu menjalankan validasi akhir. Langkahnya berlaku untuk penyedia VPS mana pun selama prasyaratnya terpenuhi.

Definition of Done — instalasi dianggap selesai bila:

• Installer berakhir dengan AlurKerja siap: https://<DOMAIN> dan seluruh validasi akhir berstatus [PASS].
• https://<DOMAIN> terbuka di browser tanpa peringatan sertifikat.
• Admin berhasil login, mengganti password awal, dan Developer License berstatus Active.
• Menu aplikasi (My Workspaces, Home, My Tasks) ter-render tanpa error.

Estimasi waktu eksekusi: 30–45 menit, termasuk menyiapkan VPS dan domain. Tahap build AlurKerja sendiri memakan 10–20 menit.

Versi yang divalidasi:

B. Prasyarat

Cloud Installer memeriksa sendiri sistem operasi, RAM, disk, port, dan kredensial Harbor sebelum mengubah apa pun di server. Siapkan kebutuhan berikut lebih dulu.

C. Menyiapkan VPS dan Domain

Langkah 1–2 menyiapkan server dan domain.

1. Buat VPS

Aksi

Buat VPS di penyedia pilihan dengan ketentuan berikut:

• sistem operasi Ubuntu 24.04 LTS (image sistem operasi, bukan image aplikasi siap pakai);
• RAM minimal 8 GB dan ruang disk kosong minimal 30 GB setelah sistem operasi terpasang;
• alamat IPv4 publik;
• port 22, 80, dan 443 terbuka di firewall penyedia (bila ada).

Expected output

VPS berstatus berjalan dan memiliki alamat IPv4 publik. Catat IP publik ini sebagai <IP_VPS> dan username login sebagai <USER>.

Jika gagal: kalau port 22, 80, atau 443 tertutup, buka di pengaturan firewall atau security group penyedia VPS.

2. Siapkan domain

Aksi

Siapkan domain atau subdomain yang record DNS-nya bisa diubah, lalu catat sebagai <DOMAIN>. Record DNS-nya dibuat di langkah 6, setelah installer menampilkan IP publik VPS.

Expected output

Pengelola DNS untuk <DOMAIN> bisa dibuka dan diubah.

Jika gagal: kalau belum punya domain, gunakan subdomain dari layanan DNS yang mengizinkan pembuatan record A. Contohnya ada di Contoh Domain DuckDNS.

D. Instalasi

Langkah 3–7 masuk ke VPS, menjalankan installer, dan mengarahkan domain.

3. Masuk ke VPS lewat SSH

Aksi

Dari terminal laptop (PowerShell di Windows, Terminal di macOS atau Linux):

ssh <USER>@<IP_VPS>

Saat pertama kali tersambung, ketik yes, lalu masukkan password VPS. Password tidak terlihat saat diketik.

Expected output

Are you sure you want to continue connecting (yes/no/[fingerprint])? yes
Warning: Permanently added '<IP_VPS>' (ED25519) to the list of known hosts.
<USER>@<IP_VPS>'s password:
<USER>@<HOSTNAME>:~$

Jika gagal: Connection timed out berarti port 22 tertutup atau IP salah; Permission denied berarti username atau password salah.

4. Masuk sebagai root

Aksi

sudo -i

Masukkan password yang sama dengan langkah 3. Lewati langkah ini bila sudah login sebagai root.

Expected output

Prompt berubah menjadi root@<HOSTNAME>:~#.

Jika gagal: kalau muncul pesan is not in the sudoers file, minta akses sudo ke pengelola VPS atau login langsung sebagai root.

5. Jalankan installer

Aksi

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

Installer menanyakan empat isian, lalu meminta konfirmasi; jawab y untuk memulai. Isian yang tidak valid ditanyakan ulang, maksimal tiga kali.

Expected output

AlurKerja Cloud Installer

  Isi data berikut untuk memulai instalasi.
  Username Harbor (dari email pendaftaran): <USERNAME_HARBOR>
  Password Harbor (tidak terlihat saat diketik):
  Email admin untuk login pertama: <EMAIL_ADMIN>
  Domain (misalnya …): <DOMAIN>

  Domain  : <DOMAIN> (HTTPS)
  Email   : <EMAIL_ADMIN>
  Folder  : /opt/alurkerja
  Langkah : 7

  Lanjutkan instalasi? [y/N]: y

[1/7] Cek prasyarat server
      Ubuntu 24.04 (amd64), RAM 7,8 GB, disk kosong cukup, port 80 dan 443 siap
      Akun Harbor dan akses image: OK
      IP publik server: <IP_VPS>
      ✓ selesai (17 dtk)

Setelah cek prasyarat, installer menampilkan record DNS yang perlu dibuat, lalu tetap melanjutkan instalasi. Bila domain sudah mengarah ke VPS, bagian ini tidak muncul.

! Tambahkan record DNS ini di pengelola domain Anda sekarang. Instalasi tetap berjalan.

      Tipe  : A
      Nama  : <DOMAIN>
      Nilai : <IP_VPS>

  Hapus record A atau AAAA lain untuk nama ini, dan matikan proxy CDN (misalnya awan oranye Cloudflare).

Jika gagal: kalau installer berhenti sebelum atau di [1/7] Cek prasyarat server, lihat Skenario 1.

6. Arahkan domain ke IP publik VPS

Aksi

Biarkan installer tetap berjalan. Di pengelola DNS domain, buat record sesuai yang ditampilkan installer:

Nilai diisi IP publik VPS dari baris Nilai di layar installer, bukan IP internet laptop dan bukan IP privat (yang diawali 10., 172.16. sampai 172.31., atau 192.168.). Contoh untuk DuckDNS ada di Contoh Domain DuckDNS.

Hapus record A atau AAAA lain untuk nama yang sama. Bila memakai Cloudflare, matikan proxy (awan oranye menjadi abu-abu, DNS only).

Expected output

Cek dari terminal laptop:

nslookup <DOMAIN> 8.8.8.8

Hasilnya menampilkan alamat <IP_VPS>.

Jika gagal: perubahan DNS kadang perlu beberapa menit. Installer baru memeriksa DNS setelah tahap build dan menunggunya sampai 30 menit. Selama menunggu, installer menampilkan sekarang: A=…; kalau angkanya bukan <IP_VPS>, perbaiki record A.

7. Tunggu instalasi selesai

Aksi

Biarkan installer menyelesaikan ketujuh tahapnya. Jangan menutup terminal atau memutus koneksi SSH.

Expected output

[7/7] Validasi akhir
      Memeriksa hasil instalasi (bisa beberapa menit selama layanan menyala)
      [PASS] All containers running or healthy
      [PASS] Configuration uses https://<DOMAIN>
      [PASS] DNS A record <DOMAIN> -> <IP_VPS>
      [PASS] HTTP redirects to HTTPS
      [PASS] Trusted HTTPS certificate valid for <DOMAIN>
      [PASS] Application page opens over HTTPS
      [PASS] Keycloak responds (issuer https://<DOMAIN>/sso/realms/alurkerja)
      [PASS] Keycloak login page accepts the application redirect URI
      [PASS] Keycloak keys reachable from inside the stack
      [PASS] Public access via https://<DOMAIN>
      ✓ selesai (8 dtk)

✓ AlurKerja siap: https://<DOMAIN>

  Login admin
    Email    : <EMAIL_ADMIN>
    Password : <PASSWORD_AWAL>
               Password awal; AlurKerja meminta password baru saat login pertama.
    Camunda  : login sekali di https://<DOMAIN>/camunda dengan akun <AKUN_CAMUNDA>
  ! Bagian ini berisi password: jangan dipotret atau dibagikan.
  Lisensi : setelah login, masukkan lisensi AlurKerja lewat aplikasi.

ALURKERJA_URL=https://<DOMAIN>

Password awal dipakai saat login pertama (langkah 9). Akun Camunda hanya diperlukan untuk menjalankan proses BPMN.

Jika gagal: baca baris ERROR: terakhir, perbaiki penyebabnya, lalu jalankan lagi perintah di langkah 5. Installer aman dijalankan ulang tanpa menghapus data — Docker dan CLI yang sudah terpasang dipakai ulang, record DNS tidak diminta lagi bila sudah benar, dan bila cek prasyarat pernah lolos, isian sebelumnya (kecuali password) ditawarkan lagi sehingga cukup tekan Enter. Gejala umum ada di F. Troubleshooting.

Alternatif langkah 5: isian lewat env-file

Untuk instalasi otomatis tanpa terminal interaktif (misalnya cloud-init), isian bisa diberikan lewat file yang hanya bisa dibaca root:

install -m 600 /dev/null /root/alurkerja-installer.env
nano /root/alurkerja-installer.env

AK_HARBOR_USER=<USERNAME_HARBOR>
AK_HARBOR_PASSWORD='<PASSWORD_HARBOR>'
AK_ADMIN_EMAIL=<EMAIL_ADMIN>
AK_DOMAIN=<DOMAIN>

curl -fsSL https://cli.alurkerja.com/cloud-install.sh | bash -s -- --env-file /root/alurkerja-installer.env

Bila keempat isian lengkap, installer langsung berjalan tanpa pertanyaan dan konfirmasi. Bila output installer tidak ke terminal (misalnya dialihkan ke file log), ringkasan akhir menampilkan perintah untuk melihat password awal dan akun Camunda, bukan isinya:

sudo grep -m1 '^PLATFORM_OWNER_PASSWORD=' /var/lib/alurkerja-installer/build.log | cut -d= -f2-
sudo grep -m1 -E '^Camunda +:' /var/lib/alurkerja-installer/build.log

E. Akses Pertama Kali

Langkah 8–13 melakukan login pertama, aktivasi lisensi, dan pengecekan menu.

8. Buka aplikasi

Aksi

Buka https://<DOMAIN> di browser.

Expected output

Karena lisensi belum aktif, halaman Not licensed yet tampil dengan tombol Activate this installation.

Jika gagal: kalau halaman tidak terbuka atau muncul peringatan sertifikat, periksa kembali hasil validasi akhir di langkah 7.

9. Login sebagai admin

Aksi

1. Klik Activate this installation. Halaman Authentication Required tampil.
2. Klik Login, lalu masuk dengan email admin dan password awal dari langkah 7.

Expected output

Halaman Update password tampil.

Jika gagal: kalau ringkasan tidak menampilkan password (misalnya admin sudah dibuat di run sebelumnya), jalankan perintah yang tertera di ringkasan untuk melihat password awal.

10. Ganti password awal

Aksi

1. Isi password baru, ulangi, lalu klik Submit.
2. Bila muncul Update Account Information, isi First name dan Last name, lalu klik Submit.

Expected output

Login selesai dan halaman Not licensed yet tampil kembali.

11. Buka menu License di Console

Aksi

Klik Activate this installation sekali lagi.

Expected output

Halaman License di Console terbuka (https://<DOMAIN>/admin/license) dengan Status Not activated yet serta tab Customer License dan Developer License.

12. Aktifkan Developer License

Aksi

Pilih tab Developer License, isi Robot username dengan username Harbor dan Robot password dengan password Harbor, sama seperti yang diisi di langkah 5, lalu klik Activate developer license. Penjelasan lengkap ada di License › Developer License.

Expected output

Status menjadi Active dan License kind menjadi Developer License.

Jika gagal: kalau tab menampilkan Customer License is active, nonaktifkan dulu Customer License sesuai aturan di halaman License.

13. Buka menu aplikasi

Aksi

1. Buka kembali https://<DOMAIN>. Halaman My Workspaces tampil.
2. Klik Create new workspace, beri nama, lalu buka workspace tersebut.
3. Buka menu Home dan My Tasks.

Expected output

Workspace terbuka dan setiap menu ter-render tanpa error.

F. Troubleshooting

Empat skenario yang paling umum saat instalasi. Lihat juga Handbook Troubleshooting untuk daftar lebih luas.

Skenario 1: Installer berhenti di awal (kode 10)

Gejala

• Installer berhenti sebelum atau di [1/7] Cek prasyarat server dengan baris ERROR: berkode 10.

Aksi remediasi

1. Jalankan sebagai root… — jalankan langkah 4, lalu ulangi langkah 5.
2. Isian … tidak valid, Instalasi dibatalkan, atau Input wajib belum diisi… — jalankan ulang langkah 5 langsung di terminal SSH, isi sesuai contoh yang ditampilkan, lalu jawab y saat konfirmasi.
3. RAM minimal 8 GB…, Ruang disk kosong minimal 30 GB…, Installer ini hanya mendukung Ubuntu 24.04, atau Server ARM belum didukung… — ganti paket atau sistem operasi VPS, lalu ulangi dari langkah 1.
4. Port 80 atau 443 sedang dipakai layanan lain — hentikan layanan yang memakai port tersebut, atau gunakan VPS baru.
5. Pemeriksaan Harbor gagal… — salin ulang username dan password dari email kredensial Harbor, lalu jalankan ulang langkah 5. Kalau masa berlaku aksesnya sudah lewat, minta perpanjangan ke admin.
6. Folder instalasi sudah berisi file…, Ada instalasi AlurKerja lain…, Ada volume database AlurKerja lama…, atau Ada paket Docker lain yang bentrok… — server tidak dalam kondisi kosong; gunakan VPS baru.

Skenario 2: DNS tidak kunjung mengarah ke VPS (kode 60)

Gejala

• Tahap Menunggu DNS terus menampilkan Menunggu <DOMAIN> -> <IP_VPS> (sekarang: A=… AAAA=…; sisa … mnt), lalu berhenti setelah 30 menit dengan pesan DNS <DOMAIN> belum mengarah hanya ke <IP_VPS>….

Aksi diagnostik

nslookup <DOMAIN> 8.8.8.8
nslookup <DOMAIN> 1.1.1.1

Hasil yang benar hanya berisi satu alamat, yaitu <IP_VPS>, tanpa alamat IPv6.

Aksi remediasi

1. Pastikan record A dari langkah 6 berisi <IP_VPS> dan tidak ada record A atau AAAA lain untuk nama yang sama. Angka setelah A= di baris Menunggu adalah IP yang sekarang terdaftar; kalau berisi IP privat atau IP internet laptop, ganti dengan <IP_VPS>.
2. Matikan proxy CDN bila ada (misalnya Cloudflare).
3. Jalankan ulang langkah 5.

Skenario 3: HTTPS tidak tersedia (kode 60)

Gejala

• Tahap Memasang domain dan HTTPS berhenti setelah menunggu 10 menit dengan pesan HTTPS untuk <DOMAIN> belum tersedia; buka port 80 dan 443 di firewall penyedia….

Aksi diagnostik

docker logs alurkerja-edge --tail=50

Aksi remediasi

1. Buka port 80 dan 443 di firewall atau security group penyedia VPS.
2. Jalankan ulang langkah 5.

Skenario 4: Installer terhenti di tengah

Gejala

• Koneksi SSH terputus, instalasi dihentikan dengan Ctrl+C, atau muncul baris ERROR: di tahap Docker, CLI, build, pemasangan domain, atau validasi akhir. Contoh:

      [9/21] Start postgres (est. ~1 min)
^C    ✗ gagal
ERROR: Installer dihentikan (kode 40)

Aksi diagnostik

cat /var/lib/alurkerja-installer/status.json
cat /var/lib/alurkerja-installer/verify.log

Kolom stage di status.json menunjukkan tahap terakhir yang dijalankan. verify.log berisi checklist validasi akhir dan baru ada setelah tahap validasi berjalan.

Aksi remediasi

1. Jalankan ulang langkah 5 — installer melanjutkan tanpa menghapus data.
2. Bila gagal lagi di tahap yang sama, kirim baris ERROR: dan potongan log yang relevan ke tim AlurKerja.

G. Menghapus VPS

Bila VPS tidak dipakai lagi:

1. Hapus VPS dari console penyedia. Pilih hapus, bukan sekadar stop — VPS yang hanya dimatikan umumnya tetap ditagih.
2. Hapus record A domain di pengelola DNS.