Cara Self-Host Rakazo di VPS dengan Docker Compose
Panduan menjalankan Rakazo di VPS Linux dengan Node 22, pnpm, PostgreSQL, Graphile Worker, Docker Compose, pilihan sandbox, pengelolaan kunci, dan ukuran server.
Komponen yang sebenarnya dijalankan oleh Rakazo saat di-host sendiri
Self-hosting Rakazo berarti menjalankan lima komponen pada satu server Linux: PostgreSQL, proses Graphile Worker, API, aplikasi web, dan container sandbox yang berfungsi sebagai komputer bot. Rakazo adalah alternatif open-source untuk Grok Bot yang diterbitkan oleh elie222 berdasarkan lisensi Apache 2.0. Setiap bot memiliki percakapan, memori, rutinitas, dan riwayatnya sendiri. Bot menggunakan satu Team Computer bersama bot lain dalam workspace, kecuali bot tersebut diberi Private Computer. Bot juga dapat membuat peer atau subagent berumur pendek. Jika istilah seperti memori, subagent, dan pemanggilan tool dalam kalimat tersebut masih belum jelas, panduan bertahap tentang cara kerja agent layak dibaca terlebih dahulu. Sebagian besar pengaturan di bawah baru mudah dipahami setelah Anda dapat membayangkan tindakan bot saat aktif.
Bagian terakhir itulah alasan Rakazo sebaiknya dijalankan pada VPS (virtual private server), bukan pada komputer desktop. Bot yang menyimpan memori dan menjalankan tugas terjadwal harus tetap dapat diakses saat Anda tidur. Laptop yang masuk ke mode suspend akan menghentikan antrean.
Rakazo masih menyebut dirinya sebagai beta hingga Oktober 2026, meskipun kini menerbitkan release dengan nomor stabil. Karena itu, anggap konfigurasi ini sebagai setup yang dapat digunakan, bukan appliance yang sudah selesai sepenuhnya. Seluruh stack menggunakan TypeScript: React 19 dan Vite untuk aplikasi web, Hono untuk API, Postgres dengan Prisma, Better Auth untuk akun, serta Graphile Worker untuk job latar belakang. Graphile Worker menyimpan antreannya di dalam Postgres, sehingga tidak ada Redis dan tidak ada penyimpanan data kedua yang perlu dijalankan. .env.example menetapkan WAKEUP_DRIVER=graphile, yang berarti bot yang aktif kembali direpresentasikan sebagai job berbasis Postgres. Jika Postgres dihentikan, semua tindakan bot yang terjadwal juga berhenti. Jika Anda lebih memilih merakit agent dari berbagai komponen daripada menjalankan produk milik pihak lain, membangun agent sendiri dari berbagai komponen adalah pilihan lainnya.
Mengapa paket 1 GB tidak akan mampu menanganinya
Hitung prosesnya. Postgres adalah satu proses. API adalah proses Node. Worker adalah proses kedua. Aplikasi web adalah proses ketiga. Supervisor sandbox adalah proses keempat. Setelah itu ada komputer milik bot: secara default, satu container Team Computer bersama yang berisi desktop Linux grafis, dengan display X terpisah dan proses Chrome untuk setiap bot yang aktif.
Dokumentasi self-host proyek tersebut tidak lagi mencantumkan ukuran host. Dokumentasi di v0.3.5, yang diperiksa pada 27 October 2026, hanya mencantumkan persyaratan perangkat lunak. Informasi yang tersedia adalah batas per komputer: dengan Docker sandbox, RAKAZO_COMPUTER_MEMORY secara default bernilai 2g dan RAKAZO_COMPUTER_CPUS bernilai 2. Batas tersebut berlaku untuk setiap komputer, bukan setiap bot. Setiap workspace secara default mendapat satu Team Computer, dan setiap Team bot yang aktif menjalankan desktop serta browser-nya di dalam komputer tersebut. Artinya, semua bot berbagi 2 GB dan dua core itu. Hanya bot yang dipindahkan ke Private Computer yang mendapatkan container dan batasnya sendiri. Atur SANDBOX_PROVIDER=docker agar desktop tersebut berjalan di VPS Anda, di samping control plane. Dengan demikian, 4 GB adalah batas minimum, bukan target. Mulailah dengan 8 GB jika Anda berencana membiarkan lebih dari satu bot tetap aktif. Naikkan RAKAZO_COMPUTER_MEMORY agar komputer bersama benar-benar dapat menggunakan memori tersebut. Ukur penggunaan aktual dengan docker stats saat bot bekerja. Browser di dalam sandbox yang paling memengaruhi penggunaan memori, sehingga lembar spesifikasi tidak dapat memberi jawaban pasti. Untuk mencegah server kecil menjalankan terlalu banyak browser sekaligus, tetapkan SANDBOX_TEAM_SCREEN_LIMIT dengan nilai positif. Pengaturan ini membatasi jumlah desktop aktif pada Docker Team Computer. Nilai bawaan 0 tidak menetapkan batas. Jika memori secara keseluruhan terbatas, RAKAZO_COMPUTER_MEMORY juga menerima nilai yang lebih kecil seperti 1536m. Untuk metode umum menentukan ukuran server bagi pekerjaan agent, berapa RAM dan CPU yang sebenarnya dibutuhkan VPS agent membahas pengukurannya secara terperinci.
Satu pengaturan dapat mencegah kondisi ini memburuk. .env.example menggunakan nilai bawaan SANDBOX_IDLE_MS=600000, dan komentarnya menyatakan bahwa komputer dijeda atau dihentikan setelah jumlah milidetik tersebut dalam keadaan idle. Setelah idle selama sepuluh menit, komputer dihentikan. Nilai minimum yang diterima adalah 30000, sedangkan 0 menonaktifkan sleep saat idle. Komentar yang sama menyarankan nilai 0 untuk self-host Docker, karena komputer yang idle tidak menimbulkan biaya. Dengan begitu, aplikasi dan sesi yang berjalan lama tetap aktif. Hal ini berlaku untuk biaya, bukan memori. Pada VPS kecil, biarkan timer tetap aktif. Tanpa timer tersebut, setiap komputer yang pernah Anda jalankan, beserta setiap browser di dalamnya, akan terus berjalan.
Penggunaan disk juga perlu diperhitungkan. Image sandbox, modul Node, dan volume Postgres menggunakan disk yang sama. Karena itu, 40 GB adalah titik awal yang wajar.
Tetapkan versi sebelum melakukan clone
Rakazo berkembang dengan cepat dan main bukan rilis. Per 9 November 2026, v0.8.0, yang diterbitkan pada 4 November 2026, merupakan rilis yang ditandai sebagai Latest. Panduan ini tetap menggunakan v0.3.5, yang diterbitkan pada 25 October 2026.
git clone https://github.com/elie222/rakazo.git
cd rakazo
git checkout f31e3c0699f086d663637c4107858c238a086fb3
git log -1 --format='%H %ci'Commit tersebut adalah commit yang ditunjuk oleh v0.3.5. Tetapkan commit, bukan branch atau tag. Branch dapat berubah pada git pull berikutnya, sedangkan tag adalah label yang dapat dipindahkan dan diarahkan ulang oleh maintainer. Karena itu, keduanya tidak mengidentifikasi tree yang dapat Anda gunakan kembali. Identifier commit tidak dapat berubah. Catat identifier tersebut bersama informasi server lainnya. Saat upgrade menyebabkan masalah, perbaikan cepatnya adalah git checkout <old commit> lalu melakukan rebuild. Cara ini hanya berhasil jika Anda mengetahui commit yang sebelumnya berfungsi. README yang ditetapkan menyebut Rakazo sebagai beta. Karena itu, menetapkan versi secara tepat sepadan dengan sedikit usaha yang diperlukan. Project dengan riwayat rilis yang disengaja dan panjang dapat ditetapkan pada tag rilis yang diterbitkan. Itulah yang dilakukan oleh stack self-hosted yang lebih kecil seperti openGym.
Persyaratan: Node 22, pnpm 9, dan Docker
node -v
pnpm -v
docker --versionpackage.json mendeklarasikan "engines": { "node": "^22.22.2 || ^24.0.0 || >=26.0.0" } dan "packageManager": "pnpm@9.15.0". Jadi, node -v harus mencetak v22.22.2 atau versi 22.x yang lebih baru, v24 apa pun, atau v26 dan versi yang lebih baru. v22 yang lebih lama dari 22.22.2 berada di luar rentang tersebut, dan README menyatakan secara eksplisit bahwa Node.js 23.x dan 25.x tidak didukung. Instal versi Node yang didukung dari NodeSource atau nvm. Corepack disertakan dalam Node 22 dan 24. Pada Node 26 dan versi yang lebih baru, instal Corepack terlebih dahulu dengan npm install -g corepack. Kemudian aktifkan pnpm:
corepack enable
corepack prepare pnpm@9.15.0 --activateDocker Engine dan plugin compose mencakup kebutuhan lainnya. Dokumentasi self-host meminta Docker Engine 26 atau yang lebih baru serta API 1.45 atau yang lebih baru untuk subpath volume home bot, bersama curl dan OpenSSL. User Anda juga harus dapat mengakses daemon. Jika docker ps menghasilkan permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock, tambahkan user Anda ke grup docker, lalu buka shell login baru. Pahami terlebih dahulu hak akses yang diberikan: keanggotaan dalam docker setara dengan root pada mesin tersebut, karena siapa pun dalam grup itu dapat menjalankan container yang memasang filesystem host.
Konfigurasikan .env, lalu jalankan Postgres
cp .env.example .env
chmod 600 .envBeberapa nilai harus diubah sebelum apa pun dijalankan. .env.example menyediakan BETTER_AUTH_SECRET=replace-with-32-plus-character-secret, ENCRYPTION_KEY=replace-with-64-random-hex-characters, SCREEN_PROXY_SECRET=replace-with-32-plus-character-screen-proxy-secret, dan SANDBOX_SUPERVISOR_TOKEN=replace-with-32-plus-character-supervisor-token, serta membiarkan POSTGRES_PASSWORD dan POSTGRES_APP_PASSWORD kosong. Semua placeholder tersebut dipublikasikan di repository. Karena itu, deployment yang masih menggunakan salah satunya akan berjalan dengan secret yang dapat dibaca siapa saja. Berikan nilai acak yang berbeda untuk setiap placeholder. ENCRYPTION_KEY harus berisi 64 karakter heksadesimal acak. Nilai tersebut dapat dibuat tepat dengan perintah yang ditampilkan oleh openssl rand -hex 32. Secret lainnya memerlukan 32 karakter atau lebih. Jalankan baris base64 satu kali untuk setiap secret. Untuk dua password Postgres, dokumentasi self-host meminta nilai yang aman digunakan dalam URL. Baris terakhir menghasilkan nilai tersebut, jadi jalankan baris itu satu kali untuk setiap password. Database memiliki dua login. DATABASE_MIGRATION_URL disediakan sebagai postgres://rakazo:REPLACE_WITH_POSTGRES_PASSWORD@127.0.0.1:5433/rakazo, yaitu pemilik yang menjalankan migration, sedangkan DATABASE_URL disediakan sebagai postgres://rakazo_app:REPLACE_WITH_POSTGRES_APP_PASSWORD@127.0.0.1:5433/rakazo, yaitu login khusus aplikasi yang tidak memiliki hak superuser dan dibatasi oleh keamanan tingkat baris. Masukkan setiap password ke dalam URL masing-masing. pnpm db:migrate membuat login rakazo_app dengan password yang Anda tetapkan.
openssl rand -base64 48
openssl rand -hex 32
openssl rand -hex 24Selanjutnya, jalankan database secara mandiri dan jalankan migration.
docker compose --env-file .env -f infra/compose/docker-compose.yml -f infra/compose/docker-compose.postgres-host.yml up postgres -d
pnpm install
pnpm db:generate
pnpm db:migrate
pnpm sandbox:buildpnpm sandbox:build membangun image komputer bot yang didefinisikan dalam package.json sebagai docker build -t rakazo/computer:local infra/sandboxes/computer. Image ini memiliki antarmuka grafis. Karena itu, proses build pertama mengunduh banyak data dan memerlukan waktu. Pastikan image tersebut berhasil dibuat dengan docker image ls rakazo/computer. Perintah itu seharusnya menampilkan satu baris.
File compose dasar sama sekali tidak memublikasikan port Postgres. Overlay docker-compose.postgres-host.yml dalam perintah tersebut memublikasikannya sebagai 127.0.0.1:5433, yang hanya dapat diakses melalui loopback. Dengan demikian, tool pada host seperti pnpm db:migrate dan pnpm dev dapat terhubung. Biarkan konfigurasi tersebut. Compose menolak menjalankan Postgres tanpa POSTGRES_PASSWORD dalam .env. Namun, port Postgres yang dapat diakses dari Internet memungkinkan serangan terhadap password. File compose production membaca variabel yang sama dan tidak memublikasikan port database.
Proses pertama
pnpm devPerintah tersebut menjalankan empat hal: API pada port 3100, Graphile Worker, aplikasi web Vite pada port 5173, dan supervisor sandbox pada port 7091 secara default. Jika port tersebut sedang digunakan, pnpm dev memilih blok port kosong lain dan mencetak URL-nya. Pada port default, aplikasi tersedia di http://127.0.0.1:5173, dan Anda seharusnya melihat halaman sign-in.
Pada VPS, Anda tidak berada di mesin tersebut. Anda juga tidak seharusnya memublikasikan port 5173 agar dapat mengaksesnya. Teruskan port melalui SSH (secure shell) dari mesin Anda sendiri.
ssh -L 5173:127.0.0.1:5173 -L 3100:127.0.0.1:3100 you@your-serverPerhatikan perbedaan antara cara menjalankan konfigurasi ini. pnpm dev menjalankan Vite pada host dan mengikatnya secara lokal. Service web pada file compose development memublikasikan 127.0.0.1:5173:5173, sedangkan service api memublikasikan 127.0.0.1:3100:3100. Keduanya hanya tersedia pada loopback, sehingga tunnel yang sama dapat digunakan. Pada file production, aplikasi web tidak memublikasikan port host. Aplikasi tersebut hanya mengekspos port 5173 kepada container di jaringan internalnya sendiri. Hanya Caddy yang memublikasikan port 80 dan 443. Karena itu, gunakan file production dan reverse proxy-nya untuk apa pun yang Anda biarkan tetap berjalan.
Provider sandbox mana yang aman di server?
Ini satu-satunya pengaturan yang harus benar. SANDBOX_PROVIDER di .env secara default adalah docker, dan checkout yang dipin juga mendukung Railway selain provider yang tercantum dalam dokumentasi self-host.
dockeradalah default. Komputer bot berjalan sebagai container pada mesin Anda, dibuat dari imagepnpm sandbox:buildyang diproduksi dan dijalankan di bawah supervisor. Bot dalam satu workspace secara default berbagi satu Team Computer, sedangkan bot hanya mendapatkan container sendiri pada Private Computer. Akun E2B tidak diperlukan.e2bmenjalankan komputer bot pada E2B dan memerlukanE2B_API_KEY. Padav0.3.5, factory menerimanya di production jika key diberikan, tanpa pembatasanNODE_ENV. Dokumentasi self-host menyebutnya sesuai untuk production publik atau multi-pengguna karena komputer bot tetap terpisah dari host yang menjalankan API dan database Anda.daytona,createos, danboatadalah provider remote tambahan. Masing-masing memerlukan key sendiri:DAYTONA_API_KEY,CREATEOS_SANDBOX_API_KEY, atauBOAT_API_KEY.railwaymenjalankan komputer pada Railway dan memerlukanRAILWAY_API_TOKENsertaRAILWAY_ENVIRONMENT_IDyang dipilih secara eksplisit pada API dan worker. Gunakan project atau environment Railway khusus untuk sandbox.desktopmenjalankan command bot langsung pada host API dan worker, sesuai penjelasan dokumentasi. Padav0.3.5, API dan worker menolaknya kecualiNODE_ENVadalahdevelopmentatautest, tetapi.env.examplemenyediakanNODE_ENV=development, sehingga server yang menjalankanpnpm devtetap menerimanya. Jangan aktifkan ini pada service publik atau bersama.fakeadalah emulator yang hanya digunakan untuk verifikasi. Ini bukan runtime.nonemenjalankan product tanpa host komputer sama sekali.
Pahami hal ini secara harfiah. Dalam mode desktop, tidak ada batas isolasi sama sekali. Bot menjalankan shell command sebagai user yang menjalankan proses API, dengan home directory user tersebut, SSH key user tersebut, kredensial cloud user tersebut, dan .env milik user tersebut. Teks pada halaman web yang dibaca bot dapat menjadi command pada server Anda. Mode desktop pada server dapat membuat bot menguasai kredensial Anda. Gunakan mode ini pada mesin yang Anda gunakan secara langsung, atau jangan gunakan sama sekali. Mengganti provider menempatkan container di sekitar jalur halaman web tersebut, bukan menutupnya. Memberi bot backend pencarian SearXNG sendiri juga menangani permukaan injeksi yang sama dari sisi pencarian.
docker merupakan batas nyata antara bot dan host Anda, tetapi batasnya lemah di antara bot itu sendiri. Secara default, bot berbagi satu Team Computer. Dokumentasi runtime komputer menyatakan bahwa bot Team berbagi user OS, workspace, profil browser, serta akses shell dan X11. Dokumentasi itu juga menyatakan bahwa folder per bot hanya mengatur pekerjaan dan bukan batas keamanan. Jadi, bot Team mana pun dapat membaca file bot Team lain. Bot yang memerlukan isolasi sendiri harus ditempatkan pada Private Computer. Provider docker menjalankannya sebagai container saudara terpisah pada network-nya sendiri. Namun, supervisor yang membuat container tersebut memasang /var/run/docker.sock. Dokumentasi self-host menyatakannya dengan jelas: akses ke socket tersebut setara dengan kendali atas host Docker. Jadi, jaga supervisor tetap privat. .env.example memperlakukan SANDBOX_SUPERVISOR_TOKEN sebagai kredensial khusus yang berbeda dari BETTER_AUTH_SECRET. Sandbox Docker memerlukannya di luar pengembangan lokal, dan product tersebut menyertakan placeholder yang dapat dibaca siapa pun di GitHub. Berikan nilai acak yang hanya digunakan untuknya. Untuk pemisahan terkuat yang tersedia di sini, gunakan e2b, atau berikan Rakazo mesin yang tidak menyimpan apa pun selain itu. Alasan yang sama berlaku untuk menjalankan coding agent dalam VM sekali pakai: cara termurah untuk menghadapi agent yang melakukan kesalahan adalah menggunakan mesin yang tidak bernilai apa pun.
Ke mana kunci API model disimpan?
Penagihan kredit model opsional Rakazo tetap nonaktif kecuali kedua secret Stripe telah diatur. Anda yang menyediakan kuncinya. .env.example menetapkan PI_DEFAULT_PROVIDER=openrouter, sehingga OPENROUTER_API_KEY biasanya menjadi tempatnya, dan kunci provider berfungsi melalui pengaturan yang sama.
Simpan kunci tersebut di .env dan jangan masukkan ke file yang Anda commit. Kedua perintah compose dalam repository meneruskan --env-file .env, sehingga nilainya sampai ke container tanpa pernah ditulis ke YAML yang dilacak oleh git. Anda juga dapat membiarkan OPENROUTER_API_KEY kosong dan menghubungkan model di aplikasi setelah signup. Ini menjadi alasan lain mengapa ENCRYPTION_KEY harus menggunakan nilai acak yang benar, bukan placeholder bawaan.
Tetapkan batas pengeluaran pada kunci di provider sebelum bot pernah menggunakannya. Bot yang berjalan dalam loop akan terus menimbulkan biaya. Rakazo juga menyediakan MAX_TOOL_CALLS_PER_TURN: tetapkan bilangan bulat positif untuk menghentikan sementara satu giliran yang melampaui anggaran pemanggilan tool, sambil tetap menghasilkan pesan akhir dari assistant. Jika tidak ditetapkan, kosong, atau bernilai 0, batasnya tidak dibatasi. Pengaturan ini menghitung pemanggilan tool, bukan biaya, sehingga tidak menggantikan batas pengeluaran dari provider. Beri kunci ini nama khusus agar Anda dapat mencabutnya secara terpisah. Jika Anda menyiapkannya untuk tim, bukan untuk diri sendiri, satu gateway OneCLI di depan agent semua orang merupakan jawaban berbeda untuk masalah yang sama, karena kunci provider disimpan di satu tempat, bukan satu kunci per orang.
Beralih dari mode pengembangan ke konfigurasi yang dapat dibiarkan berjalan
Repositori menyediakan file compose production yang menjalankan Postgres, API, worker, aplikasi web, dan Caddy untuk sertifikat TLS (transport layer security) yang diperolehnya secara otomatis. Caddy adalah satu-satunya service di dalamnya yang memublikasikan port. Secara default, file ini menggunakan E2B untuk komputer bot. Overlay opsional, infra/compose/docker-compose.prod.docker.yml, menjalankan komputer Docker lokal pada stack yang sama. Dokumentasi memperingatkan bahwa supervisor yang ditambahkannya memiliki hak yang setara dengan root pada host.
sudo --preserve-env=SSH_CONNECTION DEPLOY_USER=deploy bash infra/compose/harden-host.sh
docker compose --env-file .env -f infra/compose/docker-compose.prod.yml \
build --build-arg GIT_SHA=$(git rev-parse HEAD)
docker compose --env-file .env -f infra/compose/docker-compose.prod.yml \
up -d --wait --pull never
curl --fail https://app.example.com/healthBuat akun deploy yang hanya menggunakan key, lalu pastikan Anda dapat login dengan akun tersebut sebelum menjalankan script. harden-host.sh menonaktifkan login SSH menggunakan password dan login root, menerapkan pembatasan laju pada SSH, menambahkan izin SSH, HTTP, dan HTTPS melalui UFW (uncomplicated firewall) sambil mempertahankan aturan jaringan privat yang sudah ada, serta mengaktifkan fail2ban, pembaruan keamanan tanpa pengawasan, AppArmor, dan aturan audit. Script ini tidak mau dijalankan tanpa SSH_CONNECTION. Karena itu, perintah meneruskannya melalui sudo. Script ini membatalkan perubahan firewall kecuali Anda mengonfirmasinya dari sesi SSH baru dalam waktu tiga menit. Baca script tersebut sebelum menjalankannya karena script ini mengubah cara Anda login dan memuat ulang SSH. Biarkan konsol provider tetap terbuka sampai login SSH baru berhasil.
.env production memerlukan lebih banyak hal daripada konfigurasi development. Dokumentasi self-host mencantumkan persyaratan minimum berikut beserta secret.
NODE_ENV=production
RAKAZO_HOST=app.example.com
BETTER_AUTH_URL=https://app.example.com
WEB_ORIGIN=https://app.example.com
API_URL=https://app.example.com
SIGNUPS_ENABLED=true
SIGNUP_ALLOWLIST=you@example.com
SANDBOX_PROVIDER=e2b
AGENT_RUNTIME=pi
WAKEUP_DRIVER=graphile
DATA_DIR=/data
RAKAZO_DEPLOY_DIR=/srv/rakazo
RAKAZO_IMAGE_TAG=local
POSTGRES_PASSWORD=<random, URL-safe>
POSTGRES_APP_PASSWORD=<random, URL-safe>
BETTER_AUTH_SECRET=<random>
ENCRYPTION_KEY=<64 random hex characters>
SCREEN_PROXY_SECRET=<random>
E2B_API_KEY=<your key>
OPENROUTER_API_KEY=<your key>Arahkan A record ke server sebelum up pertama. Caddy meminta sertifikat untuk nama dalam RAKAZO_HOST. Nama tersebut harus mengarah ke server ini, dan port 80 untuk validasi HTTP atau port 443 untuk validasi TLS-ALPN harus dapat diakses dari luar. Kedua challenge aktif secara default. Karena itu, menutup port 80 saja tidak mencegah penerbitan sertifikat melalui port 443.
Atur SIGNUP_ALLOWLIST ke alamat Anda sendiri sejak awal. .env.example menyediakan SIGNUPS_ENABLED=true, dan kedua pengaturan tersebut dibaca dari environment setiap kali API dimulai. Dengan demikian, instance pada nama publik yang mengaktifkan pendaftaran tanpa allowlist akan menerima pendaftaran dari siapa pun yang menemukannya. Allowlist yang tidak kosong diterapkan setiap kali startup dan menggantikan daftar yang tersimpan. Pendaftaran melalui allowlist memerlukan verifikasi mailbox, termasuk untuk akun pertama. Karena itu, siapkan pengiriman email sebelum mendaftar. Tanpa email, dokumentasi menyarankan Anda memulai dengan SIGNUPS_ENABLED=false, lalu membuat akun menggunakan perintah bootstrap di sisi server yang disediakan. Perintah tersebut membuat akun terverifikasi biasa tanpa hak istimewa server. Terapkan allowlist terlebih dahulu. Anda dapat melonggarkannya nanti jika diperlukan. Jika Anda sudah menjalankan beberapa service pada server yang sama dan lebih memilih satu daftar pengguna daripada satu allowlist untuk setiap aplikasi, menempatkan instance Authentik di depannya memindahkan keputusan tersebut ke proxy. Namun, Authentik berada di depan akun Better Auth milik Rakazo, bukan menggantikannya.
Anggap docs/self-host.md dalam repositori sebagai sumber utama pengaturan production karena file tersebut berubah mengikuti kode, sedangkan panduan ini tidak. Karena Compose yang menjalankan prosesnya, aturan umum tetap berlaku. Dasar-dasar Docker Compose untuk VPS menjelaskan mengapa --env-file dan named volume menjadi semakin penting ketika stack dibiarkan berjalan selama berbulan-bulan.
Pencadangan
Postgres dan direktori data/ menyimpan data instance dalam pengaturan ini. Pemulihan juga memerlukan ENCRYPTION_KEY dan setiap content master key yang dikonfigurasi, jadi simpan salinannya di luar server.
./scripts/backup.sh
./scripts/restore.sh backups/BACKUP_TIMESTAMPbackup.sh melakukan dump Postgres dan mengarsipkan data/. restore.sh berfungsi pada stack Compose development, ke dalam database kosong dengan service aplikasi dihentikan, dan tidak membaca file backup production. Untuk mesin yang Anda andalkan, instal infra/compose/backup-prod.sh sebagai /usr/local/sbin/rakazo-backup dengan timer yang disediakan repository. Tool ini menulis dump terverifikasi dan arsip data aplikasi ke /var/backups/rakazo, menyimpan hingga tiga snapshot terverifikasi secara default, yang ditetapkan oleh RAKAZO_BACKUP_KEEP, dalam batas 50 GiB yang ditetapkan oleh RAKAZO_BACKUP_MAX_GB, serta menghapus snapshot parsial dan riwayat berlebih sebelum setiap eksekusi. Dengan demikian, rotasi berlangsung otomatis. Tool ini juga dapat mengenkripsi setiap backup dengan age ke public recipient yang Anda cantumkan dalam /etc/rakazo/backup.env, sehingga server menulis backup yang tidak dapat dibacanya sendiri. Buat key pair tersebut pada mesin yang Anda kendalikan dan simpan private key di luar server. Tanpa recipient, backup tetap dalam bentuk plaintext dan mencatat peringatan. Namun, setelah encrypted backup pertama dibuat, eksekusi tanpa recipient akan gagal kecuali Anda secara eksplisit mengizinkan plaintext dengan RAKAZO_BACKUP_ALLOW_PLAINTEXT=1. Backup yang berada pada disk yang sama dengan database bukanlah backup. Karena itu, salin backup ke luar server. Kemudian lakukan restore sekali pada server cadangan sebelum Anda membutuhkannya.
Penyebab kegagalan dan hal yang akan Anda lihat
pnpm db:migrate tidak dapat menjangkau database. Migrasi melaporkan bahwa database server di 127.0.0.1:5433 tidak dapat dijangkau. Container Postgres mungkin belum berjalan, sedang berjalan tetapi belum siap, atau dijalankan tanpa overlay docker-compose.postgres-host.yml, yang berfungsi mempublikasikan port 5433 ke host. Jalankan docker compose --env-file .env -f infra/compose/docker-compose.yml ps dan cari service postgres yang berstatus sehat, karena file compose memiliki health check yang berjalan setiap tiga detik. Jika container terus-menerus restart, baca log-nya: Compose stack yang dikunci versinya menolak berjalan pada volume Postgres 16 lama sampai volume tersebut dimigrasikan ke Postgres 18. docker compose ... down -v menghapus volume tersebut beserta datanya.
Port sudah digunakan. Menjalankan Postgres gagal dengan bind: address already in use jika ada proses lain yang menggunakan port 5433. Penyebab yang paling sering adalah Rakazo stack sebelumnya yang lupa Anda hentikan. sudo ss -lntp | grep 5433 menampilkan nama proses tersebut. Overlay membaca port host dari POSTGRES_HOST_PORT, sehingga Anda dapat memindahkannya selama DATABASE_URL dan DATABASE_MIGRATION_URL juga dipindahkan.
Bot tidak pernah mendapatkan komputer. Dengan SANDBOX_PROVIDER=docker dan tanpa image rakazo/computer:local, tidak ada komputer yang dapat dijalankan. docker image ls rakazo/computer menjawabnya dalam satu baris, dan pnpm sandbox:build memperbaikinya. Jika supervisor tidak dapat mengakses Docker socket, supervisor juga tidak dapat membuat container. Pesan error akan mencantumkan path-nya: permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock.
Perintah yang panjang berhenti di tengah jalan. .env.example menetapkan SANDBOX_COMMAND_TIMEOUT_MS=300000, sehingga satu perintah di dalam komputer bot dihentikan setelah lima menit. Tingkatkan batas ini untuk build yang lambat. Jangan langsung menganggap sandbox mengalami crash.
pnpm install mengalami kegagalan yang membingungkan. Periksa node -v terlebih dahulu. Workspace menetapkan ^22.22.2 || ^24.0.0 || >=26.0.0, sehingga 23.x, 25.x, dan versi 22.x apa pun sebelum 22.22.2 berada di luar rentang tersebut. .npmrc yang versinya dikunci menetapkan engine-strict=true, sehingga pnpm install menolak versi Node yang tidak didukung dengan error engine/version sebelum kode dependensi aplikasi dijalankan.
Sign-in berhasil secara lokal, tetapi tidak melalui domain. BETTER_AUTH_URL, WEB_ORIGIN, dan API_URL harus menggunakan public origin yang sama dengan address bar, termasuk scheme. http://127.0.0.1:5173 yang sudah usang pada salah satunya biasanya menyebabkan session tidak pernah dipertahankan.
Memperbarui checkout yang dikunci
Prosedur upgrade dalam dokumentasi self-host untuk stack Compose produksi yang dibangun dari checkout Anda cukup singkat: ambil source terbaru, lalu build ulang dan restart API, worker, serta aplikasi web. Migrasi dijalankan saat API start karena perintah start-nya menerapkan migrasi sebelum melayani request.
sudo /usr/local/sbin/rakazo-backup
git fetch --all --tags
git checkout NEW_COMMIT_SHA
export GIT_SHA=$(git rev-parse HEAD)
docker compose --env-file .env -f infra/compose/docker-compose.prod.yml \
up -d --wait --pull never --build api worker webBuat backup terlebih dahulu. Migrasi berjalan maju, dan versi beta tidak menyediakan jalur rollback yang dapat diandalkan. Jika checkout Anda lebih lama dari 30 August 2026, termasuk commit v0.1.0-beta, baca catatan dalam dokumentasi tentang migrasi 20260830200000_space_scope_names_and_user_credentials sebelum melakukan upgrade. Ini adalah cutover terkoordinasi. Hentikan API dan worker lama terlebih dahulu, lalu jalankan pemeriksaan batas privasi Space yang dijelaskan dalam dokumentasi. Jika melakukan upgrade dari checkout yang dibuat sebelum login aplikasi terpisah tersedia, tetapkan POSTGRES_APP_PASSWORD dalam .env sebelum melakukan rebuild. File production Compose tidak akan start tanpa nilai tersebut. File source-checkout dan production Compose juga menjalankan Postgres 18. Instalasi Postgres 16 yang sudah ada memerlukan prosedur infra/compose/upgrade-postgres.sh dalam dokumentasi sebelum dapat start pada layout baru. Baca commit antara SHA yang dikunci dan SHA baru sebelum menerapkannya. Project yang masih baru seperti ini dapat mengganti nama environment variable tanpa pemberitahuan, dan variable yang hilang akan terlihat sebagai service yang start lalu exit. Jika Anda masih mempertimbangkan apakah Rakazo memang tepat untuk dijalankan, ringkasan tentang agen AI self-hosted membahas pilihan lain dalam kategori ini serta biaya untuk mempertahankan masing-masing agen tetap berjalan.
FAQ
Dapatkah saya menjalankan Rakazo pada VPS 1 GB?
Tidak. Postgres, API, worker, supervisor sandbox, dan aplikasi web semuanya berjalan secara bersamaan. Dengan SANDBOX_PROVIDER=docker, komputer bot juga menambahkan sebuah container yang berisi desktop grafis, dengan X display dan proses Chrome terpisah untuk setiap bot aktif. Semua komponen tersebut berjalan dalam batas default sebesar 2 GB memory dan dua CPU. Dokumentasi self-host pada v0.3.5 tidak menyebutkan ukuran host. Anggap 4 GB sebagai batas minimum untuk control plane, dan gunakan ukuran yang lebih besar jika desktop berjalan pada mesin Anda.
Apakah provider desktop sandbox aman digunakan pada server?
Tidak. Dokumentasi self-host menyatakan bahwa desktop menjalankan perintah langsung pada host API dan worker. Artinya, bot berjalan sebagai user yang menjalankan proses tersebut dan dapat mengakses file serta credential milik user itu. Pada v0.3.5, API dan worker menolaknya di luar mode development dan test. Namun, server yang menjalankan pnpm dev berada dalam mode development dan menerimanya. Jangan gunakan konfigurasi ini pada server publik atau server bersama. Gunakan docker dengan memberikan Private Computer kepada bot jika bot tersebut tidak boleh berbagi file dengan bot lain di workspace. Gunakan e2b jika lebih dari satu orang melakukan sign-in.
Versi Rakazo mana yang harus saya install?
Per 9 November 2026, rilis terbaru adalah v0.8.0, yang diterbitkan pada 4 November 2026 dan ditandai sebagai Latest. Untuk mengikuti panduan ini, checkout commit v0.3.5 yang telah ditetapkan, yaitu f31e3c0699f086d663637c4107858c238a086fb3, bukan mengikuti main atau prerelease August v0.1.0-beta. Branch dapat berubah, dan tag dapat diarahkan ulang. Karena itu, keduanya tidak mengidentifikasi tree yang dapat Anda gunakan kembali. Catat commit tersebut, karena rollback hanya dapat dilakukan jika Anda mengetahui commit yang sebelumnya berfungsi.
Di mana saya harus menempatkan OpenRouter API key?
Tempatkan di .env sebagai OPENROUTER_API_KEY. Jangan pernah menempatkannya dalam file compose yang Anda commit. Kedua perintah compose dalam repository meneruskan --env-file .env, sehingga nilainya diteruskan ke container tanpa ditulis ke YAML yang dilacak oleh version control. Anda juga dapat membiarkannya kosong dan menghubungkan model dalam aplikasi setelah signup. Tetapkan batas pengeluaran untuk key tersebut di provider. Bot yang terjebak dalam loop akan terus memanggil model sampai ada sesuatu yang menghentikannya.
Apakah saya memerlukan nama domain dan TLS?
Untuk penggunaan selain pengujian awal, ya. File compose production menjalankan Caddy dan memperoleh sertifikat secara otomatis. Tetapkan RAKAZO_HOST ke hostname publik, lalu tetapkan BETTER_AUTH_URL, WEB_ORIGIN, dan API_URL ke origin HTTPS publik yang sama. Untuk pengujian awal, Anda dapat melewati penggunaan domain. Jalankan pnpm dev dan teruskan port 5173 melalui SSH, bukan memublikasikannya.