$ aoox
EN

DocsMulai

Instalasi

Menjalankan aoox di server sendiri dengan Docker Compose, lalu membuat akun owner pertama.

Waktu
± 5 menit
Butuh
VPS Linux + Docker
Hasil
Dashboard di :3000, akun owner
Server baru? Mulai dari panduan VPS baru: SSH, user sudo, firewall, lalu instalasi ini, sampai domain dengan HTTPS.

Cara tercepat: satu perintah

Untuk VPS Linux baru yang masih kosong — memasang Docker (bila belum ada), membuat semua secret, dan menjalankan stack. Tidak perlu Node.js atau git clone apa pun dulu.

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

Dengan domain + HTTPS otomatis dan owner langsung dibuat:

curl -fsSL https://aoox.dev/install.sh \
  | sudo WEB_DOMAIN=panel.example.com API_DOMAIN=api.panel.example.com \
    ACME_EMAIL=kamu@example.com \
    ADMIN_EMAIL=kamu@example.com ADMIN_PASSWORD='kata-sandi-kuat' \
    sh
Butuh sudo (atau login sebagai root) — skrip memasang Docker dan menulis ke /opt/aoox. Kalau lupa, gagal dengan pesan must be run as root.
User SSH terminal. Instalasi baru, baik skrip satu-perintah ini maupun sudo aoox install, mengisi TERMINAL_SSH_USER otomatis dengan nama user yang menjalankan sudo (kalau dijalankan langsung sebagai root atau nama itu bukan login polos, hasilnya root). Instalasi baru juga mengotorisasi key terminal otomatis (membuat key di secrets/ dan menambahkannya ke ~/.ssh/authorized_keys user itu); lewati dengan AOOX_NO_TERMINAL_AUTHORIZE=1 di depan sh (atau --no-terminal-authorize pada CLI). Langkah ini menolak~/.ssh atau authorized_keys yang berupa symlink; gagal di sini hanya memberi peringatan, instalasi tetap lanjut. Isi eksplisit menang: tambahkan TERMINAL_SSH_USER=ubuntu di depan sh pada skrip, atau --terminal-ssh-user pada CLI. Instalasi lama tidak berubah — ubah lewat Infrastruktur → Environment. Di VPS cloud login root biasanya dimatikan, jadi user ini yang harus dipakai; detailnya di Web terminal.
Skrip ini di-serve dari domain aoox sendiri (bukan pihak ketiga) dan mengambil file compose langsung dari repo aoox-cli — source-nya bisa dibaca dulu di public/install.sh sebelum menjalankannya. Perlu perintah yang meminta konfirmasi dan mendukung flag, bukan env var? Pakai aoox install dari CLI — logikanya sama persis, tinggal preferensi. Bedanya dengan skrip di atas: aoox install butuh CLI-nya sendiri sudah terpasang di server itu dulu, sedangkan install.sh di atas tidak butuh apa-apa selain curl dan sh. Memasang CLI-nya sendiri juga tidak butuh Node.js — lihat instalasi CLI tanpa Node.js (curl -fsSL https://aoox.dev/install-cli.sh | sh).

Manual: prasyarat

Langkah di bawah ini cocok kalau kamu ingin lihat/kendalikan setiap bagian sendiri.

  • Server Linux dengan Docker 24+ dan Compose v2. Cek: docker compose version.
  • Port 3000 (web) dan 3001 (API) terbuka di firewall untuk browser kamu. Port 80/443 harus kosong bila nanti memakai domain.
  • Akses ke socket Docker (/var/run/docker.sock) — API memakainya untuk build dan menjalankan container.
Spesifikasi minimum
Untuk server yang menjalankan panel: minimal 1 vCPU dan 2 GB RAM plus swap (2 GB dengan swap adalah minimum yang sudah diuji), disarankan 4 GB atau lebih, terutama untuk build Railpack atau beberapa database (lihat Memilih VPS dan menambah swap). Stack panel yang menganggur (PostgreSQL, API, web, proxy, dan registry) sudah memakai sekitar 600-900 MB sebelum ada aplikasi, dan build image di server butuh 1-2 GB lagi. RAM 1 GB hanya cukup untuk server remote (Infrastruktur → Server remote) yang menjalankan aplikasi tanpa panel; tambahkan swap di sana juga. Kebutuhan sebenarnya ditentukan aplikasi dan database yang kamu deploy; build Nixpacks pertama butuh ± 1 GB ruang disk tambahan untuk base image.

Manual: langkah demi langkah

  1. Clone repo API dan salin file env

    File compose distribusi dan contoh env ada di repo aoox-api.

    git clone https://github.com/hideandseeklab/aoox-api.git
cd aoox-api
cp .env.dist.example .env.dist

  2. Buat secret dan cari GID Docker

    Jalankan di server, lalu salin hasilnya ke langkah berikutnya:

    Nilai yang dibutuhkan
    openssl rand -hex 32                  # JWT_SECRET
openssl rand -hex 32                  # ENCRYPTION_KEY
stat -c %g /var/run/docker.sock       # DOCKER_GID (biasanya 999 atau 0)

  3. Isi .env.dist

    .env.dist (minimal)
    POSTGRES_PASSWORD=ganti-dengan-password-kuat
JWT_SECRET=<hasil openssl #1>
ENCRYPTION_KEY=<hasil openssl #2>
DOCKER_GID=<hasil stat>

# URL yang diketik di browser — harus sama persis
WEB_ORIGIN=http://192.168.1.10:3000
PUBLIC_API_URL=http://192.168.1.10:3001
    VariabelKeterangan
    POSTGRES_PASSWORDPassword database internal aoox.
    JWT_SECRETRahasia untuk token sesi. Mengganti = semua pengguna logout.
    ENCRYPTION_KEYKunci enkripsi kredensial tersimpan (registry, Git, notifikasi, S3). Jangan diganti setelah ada data — kredensial lama tidak bisa dibaca lagi.
    DOCKER_GIDGID socket Docker agar container API boleh memakai Docker host.
    WEB_ORIGIN / PUBLIC_API_URLURL web & API dari sisi browser. Cookie sesi dan gateway terminal memeriksa origin ini — beda skema/host/port = ditolak.

  4. Jalankan stack

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

    Image diambil dari Docker Hub (hideandseeklab/aoox-api dan hideandseeklab/aoox-web). Migrasi database dijalankan otomatis saat container API pertama kali boot.

  5. Buat akun owner

    Buka WEB_ORIGIN di browser. Saat tabel pengguna masih kosong kamu diarahkan ke /setup — isi nama, email, dan password untuk akun owner pertama.

    Tanpa interaksi (opsional)

    Isi ADMIN_EMAIL, ADMIN_PASSWORD, ADMIN_NAME di .env.dist sebelum up -d. Nilai ini hanya dipakai saat belum ada pengguna dan tidak pernah menimpa akun yang sudah ada.

Verifikasi

Dari server
docker compose -f docker-compose.dist.yml --env-file .env.dist ps
# api, web, postgres → running

curl -s http://localhost:3001/auth/setup-status
# {"needsSetup":true}  sebelum akun owner dibuat
# {"needsSetup":false} sesudahnya
  • Setelah login, Dashboard tampil dan menu Settings bisa dibuka tanpa error.
  • Menu Terminal boleh menampilkan petunjuk SSH — itu normal sebelum terminal dikonfigurasi.

Langkah berikutnya

Aktifkan registry lokalWajib sebelum deploy aplikasi pertama.Aktifkan reverse proxySupaya aplikasi bisa diakses lewat domain + HTTPS.Domain untuk panelLayani dashboard di panel.example.com.Undang timTambah anggota dengan peran owner/admin/member.

Memperbarui versi

Cara tercepat (butuh INSTALL_DIR terisi, sama seperti Domain panel): Settings → Update aoox → Cek update → Terapkan. Atau dari CLI:

Menekan Terapkan update memunculkan dialog konfirmasi (restart panel biasanya 1–3 menit), lalu kartu berpindah ke mode “Sedang memperbarui” — tombol dinonaktifkan, dan dashboard memeriksa sendiri secara berkala sampai panel kembali dengan versi baru, lalu memuat ulang halaman otomatis. Selama menunggu, koneksi yang sempat terputus (karena container api/web sedang di-restart) tidak ditampilkan sebagai error — itu memang bagian dari prosesnya. Kalau lebih dari 5 menit panel belum juga kembali, kartu menampilkan langkah cek manual lewat SSH.

Saat ada versi aoox yang lebih baru dipublikasikan, owner melihat tombol Update tersedia (dengan nomor versinya) di bagian bawah sidebar — klik untuk membuka halaman Update aoox. Peran lain tidak melihatnya. Server memeriksa versi terbaru di Docker Hub sendiri (sekali setelah panel menyala, lalu tiap beberapa jam); kalau server tidak punya akses internet, tombolnya tidak muncul dan tidak ada error. Tombol hanya muncul untuk instalasi yang mengikuti tag :latest — kalau image dikunci ke tag lain, halaman Update aoox hanya menampilkan versi terbaru sebagai informasi.

aoox update panel            # cek saja
aoox update panel --apply    # terapkan kalau ada update

Manual lewat SSH, kalau INSTALL_DIR belum diisi:

docker compose -f docker-compose.dist.yml --env-file .env.dist pull
docker compose -f docker-compose.dist.yml --env-file .env.dist up -d

Migrasi database berjalan otomatis saat API boot. Untuk mengunci versi, isi API_IMAGE dan WEB_IMAGE di .env.dist, mis. hideandseeklab/aoox-api:0.1.0-rc.1 (lihat tag yang tersedia di Docker Hub) — kedua cara di atas membaca variabel yang sama. Instalasi yang mengunci tag tidak akan melihat tombol “Update tersedia” di sidebar; halaman Update aoox tetap menampilkan versi terbaru sebagai informasi. Panel mengenali tag yang terpasang dari variabel API_IMAGE yang kini diteruskan compose ke container API (instalasi lama: jalankan aoox reinstall supaya compose-nya ikut diperbarui).

Pada instalasi yang dikunci ke tag, halaman Update aoox menonaktifkan Terapkan update dan menjelaskan alasannya: menarik tag yang sama lagi tidak mengubah versi, dan aoox update panel --apply / API menolak alih-alih melaporkan berhasil. Untuk pindah ke versi yang lebih baru, ubah API_IMAGE dan WEB_IMAGE ke tag baru (atau hapus kedua baris agar mengikuti :latest), lalu jalankan sudo aoox reinstall. Satu pengecualian: tag terkunci yang dipublikasikan ulang dengan nama yang sama tetap bisa diterapkan.

Catatan penting: baik aoox update panel maupun tombol “Terapkan update” hanya menjalankan pull + up -d dengan file docker-compose.dist.yml yang sudah ada di server — keduanya tidak pernah menulis ulang file compose itu sendiri. Kalau sebuah rilis menambahkan variabel baru ke file compose (misalnya env baru yang harus diteruskan ke sebuah service), instalasi lama tidak otomatis mendapatkannya lewat update — begitu juga variabel baru di .env.dist (contohnya Terminal yang error TERMINAL_SSH_USER is not set setelah update). Perbaikan paling mudah dan aman untuk data: sudo aoox reinstall — menulis ulang compose dari salinan terbaru, menggabungkan .env.dist (secret tidak pernah dibuat ulang), lalu pull + recreate tanpa menyentuh volume. Pilih reinstall, bukan aoox install --new-secrets (yang hanya ada bersama --wipe-data dan menghapus data lama). Cara manual: edit docker-compose.dist.yml di INSTALL_DIR (default /opt/aoox) sesuai catatan rilis, lalu:

docker compose -f docker-compose.dist.yml -f docker-compose.override.yml --env-file .env.dist up -d

(-f docker-compose.override.yml hanya kalau file itu ada — dibuat otomatis saat memakai Domain panel dari dashboard).

Build dari source

Checkout aoox-api dan aoox-web bersebelahan, lalu tambahkan file compose build:

docker compose -f docker-compose.dist.yml -f docker-compose.build.yml --env-file .env.dist up -d --build

Menghapus

docker compose -f docker-compose.dist.yml --env-file .env.dist down -v
Hati-hati
-v menghapus volume data aoox (pengguna, project, riwayat deployment). Container aplikasi, database, registry, dan proxy yang dibuat dari dashboard tidak ikut terhapus — hapus dari dashboard dulu, atau lewat docker dengan filter label com.docker.compose.project=aoox.

Ada yang keliru? Edit halaman ini di GitHub ↗