Web terminal

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

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. Bila TERMINAL_SSH_USER kosong, terminal masuk sebagai root (default instalasi lama) — kartu Terminal menandainya sebagai user default. Instalasi baru lewat sudo aoox install atau skrip satu-perintah (curl … | sudo sh) mengisinya otomatis dengan nama user yang menjalankan sudo (bila berupa nama login polos dan bukan root; selain itu root; flag --terminal-ssh-user atau env TERMINAL_SSH_USER yang eksplisit selalu menang); instalasi lama tidak berubah (ubah lewat Environment, lihat User SSH di VPS cloud). Kalau koneksi gagal, terminal menampilkan tautan ke Infrastruktur → Environment untuk memperbaiki pengaturannya.

3. Otorisasi key platform

   Instalasi baru melakukannya sendiri: sudo aoox install dan skrip satu-perintah membuat key di secrets/ lalu menambahkannya ke ~/.ssh/authorized_keys user terminal. Untuk instalasi yang sudah ada, owner cukup klik Otorisasi otomatis di Infrastruktur → Terminal (atau di notifikasi galat halaman Terminal); aoox menambahkan public key ke authorized_keys user itu, menguji login, dan menyambung ulang. Tidak ada password atau private key yang ditulis. Perintah manual di bawah tetap tampil sebagai cadangan.

   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.

User SSH di VPS cloud

Terminal masuk ke host sebagai user di kolom User (TERMINAL_SSH_USER), dan perintah otorisasi key harus dijalankan di host sebagai user yang sama. Di VPS cloud (Ubuntu, Tencent, dan sejenisnya) login root biasanya dimatikan di sshd (PermitRootLogin no atau hanya lewat key provider), jadi default root sering ditolak.

1. Isi User dengan user login VPS

   Buka Infrastruktur → Environment (owner), isi User dengan user yang kamu pakai untuk SSH ke VPS — di Ubuntu biasanya ubuntu — lalu simpan. Panel memulai ulang kontainer API beberapa detik.

2. Otorisasi key sebagai user itu

   Di VPS, login sebagai user yang sama dan jalankan perintah otorisasi dari Infrastruktur → Akses terminal (tiga baris di atas). Perintah itu menulis ke ~/.ssh/authorized_keys milik user yang sedang menjalankannya, jadi jangan dijalankan dengan sudo.

3. Sambung ulang

   Klik Sambung ulang di menu Terminal.

Batas otorisasi otomatis

• Hanya untuk host aoox dengan key platform. Server remote tetap manual (perintah otorisasi di halaman Server remote), begitu juga bila memakai key atau password sendiri.
• Hanya owner yang melihat tombolnya (admin tetap bisa memakai perintah manual).
• Key ditulis ke ~/.ssh/authorized_keys user terminal. Kalau sshd memakai AuthorizedKeysFile di lokasi lain, key tidak akan dibaca: aoox melaporkan bahwa uji koneksi gagal, dan kamu perlu memasang key di lokasi itu.
• SELinux (mis. RHEL/Rocky) bisa menolak sshd membaca berkas yang baru ditulis; perbaiki konteksnya dengan restorecon -R ~/.ssh di host.
• Bila ~/.ssh atau authorized_keys berupa symlink, aoox menolak mengikutinya dan meminta otorisasi manual.
• Bila Docker memakai bridge/gateway kustom (bukan alamat default seperti host.docker.internal atau 172.17.0.1), tombol tidak muncul; gunakan perintah manual.
• Instalasi baru bisa melewatkan langkah otomatis dengan --no-terminal-authorize (CLI) atau AOOX_NO_TERMINAL_AUTHORIZE=1 (skrip satu-perintah).

Kredensial alternatif

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

Langkah berikutnya