DocsInfrastruktur

Troubleshooting

Masalah yang paling sering muncul, dikelompokkan per area, dengan cara diagnosis cepat.

Mulai dari: Log API + docker ps
Sumber kebenaran: Log deployment di tab Deploy
Masih buntu?: Buka issue dengan info di bawah

Diagnosis cepat

Di server, dari folder aoox-api

# status tiga container inti
docker compose -f docker-compose.dist.yml --env-file .env.dist ps

# log API (deploy, backup, notifikasi, SSH) dan web
docker compose -f docker-compose.dist.yml --env-file .env.dist logs -f --tail 200 api
docker compose -f docker-compose.dist.yml --env-file .env.dist logs -f --tail 100 web

# semua container yang dikelola aoox
docker ps -a --filter label=com.docker.compose.project=aoox

# proxy & registry
docker logs -f --tail 100 aoox-proxy
docker logs -f --tail 100 aoox-registry

# API hidup?
curl -s http://localhost:3001/auth/setup-status

Masalah deploy: log deployment di tab Deploy adalah sumber paling lengkap — token dan password sudah disensor, aman untuk dibagikan.
Masalah runtime aplikasi: log container di tab yang sama, atau docker logs aoox-app-<slug>.
Siapa mengubah apa: Audit log (owner/admin).

Instalasi & akses Build & deploy Domain & HTTPS Database & backup Terminal & server remote Notifikasi, jobs, disk

Instalasi & akses

Gejala	Penyebab	Solusi
`aoox install` berhenti dengan “Docker already has data volumes from an earlier aoox installation”	Folder instalasi kosong (atau sudah dihapus) tetapi volume `aoox_postgres_data` masih ada. Instalasi baru akan membuat `POSTGRES_PASSWORD` baru yang tidak bisa membuka database lama, jadi installer menolak sebelum mengubah apa pun.	Pertahankan data: kembalikan `.env.dist` yang lama (`/opt/aoox/backups/<timestamp>/` kalau installer pernah menyimpannya) lalu jalankan `sudo aoox reinstall`. Mulai bersih: `sudo aoox install --force --new-secrets --wipe-data` (menghapus volume itu dan container stack-nya; Anda diminta mengetik folder, atau beri `--confirm-wipe=<dir>`).
Perbaikan/fitur baru tidak muncul setelah update panel (mis. `PUBLIC_API_URL` di webhook masih `localhost`)	`aoox update panel` dan tombol “Terapkan update” hanya `pull` + `up -d`: file compose dan variabel baru di `.env.dist` tidak diperbarui.	Jalankan `sudo aoox reinstall` (`--dry-run` dulu untuk melihat perubahannya). Alternatif tanpa CLI: edit `.env.dist` / halaman Environment, atau sesuaikan compose manual sesuai catatan rilis — lihat Memperbarui versi. `aoox install --force` juga mempertahankan secret dan mencadangkan file lama lebih dulu; hanya `--force --new-secrets --wipe-data` yang menghapus data.
Web terbuka, tapi sign-in / API gagal (network error)	`PUBLIC_API_URL` tidak bisa dijangkau browser (IP/port salah, firewall 3001).	Samakan dengan alamat yang bisa dibuka dari browser; `curl <PUBLIC_API_URL>/auth/setup-status` dari laptop harus menjawab.
Terminal: `origin not allowed`	`WEB_ORIGIN` ≠ URL di browser (skema/host/port).	Samakan persis, lalu `up -d` ulang. Lihat Domain untuk panel.
Rate limit (sign-in) atau audit log menganggap semua pengguna satu alamat, atau mencatat IP proxy, bukan IP klien	API hanya memercayai `X-Forwarded-For` dari hop di jaringan privat (Traefik, container web). Proxy dengan alamat publik, atau rantai beberapa proxy, tidak dipercaya secara default.	Isi `TRUST_PROXY` di `.env.dist`: jumlah hop (`2`), atau daftar IP/CIDR proxy dipisah koma. `true` memercayai semua hop, sehingga klien bisa memalsukan IP-nya bila port API terjangkau langsung; `false` mengabaikan header. Lalu `up -d` ulang.
Kartu Registry/Proxy: Docker tidak terjangkau / permission denied di socket	`DOCKER_GID` salah atau socket tidak di-mount.	`stat -c %g /var/run/docker.sock` → set `DOCKER_GID` → recreate API.
Semua pengguna logout mendadak	`JWT_SECRET` berubah.	Normal setelah rotasi; kembalikan nilai lama bila tidak disengaja.
Kredensial registry/Git/notifikasi/S3 tidak bisa dibaca	`ENCRYPTION_KEY` berubah.	Kembalikan nilai lama; kalau hilang, masukkan ulang semua kredensial.
`/setup` tidak muncul / 404	Sudah ada pengguna.	Sign in biasa; owner bisa reset password anggota. Untuk mulai dari nol: `down -v`.

