Mulai dengan CLI

Perintah

aoox

Autentikasi

API token aoox_… dari panel

Butuh

Script installer (tanpa Node.js), atau Node.js 22+ (npm)

Memasang CLI

Di Linux atau macOS, script installer memasang aoox tanpa perlu Node.js sama sekali — tarball-nya membawa runtime Node sendiri:

curl -fsSL https://aoox.dev/install-cli.sh | sh

aoox --version

Terpasang ke /usr/local/lib/aoox + /usr/local/bin/aoox (root/sudo), atau ~/.local/lib/aoox kalau tidak ada akses itu. Menjalankan ulang perintah yang sama berarti upgrade. Mendukung Linux (glibc — bukan Alpine/musl) dan macOS, x64 maupun arm64.

npm install -g @hideandseeklab/aoox

aoox --version

Perintah terpasang sebagai aoox meski nama paketnya @hideandseeklab/aoox. Untuk ikut main sebelum dirilis, pasang 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

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 dari cara manual di Instalasi. Jalankan sebagai root, langsung di server tujuan.

$ sudo aoox install
==> Detecting the server public IP
Install aoox in /opt/aoox and run docker compose up -d? (Y/n)
==> Running docker compose up -d
==> Waiting for the API to be ready

aoox is installed in /opt/aoox.
Open: http://203.0.113.10:3000
Create the first owner account at /setup.

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 harus dipakai bersamaan, 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.
• --force pada instalasi yang sudah ada mencadangkan .env.dist dan file compose ke <dir>/backups/<timestamp>/ lalu memakai ulang secret yang ada beserta semua nilai yang sudah ada (hanya flag yang Anda berikan yang mengganti nilai), sehingga data tetap aman.
• Memulai benar-benar dari nol butuh ketiganya: --force --new-secrets --wipe-data. Perintah ini menjalankan docker compose down -v untuk stack yang ada (volume database dihapus), membuat secret baru, dan meminta Anda mengetik folder instalasi sebagai konfirmasi — --yes saja tidak cukup; untuk mode non-interaktif pakai --confirm-wipe=/opt/aoox. --new-secrets atau --wipe-data sendirian ditolak: secret baru tidak bisa membuka volume database lama, dan itulah yang dulu merusak instalasi.
• Secret (JWT_SECRET, ENCRYPTION_KEY, password Postgres) dibuat acak dan ditulis ke .env.dist dengan mode 0600 — tidak perluopenssl rand manual.

Masuk ke panel

1. 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. Dialog yang menampilkan token juga berisi baris aoox login --url … --token … yang siap disalin.

