Mulai dengan CLI

aoox adalah CLI resmi aoox: menyimpan kredensial panel di mesinmu dan berbicara ke API yang sama dengan dashboard.

Perintah: aoox
Autentikasi: API token aoox_… dari panel
Butuh: Node.js 20+ (aoox install: VPS Linux + root)

Tahap awal

CLI sudah bisa memasang aoox (install), masuk (login/whoami), dan build + deploy repo lokal (link/deploy). Perintah untuk project, database, log tail, dan lainnya belum ada — untuk itu pakai dashboard, webhook, atau panggil API langsung dengan token yang sama.

Memasang CLI

Paket npm belum dirilis, jadi untuk sekarang pasang dari source. Butuh Node.js 20+.

Dari source

git clone https://github.com/hideandseeklab/aoox-cli.git
cd aoox-cli
npm install
npm run build
npm link          # menyediakan perintah aoox secara global

aoox --version

Perintah terpasang sebagai aoox.

Memasang aoox lewat aoox install

Perintah ini berbeda dari bagian sebelumnya: aoox install tidak menyambung ke panel yang sudah ada — ia memasang panelnya sendiri (postgres + api + web) di VPS Linux yang masih kosong, sebagai alternatif cara manual di Instalasi. Jalankan sebagai root, langsung di server tujuan.

Paling sederhana (tanpa domain, akses lewat IP)

$ sudo aoox install
==> Mendeteksi IP publik server
Pasang aoox di /opt/aoox dan jalankan docker compose up -d? (Y/n)
==> Menjalankan docker compose up -d
==> Menunggu API siap

aoox terpasang di /opt/aoox.
Buka: http://203.0.113.10:3000
Buat akun owner pertama di /setup.

Dengan domain + HTTPS otomatis dan owner langsung dibuat

sudo aoox install \
  --web-domain panel.example.com \
  --api-domain api.panel.example.com \
  --acme-email saya@example.com \
  --admin-email saya@example.com \
  --admin-name "Admin" \
  --admin-password "kata-sandi-kuat" \
  --yes

Docker dipasang otomatis lewat get.docker.com bila belum ada — minta konfirmasi kecuali --yes.
--web-domain dan --api-domain saling mensyaratkan, dan keduanya butuh --acme-email untuk sertifikat Let's Encrypt lewat proxy bawaan.
Tanpa --admin-email, buat akun owner lewat /setup di browser seperti instalasi manual.
Folder instalasi default /opt/aoox (ubah dengan --dir); instalasi yang sudah ada di folder itu ditolak kecuali diberi --force.
Secret (JWT_SECRET, ENCRYPTION_KEY, password Postgres) dibuat acak dan ditulis ke .env.dist dengan mode 0600 — tidak perluopenssl rand manual.

Perintah ini menjalankan ulang langkah-langkah di Instalasi secara otomatis: clone compose distribusi, isi env, docker compose up -d, lalu tunggu /auth/setup-status menjawab. Bukan penggantiaoox login — setelah panel terpasang, login seperti biasa untuk memakai aoox link/aoox deploy.

Buat API token di panel
Settings → API token: beri nama (mis. laptop-saya), pilih kedaluwarsa, lalu salin token aoox_… yang hanya tampil sekali. Token bertindak sebagai pemiliknya dengan peran yang sama — lihat Keamanan akun.
Jalankan aoox login
```
$ aoox login
URL panel  https://panel.example.com
API token (aoox_…) ********
Memverifikasi token... ok
Masuk sebagai kamu@example.com (owner) di https://panel.example.com
Token disimpan di /home/kamu/.config/aoox/config.json
```
Token diminta lewat prompt tersembunyi, bukan argumen, supaya tidak tertinggal di riwayat shell atau daftar proses. Sebelum disimpan, CLI memanggil GET /auth/me — kredensial yang ditolak tidak pernah ditulis ke disk.
Pastikan tersambung
```
$ aoox whoami
kamu@example.com · owner · Admin
Panel: https://panel.example.com
```
Tambahkan --json untuk keluaran yang bisa diproses skrip; baris teks di atas otomatis disembunyikan.

Build & deploy dari repo lokal

aoox link menghubungkan folder repo ke satu aplikasi di panel, lalu aoox deploy membangun image di mesinmu, mem-push-nya ke registry, dan memicu deploy — mengikuti log sampai selesai seperti tab Deploy di dashboard.

Link folder ke aplikasi

$ cd repo-aplikasiku
$ aoox link
? Pilih project › toko
? Pilih aplikasi › shop (shop)
Ter-link: toko / shop (shop)
Ditulis ke .aoox.json — aman di-commit, tidak memuat rahasia.

--project/--app melewati pemilihan interaktif — dipakai di CI. File .aoox.json yang dihasilkan tidak berisi token, aman masuk repo.

