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
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.
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 di-provision.	Provision registry dulu.
Build: repository not found / 128	Repo privat tanpa Kredensial Git, token kedaluwarsa, atau branch salah.	Tambahkan kredensial di Settings 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.

Domain & HTTPS

Gejala	Penyebab	Solusi
Tab Domain: Proxy belum berjalan	Traefik belum di-provision.	Settings → Reverse proxy → provision (owner).
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.
Sertifikat self-signed / TRAEFIK DEFAULT CERT	ACME gagal: DNS belum benar, port 80 tertutup, rate limit, atau email kosong saat provision.	`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 Disk Docker.
Tes tujuan S3: NoSuchBucket / gagal ke MinIO lokal	Bucket belum ada, region salah, atau endpoint memakai localhost dari container.	Buat bucket; pakai nama container MinIO + :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.	Jalankan perintah yang ditampilkan di host sebagai user itu.
Terminal: `TERMINAL_SSH_USER is not set`	Env kosong.	Isi di `.env.dist`, 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.

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.	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.	Settings → Disk Docker → 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	MinIO dari template (API / Console)	—

Melapor issue

Bila belum teratasi, buka issue di GitLab aoox-api ↗ dengan:

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 GitLab ↗