Build & deploy

Gejala	Penyebab	Solusi
Deploy gagal: No self-hosted registry	Registry lokal belum diaktifkan.	Aktifkan registry dulu.
Build: repository not found / 128	Repo privat tanpa Kredensial Git, token kedaluwarsa, atau branch salah.	Tambahkan kredensial di Integrasi → Kredensial Git dan pilih di aplikasi; cek nama branch.
Build: unknown flag --mount / heredoc error	Sintaks BuildKit di Dockerfile; builder klasik.	Ganti dengan langkah biasa — lihat Cara build.
Health check tidak pernah healthy	Port container ≠ port yang di-listen, listen hanya di `127.0.0.1`, path tidak 2xx, atau image tanpa wget/curl/node/python3.	Listen di `0.0.0.0`, samakan port, sediakan endpoint 200 cepat.
Env baru tidak terbaca aplikasi	Env diterapkan saat container dibuat.	Deploy atau Rollback sekali lagi.
400: referensi `${{database.x.url}}` tidak dikenal	Slug salah atau database di project lain.	Referensi hanya dalam project yang sama.
Webhook push tidak memicu deploy	Branch beda, event bukan push, deployment masih jalan (`busy`), atau 401 secret.	Cek Recent Deliveries di provider — tabel respons.
Rollback gagal: image not found	Tag dipangkas retensi atau dihapus manual.	Deploy ulang commit itu; naikkan Riwayat deployment.
Nixpacks/statis: build pertama sangat lama	Base image ± 350 MB + helper dibangun sekali.	Tunggu; untuk build cepat pakai Dockerfile.
Deploy berhasil (Running) tapi aplikasi tidak bisa diakses	Belum ada port host maupun domain — dulu keduanya kosong secara default dan tersembunyi di tab edit, jadi aplikasi baru bisa diam-diam tidak bisa diakses.	Tambahkan salah satunya dari tab Pengaturan atau Domain. Untuk aplikasi baru, pilih IP+port atau Domain di langkah Akses saat membuat, supaya tidak perlu diperbaiki belakangan.

Domain & HTTPS

Gejala	Penyebab	Solusi
Tab Domain: Proxy belum berjalan	Traefik belum diaktifkan.	Settings → Reverse proxy → aktifkan (owner).
Domain panel disimpan, DNS & `ufw` sudah OK, browser tetap unable to connect	Proxy belum jalan saat itu (kini otomatis dinyalakan saat simpan domain), atau port 80/443 diblokir firewall/security group provider VPS — `ufw inactive` ≠ port terbuka ke publik.	`docker ps --filter name=aoox-proxy` harus `Up`; buka 80/443 di panel provider VPS. Lihat Domain untuk panel → Jebakan umum.
Panel tidak bisa dibuka setelah mengaktifkan Hanya izinkan akses lewat domain; `IP:3000` tidak lagi menjawab	Opsi itu hanya membuka port 3000/3001 di `127.0.0.1`, jadi domain kini satu-satunya jalan masuk, dan domainnya bermasalah (DNS, firewall/security group, sertifikat).	Lewat SSH, di folder instalasi: hapus dua baris `ports:` di `docker-compose.override.yml`, lalu `docker compose -f docker-compose.dist.yml -f docker-compose.override.yml --env-file .env.dist up -d`. Lihat Domain panel → Hanya izinkan akses lewat domain.
404 page not found dari Traefik	Container belum healthy, atau domain ditambah sebelum container dibuat ulang.	Tunggu healthy; cek log deploy; pastikan health check lolos.
Bad Gateway (502) dari domain, padahal container berjalan	Traefik tidak bisa menjangkau aplikasi: `Container port` bukan port yang didengarkan aplikasi (mis. image nginx mendengarkan 80, port diatur 3000).	Bila image mendeklarasikan port `EXPOSE` yang tidak mencakup Container port, tab Settings dan Domain menampilkan peringatan (dan log deploy mencatatnya) dengan tombol `Pakai port 80`. Jika tidak, atur Container port di Settings ke port yang benar-benar didengarkan aplikasi.
Sertifikat self-signed / TRAEFIK DEFAULT CERT	ACME gagal: DNS belum benar, port 80 tertutup, rate limit, atau email kosong saat diaktifkan.	`docker logs -f aoox-proxy`; uji dengan `PROXY_ACME_STAGING=true`.
Redirect loop	Cloudflare mode Flexible atau proxy lain men-terminate TLS di depan.	Full (strict), atau matikan HTTPS di aoox.
Cek DNS: `?`	IP publik server tidak terdeteksi (NAT/tanpa internet keluar).	Set `PUBLIC_IP` di `.env.dist`.
Preview PR tidak resolve	Tanpa DNS wildcard, atau preview domain salah.	`*.preview.example.com A <ip>`.

