$ aoox

DocsInfrastruktur

Web terminal

Shell ke host aoox (atau server remote) langsung dari browser, untuk owner dan admin.

Siapa
Owner & admin saja
Ke mana
Host aoox (SSH) atau server remote
Klien
xterm.js di browser → Socket.IO → SSH

Cara kerja

Container tidak bisa membuka shell di host-nya sendiri, jadi API terhubung ke host lewat SSH. Browser tidak pernah memegang kredensial SSH:

  1. 01tiketbrowser minta tiket JWT 60 detik, sekali pakai, scope terminal
  2. 02socketSocket.IO /terminal dengan tiket + ukuran kolom/baris
  3. 03sshAPI membuka sesi SSH ke target memakai key platform
  4. 04shellinput/output diteruskan; resize mengikuti jendela
ModeKapanShell yang didapat
SSH ke hostTERMINAL_SSH_HOST terisi (default host.docker.internal)Shell user SSH di host — yang biasanya kamu mau.
LokalTERMINAL_SSH_HOST kosongShell di dalam container API (bash sebagai user node) — hanya untuk debug API.

Menyiapkan SSH ke host

  1. Aktifkan SSH server di host

    Linux
    sudo apt install openssh-server && sudo systemctl enable --now ssh

    Windows (dev): fitur opsional OpenSSH Server. Compose distribusi sudah memetakan host.docker.internal ke gateway host di Linux.

  2. Isi env terminal di .env.dist

    .env.dist
    TERMINAL_SSH_HOST=host.docker.internal
TERMINAL_SSH_PORT=22
TERMINAL_SSH_USER=deploy        # user host yang dipakai terminal

    Jalankan up -d lagi setelah mengubah env. Tanpa TERMINAL_SSH_USER kartu Terminal menampilkan Perlu perhatian.

  3. Otorisasi key platform

    API membuat keypair ed25519 di ./secrets saat pertama dibutuhkan. Settings → Terminal menampilkan public key dan perintah untuk dijalankan sekali di host sebagai TERMINAL_SSH_USER:

    mkdir -p ~/.ssh && chmod 700 ~/.ssh
touch ~/.ssh/authorized_keys && chmod 600 ~/.ssh/authorized_keys
echo 'ssh-ed25519 AAAA… aoox' >> ~/.ssh/authorized_keys

    Key yang sama dipakai untuk server remote — otorisasi sekali per host.

  4. Buka menu Terminal

    Pilih target (Host aoox / server remote) dan mulai mengetik. Ukuran terminal mengikuti jendela browser; sesi ditutup saat tab ditutup atau koneksi putus.

Kredensial alternatif

EnvKapan dipakaiCatatan
TERMINAL_SSH_PRIVATE_KEY_FILEBawa key sendiriPath di container API (mount ke /run/secrets/…); TERMINAL_SSH_PASSPHRASE bila terenkripsi.
TERMINAL_SSH_PRIVATE_KEYKey inline di envKurang praktis; hindari di file yang di-commit.
TERMINAL_SSH_PASSWORDPassword SSHKurang aman — hanya untuk uji cepat.

Prioritas: key eksplisit → password → key platform (default).

Tips pemakaian

  • Semua container aoox terlihat dari host: docker ps --filter label=com.docker.compose.project=aoox.
  • Masuk ke container aplikasi: docker exec -it aoox-app-<slug> sh. Untuk perintah rutin, lebih rapi pakai job.
  • Log proxy saat sertifikat bermasalah: docker logs -f aoox-proxy.
  • Tempel dengan Ctrl+Shift+V (Linux/Windows) atau Cmd+V (macOS); Ctrl+C diteruskan ke shell, bukan menyalin.

Bila gagal

PesanPenyebab & solusi
auth failed + perintah otorisasiKey belum ada di authorized_keys user itu. Jalankan perintah yang ditampilkan di terminal/Settings.
origin not allowedWEB_ORIGIN tidak sama persis dengan URL di browser (skema/host/port). Samakan, up -d ulang.
TERMINAL_SSH_USER is not setIsi env, restart stack.
connect ECONNREFUSED / timeoutsshd tidak jalan, port salah, atau host.docker.internal tidak resolve (Linux tanpa extra_hosts — pakai IP gateway docker0, mis. 172.17.0.1).
Direktori key tidak writable (uid 1000)Perbaiki kepemilikan folder ./secrets: sudo chown -R 1000:1000 ./secrets.
403 saat membuka terminalPeran member. Hanya owner/admin.
Ini setara shell di host
Hanya owner dan admin yang bisa membuat tiket terminal; dicek lagi di gateway. Tiket berumur 60 detik dan sekali pakai; gateway menolak Origin selain WEB_ORIGIN. Fitur ini dimaksudkan untuk lingkungan dev/self-hosted yang dipercaya — host key SSH belum diverifikasi. Pembukaan sesi (pembuatan tiket) tercatat di audit log; perintah yang diketik tidak.

Langkah berikutnya

Server remoteTarget terminal selain host.Pengguna & peranKenapa member tidak punya terminal.Domain untuk panelWEB_ORIGIN yang benar untuk terminal.Troubleshootingorigin not allowed dan kawan-kawannya.

Ada yang keliru? Edit halaman ini di GitLab ↗