Deploy
```
$ aoox deploy
==> Build localhost:5000/toko/shop:a1b2c3d
==> docker login localhost:5000
==> Push localhost:5000/toko/shop:a1b2c3d
==> Memutakhirkan aplikasi & memicu deploy
[building] Building localhost:5000/toko/shop:a1b2c3d from https://…
...
Deployed: localhost:5000/toko/shop:a1b2c3d
```
Build berjalan di Docker lokal (docker build dengan --dockerfile/--context), lalu di-push ke registry aplikasi itu — default registry self-hosted bila ada lebih dari satu, pilih manual dengan --registry. Tag default git short SHA (+ -dirty bila ada perubahan belum di-commit); timpa dengan --tag.

Aplikasi otomatis dipindah ke sourceType: image memakai registry dan tag yang baru saja di-push — bukan mem-build ulang di server seperti build dari Git. Dua sumber aplikasi. Deploy yang masih berjalan untuk aplikasi yang sama ditolak (409) — tunggu selesai dulu.

Referensi perintah

Perintah	Fungsi	Flag
`aoox install`	Memasang aoox (postgres + api + web) di VPS baru lewat Docker Compose.	--web-domain, --api-domain, --acme-email, --admin-email/-name/-password, --dir, --force, --yes/-y
`aoox login`	Menyimpan URL panel dan API token untuk perintah lain.	--url/-u, --token/-t
`aoox whoami`	Menampilkan akun dan panel yang sedang dipakai.	--url/-u, --token/-t, --json
`aoox link`	Menghubungkan folder repo ke sebuah aplikasi di panel (dipakai aoox deploy).	--project, --app
`aoox deploy`	Build image lokal, push ke registry, lalu deploy — mengikuti log sampai selesai.	--tag, --dockerfile/-f, --context, --registry
`aoox help [PERINTAH]`	Daftar perintah, atau bantuan satu perintah.	—

Konfigurasi & variabel lingkungan

Sumber	Isi	Catatan
`config.json`	`{ "url": "…", "token": "aoox_…" }` di direktori konfigurasi oclif (`~/.config/aoox/` di Linux).	Ditulis dengan mode `0600`; jalur lengkapnya dicetak saat login.
`--url` / `--token`	Menimpa isi file untuk satu perintah.	Berguna saat berpindah antar panel (produksi vs staging).
`AOOX_URL` / `AOOX_TOKEN`	Sumber yang sama lewat environment.	Dipakai CI; muncul juga di --help.

Urutan: flag → environment → isi config.json. Bila tidak ada yang lengkap, CLI menyuruh menjalankan aoox login.
Beberapa panel? Jangan login ulang bolak-balik — simpan satu sebagai default lalu timpa dengan --url/--token seperlunya.

Di CI (tanpa terminal)

aoox login butuh terminal interaktif. Di pipeline, lewati login dan berikan kredensial lewat environment:

.gitlab-ci.yml

deploy:
  image: node:20
  variables:
    AOOX_URL: https://panel.example.com
  script:
    - npx aoox whoami            # AOOX_TOKEN dari CI variable (masked)

Simpan token sebagai variabel CI yang masked, dan buat token terpisah per pipeline agar bisa dicabut tanpa mengganggu yang lain.

Jebakan umum

Pesan	Penyebab & solusi
Token ditolak panel (401)	Token kedaluwarsa, dicabut, atau salah salin. Buat token baru di Settings → API token.
Tidak ada terminal interaktif	Berjalan di CI/skrip. Beri `--url` dan `--token`, atau set `AOOX_URL` dan `AOOX_TOKEN`.
Tidak bisa menghubungi panel	URL salah atau API tidak terjangkau dari mesin ini. Pakai `PUBLIC_API_URL` panel (bukan URL dashboard) dan uji dengan `curl <url>/auth/setup-status`.
Config rusak (bukan JSON yang sah)	File konfigurasi teredit manual. Hapus file itu lalu `aoox login` lagi.
403 pada perintah tertentu	Peran akun pemilik token tidak cukup — token tidak menambah hak apa pun di atas pemiliknya. Bila tokennya punya scope, lihat token read-only/project-limited.
Repo ini belum di-link	`aoox deploy` dijalankan sebelum `aoox link`. Jalankan `aoox link` dulu di folder repo.
Sudah ada deployment yang berjalan (409)	Aplikasi yang sama sedang di-deploy — dari dashboard, webhook, atau `aoox deploy` lain. Tunggu selesai, cek tab Deploy.
aoox install: perlu root	Jalankan dengan `sudo` — instalasi menulis ke path sistem dan mengelola Docker.
aoox install: sudah ada instalasi di …	Folder `--dir` (default `/opt/aoox`) sudah terisi. Beri `--force` untuk menimpanya, atau pakai `--dir` lain.

Belum tersedia

Perintah untuk project, log tail mandiri, dan database; paket npm resmi; autocomplete shell; keluaran --json untuk semua perintah (baru whoami).

Langkah berikutnya

Pengguna & peranMembuat API token dan scope-nya.InstalasiLangkah manual yang di-otomatisasi aoox install.RegistryTempat image dari aoox deploy disimpan.Deploy & rollbackApa yang terjadi di balik layar saat deploy.

Ada yang keliru? Edit halaman ini di GitLab ↗

Buat API token di panel

Jalankan aoox login

Pastikan tersambung

Link folder ke aplikasi

Deploy

Di CI (tanpa terminal)