Database & backup

Gejala	Penyebab	Solusi
Aplikasi: `ECONNREFUSED` / `ENOTFOUND` ke database	Memakai URL eksternal/localhost dari dalam container, atau app di server remote memakai host internal.	Pakai referensi (host internal) untuk app lokal; koneksi eksternal + port host untuk server remote.
Database status error saat dibuat	Tag image tidak ada, atau port host sudah dipakai.	Hapus, buat ulang dengan tag/port lain.
Backup 20 byte / gagal	Kredensial/DB belum siap, atau disk penuh.	Baca pesan error di baris backup; cek strip disk di atas halaman Docker.
Tes tujuan S3: NoSuchBucket / gagal ke server S3 lokal	Bucket belum ada, region salah, atau endpoint memakai localhost dari container.	Buat bucket; pakai nama container S3 (mis. RustFS) + :9000 sebagai endpoint.
Data browser: 400 hanya satu statement	`;` di akhir atau beberapa statement.	Jalankan satu per satu, atau pakai Impor SQL.
Member: 403 saat menjalankan query	Statement tulis.	Hanya owner/admin; sesi member read-only di engine.

Terminal & server remote

Gejala	Penyebab	Solusi
Terminal: auth failed + perintah otorisasi	Key platform belum di `authorized_keys` user itu (otorisasi otomatis menolak `~/.ssh` atau `authorized_keys` yang berupa symlink).	Jalankan perintah yang ditampilkan di host sebagai user itu.
Terminal: `SSH authentication failed for root@host.docker.internal`	Terminal masuk sebagai `root` (default), sedangkan di VPS cloud (Ubuntu, dll.) login root biasanya ditolak sshd dan login-mu user lain.	Isi User di Infrastruktur → Environment dengan user login VPS (mis. `ubuntu`), jalankan perintah otorisasi di VPS sebagai user itu, periksa `~/.ssh/authorized_keys` user itu dan `PermitRootLogin` di `/etc/ssh/sshd_config`. Rinciannya di Web terminal.
Terminal: `TERMINAL_SSH_USER is not set` (versi lama)	Instalasi lama tidak punya baris ini di `.env.dist`, dan update tidak menyentuh file itu. Versi terbaru otomatis memakai `root` bila kosong.	Jalankan `sudo aoox reinstall` (menambah baris yang hilang tanpa menyentuh data). Tanpa CLI: tambah `TERMINAL_SSH_USER=root` di `.env.dist` atau pakai halaman Environment. Kalau login harus user lain, isi lewat Settings → Infrastruktur → Environment (owner, tanpa SSH), atau manual di `.env.dist` lalu restart stack.
Terminal: `ECONNREFUSED` ke host.docker.internal	sshd mati/port salah, atau Linux tanpa extra_hosts.	Pakai IP gateway docker0 (mis. `172.17.0.1`) sebagai `TERMINAL_SSH_HOST`.
Direktori key tidak writable (uid 1000)	`./secrets` milik root.	`sudo chown -R 1000:1000 ./secrets`.
Server remote: docker: command not found / permission denied	Docker belum ada di PATH user, atau user tidak di grup docker.	`curl -fsSL https://get.docker.com \| sh`, `usermod -aG docker <user>`.
Deploy remote sukses tapi tidak bisa diakses	Port host kosong atau firewall server menutup port.	Isi Port host; buka port di ufw/security group. Domain tidak berlaku di server remote.
Port bisa dijangkau dari internet padahal ufw menolaknya	Docker mempublikasikan port lewat aturan firewall sendiri yang tidak disaring ufw.	Tutup di firewall provider, atau ubah Mendengarkan di port itu menjadi Hanya server ini. Tab Port terbuka di halaman Docker menampilkan semua port yang dipublikasikan dan apakah terbuka.