2. Jalankan aoox login

   $ aoox login
   Use the address you open the dashboard with: your panel domain (e.g. https://dashboard.example.com),
   or http://<server-IP>:3000 if no panel domain is set yet.
   ? Dashboard URL https://panel.example.com
   Looking for the panel... ok
   API token (aoox_…) ********
   Verifying token... ok
   Logged in as kamu@example.com (owner) at https://panel.example.com
   Token saved to /home/kamu/.config/aoox/config.json

   Yang kamu isi hanya alamat dashboard — alamat yang kamu buka di browser, bukan alamat API. CLI membaca alamat API dari dashboard (/.well-known/aoox.json). Skema boleh dihilangkan: host tanpa skema dicoba lewat https lalu http, dan IP polos juga di port 3000, jadi 203.0.113.10 berfungsi pada instalasi baru tanpa domain panel. Bila dashboard tidak mengumumkan alamat API publik, CLI mengasumsikan <host yang sama>:3001 dan mengatakannya. Alamat API dari skrip lama tetap berfungsi (dengan satu baris catatan).

   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.

3. 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.

Terhubung ke panel yang mana?

Menjalankan aoox tanpa argumen menampilkan daftar perintah dan, di bawahnya, ke mana CLI terhubung. Alamat dashboard dan API diambil dari login tersimpan (tanpa jaringan); baris registry meminta registry default ke panel dengan timeout singkat dan tidak pernah menggagalkan perintah. aoox --help dan aoox <perintah> --help tidak berubah.

$ aoox
...
Connected to
  Dashboard  https://dashboard.example.com
  API        https://api.example.com
  Registry   registry.example.com (self-hosted)

$ aoox            # belum login
Not connected — run: aoox login

Kalau registry tidak bisa dicek muncul Registry (could not check: panel unreachable); alamat registry localhost:… mendapat peringatan singkat untuk mengatur domain dengan aoox registry domain --set <host>.

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.

1. Link folder ke aplikasi

   $ cd repo-aplikasiku
   $ aoox link
   ? Select a project › toko
   ? Select an application › shop (shop)
   Linked: toko / shop (shop)
   Written to .aoox.json — safe to commit, contains no secrets.

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

2. Deploy

   $ aoox deploy
   ==> Build localhost:5000/toko/shop:a1b2c3d
   ==> docker login localhost:5000
   ==> Push localhost:5000/toko/shop:a1b2c3d
   ==> Updating the application & triggering a 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.

Variabel (aoox env, aoox run)

aoox env membaca dan mengubah environment dari set variabel (yang sama dengan menu Variabel di dashboard) dan mengatur environment mana yang dipakai aplikasi tertaut. aoox run menjalankan perintah dengan variabel yang didapat aplikasi saat deploy, tanpa menulis file.

• Environment set dipilih dengan --set <slug> (singkat -s) dan --env <nama> (-e).
• Bawaan: --set adalah satu-satunya set yang dipakai aplikasi yang ditautkan dengan aoox link (atau satu-satunya set yang bisa kamu lihat); --env adalah satu-satunya environment set itu yang ditautkan. Bila ada beberapa kandidat, perintah berhenti dan menampilkan daftarnya — tidak pernah menebak. Tidak ada nama environment bawaan.
• --app <id> memakai aplikasi lain, dan --stack <id> sebuah stack compose, sebagai ganti aplikasi tertaut.

$ aoox env list
backend  (Backend) · shared with shop, blog · your role: developer
  development             3 variables
  staging                 0 variables
  production (protected)  7 variables  used by 2

$ aoox env set API_URL=https://api.example.com GREETING="hello world" -s backend -e development
backend/development: added API_URL, GREETING (5 variables now)

$ aoox env list --set backend --env development            # hanya nama, nilai disamarkan
API_URL=••••••••
$ aoox env list --set backend --env development --reveal   # nilai (diaudit)
$ aoox env pull --set backend --env development            # menulis ./.env (mode 0600)
$ aoox env unset OLD_KEY --set backend --env development
$ aoox run -- npm run dev                                  # variabel aplikasi yang di-deploy (kemungkinan production)

Apa yang diteruskan aoox run ke perintah

• Secara bawaan ia meniru yang dilakukan panel saat membuat container, sejauh yang bisa dilakukan dari terminal: membaca setiap environment set yang ditautkan aplikasi, berurutan (yang belakangan menang pada key yang sama), lalu menaruh env milik aplikasi di atasnya. Setiap pembacaan diaudit. Bila salah satunya tidak bisa dibaca (environment terlindungi, viewer, scope token), tidak ada yang dijalankan.
• ${{vars.KEY}} diganti dengan nilai gabungan KEY dari set, satu tingkat seperti di panel.
• Referensi ${{database.…}} dan ${{secret.…}}, serta ${{vars.KEY}} yang tidak didefinisikan set tertaut mana pun, dibiarkan apa adanya, dengan satu peringatan yang menyebut variabelnya: hanya panel yang meresolusinya saat deploy. Secret yang disinkronkan dari Infisical tidak ikut (ada peringatannya).
• --set/--env memakai tepat satu environment set saja: tanpa tautan dan tanpa env sendiri.
• --file .env.local berada di atas semua itu: urutannya, dari terendah ke tertinggi, environment-mu saat ini, lalu aoox, lalu file. File hanya dibaca, dan referensi di dalamnya tidak diresolusi.

$ aoox run -- node server.js
aoox  Injecting 9 variables into your process · Application "shop-web": shared/production < backend/production < own env

Jumlahnya adalah yang ditambah atau ditimpa aoox, termasuk --file; variabel bawaan shell-mu tidak dihitung. Baris ini berwarna hanya di terminal: NO_COLOR mematikan warna, FORCE_COLOR memaksanya, dan pipe serta log CI tetap polos. --quiet (-q) menyembunyikan baris itu, tetapi peringatan tentang referensi yang tidak bisa diresolusi aoox selalu dicetak.

Format pull dan push

$ aoox env pull --env staging                        # ./.env, teks tersimpan beserta komentarnya
$ aoox env pull --format json                        # ./.env.json  {"KEY":"value"}
$ aoox env pull --format shell                       # ./.env.sh    export KEY='value'
$ aoox env pull --format json --file - | jq .PORT    # hanya ke standard output
$ eval "$(aoox env pull --format shell --file -)"    # muat ke shell saat ini

• --file - menulis data ke standard output dan tidak ada yang lain di sana, jadi bisa di-pipe atau diberikan ke eval. Catatan (mis. soal referensi ${{…}}) dikirim ke standard error. Pada mode ini tidak ada pemeriksaan "file sudah ada" dan tidak ada peringatan .gitignore, karena tidak ada file yang ditulis.
• Format shell membungkus tiap nilai dengan kutip tunggal dan menulis kutip tunggal di dalam nilai sebagai '\'', sehingga spasi, $ dan kutip selamat saat eval. Tanpa --file, filenya .env, .env.json atau .env.sh menurut format, selalu dengan mode 0600 bila OS mendukung.

$ aoox env push --file .env.staging --set backend --env staging
Environment: backend/staging
  + added (1): NEW_FLAG
  ~ changed (1): API_URL
  - removed (1): OLD_KEY
  = unchanged: 6
Variables that are not in the file are removed: this replaces the whole environment.
? Replace "backend/staging" with the contents of .env.staging? (y/N)

• File diperiksa sebelum apa pun dikirim. Ditolak: nama tidak valid, awalan export , spasi di ujung baris, nama ganda, dan ${{project.…}}. Nilai ber-kutip (KEY="value") diterima dengan peringatan, karena panel menyimpan kutipnya sebagai bagian dari nilai. Akhir baris Windows dan BOM di awal dinormalkan.
• push, promote dan diff tidak pernah mencetak nilai. push dan promote meminta konfirmasi; tanpa terminal (CI) keduanya menolak kecuali kamu memberi --yes. Bila orang lain mengubah environment di sela itu, tidak ada yang ditulis (409), sama seperti set.
• Setiap perubahan tercatat sebagai versi (lihat riwayat dan restore); memulihkan versi lama dilakukan di dashboard.

Cara nilai disimpan (tanda kutip)

Panel menyimpan satu environment sebagai teks KEY=VALUE biasa, satu variabel per baris. Key adalah semua sebelum = pertama; nilainya adalah semua setelahnya, persis seperti yang diberikan. Tidak ada pemrosesan kutip atau escape — tidak di CLI, tidak di panel, tidak saat nilai dimasukkan ke container — jadi tanda kutip yang kamu ketik dihapus oleh shell-mu, dan kutip yang menjadi bagian nilai tetap menjadi bagiannya.

• Ditolak sebelum apa pun dikirim: nama tidak valid (huruf, angka dan _, tidak diawali angka), nilai dengan baris baru (satu variabel per baris), dan nilai yang berakhir dengan spasi (panel memangkas ujung tiap baris).
• Referensi ${{vars.KEY}} dan ${{database.<slug>.url}} disimpan dan di-pull apa adanya; panel meresolusinya saat container dibuat.
• Stack compose membaca teks hasil resolusi lewat parser --env-file Docker Compose sendiri, yang menghapus kutip yang membungkus seluruh nilai. Hindari kutip pembungkus pada nilai yang dipakai stack.

Mengedit bersamaan

set, unset dan push membaca environment, mengubah teksnya, lalu menyimpannya kembali bersama versi yang dibaca. Bila orang lain menyimpan di sela itu (dashboard, terminal lain), panel menjawab 409 dan CLI mengatakan tidak ada yang ditulis — jalankan perintahnya lagi agar perubahanmu diterapkan di atas versi terbaru. Editor di dashboard bekerja dengan cara yang sama.

Siapa boleh apa

• Tautan: env link/unlink butuh peran developer di project aplikasi itu; menambah atau melepas tautan ke environment terlindungi butuh peran admin project. Set harus dibagikan ke project itu.
• Di CI buat API token lalu ekspor AOOX_TOKEN/AOOX_URL. Token bisa dibatasi ke sebagian environment set (Pengaturan → API token → batas variabel), mis. backend/staging, backend/* atau */development: environment lain ditolak dengan 403. Lihat Scope API token.
• Token baca saja tetap bisa menjalankan aoox env pull, aoox env list --reveal dan aoox run (membaca tidak mengubah apa pun dan diaudit), tetapi set, unset, push, promote, link dan unlink ditolak. Viewer tidak pernah bisa membaca nilai, dengan atau tanpa token.
• Setiap pembacaan nilai tercatat di audit log tanpa nilainya. CLI tidak pernah menyimpan environment di disk.
• Membuat, membagikan, dan menghapus set serta environment dilakukan di dashboard oleh owner atau admin instance.

Pengembangan lokal

Jalankan aplikasi di laptop dengan variabel satu environment set, tanpa file .env dan tanpa menautkan folder. Cukup sudah masuk (login).

1. Pasang CLI, buat token sempit, lalu masuk

   $ npm i -g @hideandseeklab/aoox
   $ aoox login

   Di panel, Pengaturan → API token → Buat token: aktifkan Read-only dan isi Batasi ke variabel dengan environment yang Anda pakai, mis. backend/development. Dengan begitu token di laptop tidak bisa menyentuh production. Lihat cakupan API token.

2. Taruh perintahnya di package.json

   package.json

   "scripts": {
     "start:dev": "aoox run --set backend --env development -- nest start --watch"
   }

   Pindahan dari Infisical? infisical run --env=dev -- … menjadi aoox run --set <slug> --env development -- ….

3. Selalu sertakan --set dan --env di lokal

   Tanpa keduanya, Anda mendapat variabel aplikasi yang sudah di-deploy

   aoox run -- … tanpa --set/--env butuh aplikasi tertaut dan menyuntikkan apa yang didapat kontainernya saat deploy: environment set yang tertaut ke aplikasi plus env miliknya sendiri. Itu biasanya production, dan mengubah tautan aplikasi di panel akan diam-diam mengubah apa yang didapat laptop Anda. Dengan --set/--env hanya satu environment yang disuntikkan: tanpa tautan, tanpa env aplikasi.

4. Yang Anda lihat

   $ aoox run --set backend --env development -- nest start --watch
   aoox  Injecting 5 variables from backend/development (no links, no own env)

   • Baris itu keluar di standard error dan berwarna hanya di terminal (polos saat di-pipe atau dengan NO_COLOR). --quiet (-q) menyembunyikannya, tetapi tidak pernah peringatan.
   • Gagal dengan aman: kalau pembacaan ditolak (token salah, tidak punya akses, environment terproteksi, cakupan token), perintah tidak dijalankan sama sekali.
   • Variabel hanya ada di proses anak; tidak ada yang ditulis ke disk.

5. Alat yang hanya membaca file

   $ aoox env pull --set backend --env development --file .env

   File ditulis dengan mode 0600 dan tidak ditimpa tanpa --force. Pastikan .env ada di .gitignore; aoox memperingatkan bila belum.

6. Perlukah aoox link?

   Tidak untuk variabel lokal: --set/--env hanya butuh Anda sudah login. Anda memerlukannya untuk aoox deploy, untuk aoox run tanpa flag, dan untuk mengatur tautan lewat aoox env links/link/unlink. Perintah itu menulis .aoox.json (alamat panel, id dan nama project serta aplikasi, tanpa rahasia), aman untuk di-commit.

7. CI

   Lewati aoox login dan isi AOOX_URL serta AOOX_TOKEN (variabel CI yang di-mask) dari token read-only yang dibatasi ke environment yang dibutuhkan job.

   $ AOOX_URL=https://panel.example.com aoox run --set backend --env development -- npm test

Batasan

• Referensi ${{database.…}} dan ${{secret.…}} tetap apa adanya, dengan peringatan: hanya panel yang menyelesaikannya saat deploy. Arahkan variabel itu ke database lokal lewat variabel khusus lokal atau --file.
• Secret yang disinkronkan dari Infisical tidak ikut.
• Bila --set/--env dihilangkan dan kandidatnya banyak, perintah berhenti dan mendaftarkannya; tidak pernah menebak.

Build & push image (aoox registry)

Dua perintah untuk memasukkan image ke registry tanpa men-deploy-nya — berguna kalau image dipilih nanti di dashboard (Aplikasi baru → Image siap pakai). Keduanya tidak butuh aoox link; memakai login biasa (atau --url/--token). Registry default adalah yang self-hosted; pakai --registry <id> untuk yang lain.

$ aoox registry build myapp:1.0.0
==> Build registry.example.com/myapp:1.0.0
...
Built registry.example.com/myapp:1.0.0
Next: aoox registry push myapp:1.0.0 (or build with --push next time)

$ aoox registry push myapp:1.0.0
==> docker login registry.example.com
==> Push registry.example.com/myapp:1.0.0
Pushed registry.example.com/myapp:1.0.0
Use it in the dashboard: New application → Ready-made image

build membaca ./Dockerfile (-f/--dockerfile, --context) dan menamai image <host registry>/<nama>:<versi>. push hanya mendorong image yang sudah ada secara lokal dan menerima nama pendek maupun lengkap. Untuk build dan push sekaligus, pakai aoox registry build myapp:1.0.0 --push. Nama harus huruf kecil.

Tidak perlu mengetik semuanya. Kalau versinya dihilangkan (aoox registry build myapp) atau seluruh argumennya (aoox registry build), CLI membacanya dari proyek: konteks build untuk build, folder saat ini untuk push. nama:versi yang diketik selalu menang. File pertama yang ditemukan, dengan urutan ini, memberi tiap nilai:

Nilai dari file yang tidak bisa dipakai (variabel $(…) atau ${…}, versi dynamic) dilewati dan sumber berikutnya dicoba. Nama diubah ke huruf kecil; tanda + pada versi (metadata build, tidak boleh ada di tag) menjadi _. Kalau HEAD sudah melewati tag git terakhir, tidak ada yang ditebak: beri tag rilisnya, ketik nama:versi, atau tambahkan --force untuk memakai bentuk git describe seperti 1.4.2-3-gabc1234.

$ aoox registry build
==> Image web:1.4.2 (name and version from package.json)
? Build web:1.4.2? (Y/n/e)

Karena nama atau versi turunan bisa saja keliru, CLI bertanya dulu sebelum melakukan apa pun: Y lanjut, n berhenti, e untuk mengetik nama:versi lain. --yes (-y) melewati pertanyaan. Tanpa terminal, atau saat CI terisi, CLI menolak dan meminta nama:versi atau --yes. nama:versi yang diketik lengkap tidak pernah ditanyakan. Kalau lupa menaikkan versi, pengecekan "already exists" di bawah tetap melindungi registry dan menunjukkan di mana mengubahnya.

Ganti domain panel

Alternatif dari Settings → Domain panel di dashboard — cocok untuk skrip provisioning. Lihat Domain untuk panel untuk detail apa yang terjadi di baliknya.

$ aoox domain set --web panel.example.com --api api.panel.example.com \
  --acme-email kamu@example.com
Domain saved: panel.example.com (dashboard), api.panel.example.com (API).
The panel will restart for a few seconds to apply it — the connection to this API will drop briefly.

Untuk membatalkannya, aoox domain clear menghapus domain dan kembali ke http://<IP server>:3000 (bertanya dulu; --yes melewati pertanyaan). Proxy dan domain aplikasi tidak disentuh. Lihat Menghapus domain.

Update aoox

Ada dua hal berbeda yang diperbarui, dengan dua perintah. aoox update memperbarui CLI itu sendiri di komputermu; aoox update panel memperbarui panel (image aoox-api/aoox-web di server).

CLI: aoox update

Mencari versi terbaru di npm (tanpa login, tanpa panel). Semua dist-tag npm menjadi kandidat: instalasi pre-release ditawari versi terbaru apa pun labelnya (alpha, lalu beta, lalu rc), sedangkan instalasi stabil hanya melihat versi stabil dan tidak pernah pindah ke pre-release. Selama belum ada versi stabil, pre-release terbit di tag latest, sehingga npm i -g @hideandseeklab/aoox memasang yang terbaru. Kalau CLI dipasang lewat npm, ia menjalankan npm i -g @hideandseeklab/aoox@<versi> untukmu; untuk tarball standalone atau source checkout ia mencetak perintah persisnya alih-alih menebak.

$ aoox update --check
Update available: aoox CLI 0.1.0-rc.1 → 0.1.0-rc.2
Run: aoox update

$ aoox update
==> npm i -g @hideandseeklab/aoox@0.1.0-rc.2
Updated aoox CLI 0.1.0-rc.1 → 0.1.0-rc.2

$ aoox update
aoox CLI 0.1.0-rc.2 is up to date

Kalau registry npm tidak terjangkau, perintah gagal dengan pesan jelas (exit status bukan nol).

Panel: aoox update panel

Cek dan terapkan update untuk panel itu sendiri (bukan aplikasi yang di-deploy) — bandingkan digest image aoox-api/aoox-web di registry, bukan sekadar nomor versi.

$ aoox update panel
Running version: 0.1.0-rc.1
  api: hideandseeklab/aoox-api:latest (update available)
  web: hideandseeklab/aoox-web:latest (up to date)
Update available. Run with --apply to apply it.

$ aoox update panel --apply
Update applied — the panel will restart for a few seconds to apply it.

Bila instalasi di-pin ke tag versi (API_IMAGE / WEB_IMAGE di .env.dist), versi baru yang terbit tetap ditampilkan tetapi tidak pernah diterapkan oleh perintah ini: ia mencetak versi terbaru dan cara memindahkan pin (isi kedua variabel dengan tag baru, atau hapus agar mengikuti latest, lalu jalankan sudo aoox reinstall), dan --apply menolak alih-alih melaporkan berhasil.

Sama seperti aoox domain set, butuh INSTALL_DIR terisi. Lihat Memperbarui versi untuk cara manual lewat SSH sebagai alternatif.

Memperbaiki instalasi (aoox reinstall)

aoox update panel hanya pull + up -d: ia tidak menulis ulang docker-compose.dist.yml dan tidak menambah variabel baru ke .env.dist. Instalasi lama karena itu tidak menerima perbaikan yang butuh perubahan compose atau env (contoh nyata: Terminal error TERMINAL_SSH_USER is not set setelah update, karena instalasi lama tidak pernah menulis variabel itu). aoox reinstall memperbaikinya tanpa menyentuh data. Jalankan di server panel, sebagai root:

$ sudo aoox reinstall --dry-run
$ sudo aoox reinstall

Aman dijalankan berulang: bila tidak ada yang perlu diubah, tidak ada file yang ditulis ulang (folder backup tetap dibuat) dan container disegarkan. Bila docker-compose.override.yml memakai tag !override (opsi Hanya izinkan akses lewat domain) dan Docker Compose di host lebih lama dari 2.24.4, perintah berhenti sebelum mengubah apa pun: upgrade plugin Compose atau matikan opsi itu di dashboard dulu. Opsi: --dir (default /opt/aoox), --yes (tanpa konfirmasi), --no-pull, --terminal-ssh-user <user> (mengisi atau menimpa nilai itu), dan --dry-run (hanya cetak rencana).

Tanpa CLI: edit .env.dist langsung (mis. tambah TERMINAL_SSH_USER=root) atau pakai halaman Environment di Settings, lalu docker compose … up -d.

Referensi perintah

Konfigurasi & variabel lingkungan

• 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:

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

Di balik antivirus atau proxy perusahaan

Pemindaian HTTPS oleh antivirus (AVG, Avast, Kaspersky, ESET, Bitdefender) dan proxy perusahaan (Zscaler, Netskope, Fortinet, Palo Alto) menandatangani ulang lalu lintas HTTPS dengan sertifikat root mereka sendiri. Sertifikat itu terpasang di penyimpanan sertifikat sistem operasi Anda, tetapi Node hanya mengenal daftar bawaannya, jadi CLI dulu gagal dengan galat sertifikat padahal sertifikat panel sebenarnya baik-baik saja.

Pada Node 22.19+ atau 24.5+ CLI kini juga memercayai penyimpanan sistem selain daftar Node, sehingga langsung berfungsi tanpa pengaturan. Verifikasi sertifikat tidak pernah dimatikan. Pada Node yang lebih lama tidak ada yang berubah, dan pesan galat menyebut penerbit yang terlihat (misalnya AVG Web/Mail Shield Root).

• Nonaktifkan penyimpanan sistem dengan AOOX_SYSTEM_CA=0.
• NODE_EXTRA_CA_CERTS=/path/ke/root.pem tetap berfungsi bila Anda ingin memercayai satu root tertentu.
• Node lama: setel NODE_OPTIONS=--use-system-ca (Node 22.15+ / 23.10+), perbarui Node, atau tambahkan domain panel ke pengecualian pemindaian HTTPS antivirus.

Jebakan umum

Langkah berikutnya