Notifikasi, jobs, disk

Gejala	Penyebab	Solusi
Tes notifikasi sukses, event tidak pernah masuk	Toggle event belum aktif, atau event tidak terjadi (mis. container mati di server remote tidak terdeteksi).	Nyalakan toggle; picu event sungguhan.
Project tidak terlihat oleh rekan	Ia belum ditambahkan sebagai anggota project; member instance hanya melihat project yang ditugaskan.	Tambahkan di tab Anggota project — lihat Project.
Viewer: tombol ada tapi aksi gagal 403	Peran project viewer bersifat baca-saja dan ditegakkan di API.	Naikkan ke developer bila memang perlu mengubah.
Swarm: task pending / image pull failed di node lain	Constraint tidak cocok, atau `REGISTRY_PUBLIC_HOST` masih localhost sehingga node lain tak bisa menarik image.	Lihat Docker Swarm.
Job jalan pada jam yang salah	Zona waktu API = UTC kecuali TZ diisi.	Isi `TZ=Asia/Jakarta` (zonamu) di `.env.dist` lalu buat ulang container api, atau geser jam di cron (WIB = UTC+7).
Job: container not running	Target Di container tapi aplikasi stopped.	Pakai Container terpisah atau start aplikasi.
Disk penuh (atau notifikasi disk hampir penuh)	Image deployment lama, dangling image, build cache, backup lokal.	Docker (strip disk di atas) → Bersihkan sekarang; turunkan Riwayat deployment & jumlah simpan backup; GC registry.
Stack compose: service tidak melihat env	Env stack hanya untuk interpolasi.	Tambahkan `environment:` di service.

Mulai dari nol (uji coba)

Menghapus semua data aoox — bukan container aplikasi/database yang sudah dibuat dari dashboard:

docker compose -f docker-compose.dist.yml --env-file .env.dist down -v
docker compose -f docker-compose.dist.yml --env-file .env.dist up -d

Container app/db/registry/proxy tetap ada dan akan yatim setelah reset. Hapus dulu dari dashboard, atau: docker ps -aq --filter label=com.docker.compose.project=aoox | xargs docker rm -f (dan volume-nya bila memang ingin bersih total).

Referensi port & env

Port	Untuk	Env
3000	Web (dashboard)	`WEB_PORT`
3001	API	`API_PORT`
5000	Registry lokal	`REGISTRY_PORT`
80 / 443	Reverse proxy (ACME butuh 80)	`PROXY_HTTP_PORT` / `PROXY_HTTPS_PORT`
22	SSH ke host (terminal)	`TERMINAL_SSH_PORT`
9000 / 9001	RustFS dari template (API S3 / Console)	—

Melapor issue

Bila belum teratasi, buka issue di GitHub aoox-api ↗. Semua bug masuk ke repositori ini, baik soal dashboard, API, CLI, maupun dokumentasi (issue yang ada). Sertakan:

Versi image API/web (kartu Host di Dashboard, atau tag di .env.dist) dan versi Docker.
Langkah yang dilakukan dan yang diharapkan.
Potongan log API di sekitar waktu kejadian (rahasia sudah disensor; tetap periksa).
Untuk deploy: log deployment dari tab Deploy dan cara build yang dipakai.

Langkah berikutnya

InstalasiEnv wajib dan verifikasi awal.Deploy & rollbackMembaca log deployment.Proxy & domainRouter Traefik dan ACME.Pengguna & peranAudit log untuk melacak siapa mengubah apa.

Ada yang keliru? Edit halaman ini di GitHub ↗