Cara Self-Host Actual Budget di VPS dengan Docker
Pelajari cara menjalankan Actual Budget di VPS dengan Docker Compose, termasuk volume data, HTTPS untuk Web Crypto API, file anggaran pertama, impor bank, dan backup.
Yang akan Anda bangun
Actual Budget adalah aplikasi penganggaran berbasis amplop yang di-host sendiri. Aplikasi ini biasanya menjadi pilihan ketika orang mencari alternatif YNAB yang dapat mereka host sendiri. Servernya terdiri atas satu container, satu volume data, dan satu nama HTTPS. Server terutama menyimpan file dan menyinkronkannya.
Arsitekturnya perlu dipahami sebelum Anda menjalankan perintah apa pun. Anggaran itu sendiri adalah database SQLite yang berada di dalam browser dan setiap aplikasi seluler Anda. Server yang akan Anda instal adalah endpoint sinkronisasi. Server ini menyimpan daftar akun, file anggaran, dan log perubahan yang memungkinkan ponsel serta laptop memiliki data yang sama. Karena itu, aplikasi tetap berfungsi saat server tidak aktif. Kehilangan server juga tidak menyebabkan anggaran hilang selama salah satu client masih menyimpan salinannya.
Mengapa server memerlukan HTTPS
Actual memerlukan HTTPS, dan ini bukan formalitas. Actual memerlukan fitur browser yang disebut SharedArrayBuffer agar dapat berjalan. Browser hanya mengaktifkan fitur tersebut jika halaman terisolasi lintas origin dalam konteks aman, sesuai istilah dalam spesifikasi. Konteks aman adalah https:// atau http://localhost. Jika Anda memuat aplikasi dari http://203.0.113.10:5006 di browser pada mesin lain, browser tidak pernah memberikan fitur tersebut kepada halaman, sehingga budget tidak dimuat. Ponsel tidak mendapat pengecualian. FAQ Actual menyebutkan bahwa aplikasi iOS resmi sedang dalam pengujian beta dan terhubung ke server Anda sendiri. FAQ tersebut juga menyebutkan bahwa belum ada aplikasi Android resmi. Jadi, pada sebagian besar ponsel, Anda menggunakan aplikasi web yang sama, memasangnya di layar utama sebagai Progressive Web App, dan aturan konteks aman yang sama tetap berlaku.
Jadi, ada dua konfigurasi yang dapat digunakan. Pasang sertifikat yang valid pada nama domain yang valid di depan container, seperti yang dilakukan panduan ini. Atau berikan sertifikat self-signed kepada server menggunakan ACTUAL_HTTPS_KEY dan ACTUAL_HTTPS_CERT, sesuai dokumentasi project, lalu terima peringatan browser pada setiap perangkat. Sertifikat gratis dari Let's Encrypt dapat diperoleh dalam lima menit, jadi gunakan opsi pertama.
Instal Actual Budget dengan Docker Compose
Instal Docker terlebih dahulu jika server masih baru. Jika sintaks file Compose masih baru bagi Anda, panduan dasar-dasar Docker Compose untuk VPS menjelaskan kolom yang digunakan di bawah ini.
sudo install -d -m 755 /opt/actual
sudo install -d -m 700 /opt/actual/dataTulis /opt/actual/docker-compose.yml:
services:
actual:
image: actualbudget/actual-server:latest
container_name: actual
restart: unless-stopped
ports:
- '127.0.0.1:5006:5006'
volumes:
- ./data:/dataAda tiga detail penting dalam file tersebut.
Image-nya adalah actualbudget/actual-server:latest, yang dipublikasikan oleh proyek ke Docker Hub dan dicerminkan di ghcr.io/actualbudget/actual. Tersedia tag latest-alpine untuk mesin berdaya rendah.
Container menulis semua data di bawah /data. Di dalamnya terdapat server-files, yang menyimpan account.sqlite berisi kredensial login dan token sesi Anda, serta user-files, yang menyimpan file anggaran. Mount path tersebut agar anggaran Anda tetap ada saat container diganti. ACTUAL_DATA_DIR dapat memindahkannya, tetapi nilai default sudah sesuai.
Port hanya dipublikasikan pada 127.0.0.1. Nilai 5006:5006 tanpa alamat mengikat port pada semua interface. Docker juga menulis aturannya sendiri sebelum aturan ufw, sehingga aplikasi tetap terbuka ke Internet meskipun firewall menolak semua koneksi. Hal yang tidak terduga ini dijelaskan dalam alasan port yang dipublikasikan Docker melewati ufw. Binding ke loopback berarti hanya reverse proxy pada server yang sama yang dapat mengaksesnya.
Mulai container:
cd /opt/actual
docker compose up --detach
docker compose logs -f actualLog akan stabil setelah server melaporkan bahwa server sedang listen pada port 5006. Periksa secara lokal sebelum mengubah DNS:
curl -fsS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:5006/Respons 200 berarti aplikasi sedang melayani permintaan. Respons curl: (7) Failed to connect berarti tidak ada proses yang menerima koneksi pada 127.0.0.1:5006. Jalankan docker compose ps --all, karena docker compose ps biasa hanya menampilkan container yang sedang berjalan. Jika container berstatus exited, penyebab umumnya adalah masalah permission pada volume yang di-mount. Masalah tersebut terlihat sebagai baris EACCES dalam log.
Pasang sertifikat dan nama domain yang valid di depan
Arahkan A record ke VPS, budget.example.com, lalu tunggu hingga resolusinya selesai. Setelah itu, instal nginx dan terbitkan sertifikat. Panduan Certbot di Ubuntu 24.04 dengan nginx menjelaskan penerbitan sertifikat dan timer perpanjangannya secara lengkap.
Blok proxy:
server {
listen 443 ssl;
http2 on;
server_name budget.example.com;
ssl_certificate /etc/letsencrypt/live/budget.example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/budget.example.com/privkey.pem;
client_max_body_size 100m;
location / {
proxy_pass http://127.0.0.1:5006;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}client_max_body_size adalah baris yang sering terlupakan. Sinkronisasi sehari-hari hanya mengirim perubahan Anda, tetapi seluruh file anggaran diunggah saat Anda pertama kali mendaftarkan anggaran ke server dan setiap kali Anda mengatur ulang sinkronisasi. Secara default, Nginx menetapkan ukuran body request sebesar 1 MB. Setelah ukuran file melebihi batas tersebut, seluruh unggahan gagal dengan 413 Request Entity Too Large di access log nginx, sedangkan aplikasi hanya menampilkan error sinkronisasi umum. Server memiliki batas terpisah: ACTUAL_UPLOAD_FILE_SYNC_SIZE_LIMIT_MB secara default bernilai 20 dan ACTUAL_UPLOAD_SYNC_ENCRYPTED_FILE_SYNC_SIZE_LIMIT_MB secara default bernilai 50. Jadi, tetapkan batas nginx di atas nilai yang berlaku bagi Anda.
Muat ulang dan uji:
sudo nginx -t && sudo systemctl reload nginx
curl -fsS -o /dev/null -w '%{http_code}\n' https://budget.example.com/Proses pertama: kata sandi dan file anggaran pertama Anda
Buka https://budget.example.com di browser. Layar pertama meminta Anda menetapkan kata sandi server. Kata sandi ini melindungi seluruh server, jadi buat kata sandi acak yang panjang dan simpan di tempat yang dapat Anda temukan kembali, misalnya di pengelola kata sandi Vaultwarden yang di-host sendiri. Secara bawaan, tidak ada akun pengguna yang perlu dibuat: server hanya memiliki satu kata sandi, sehingga berbagi anggaran berarti berbagi kata sandi tersebut. Login terpisah hanya dapat digunakan jika Anda menghubungkan penyedia OpenID, yang didukung Actual untuk konfigurasi multi-pengguna.
Selanjutnya, buat file anggaran. Buka Settings, lalu klik Enable encryption di bagian Encryption. Aktifkan fitur tersebut agar server hanya menyimpan ciphertext untuk data anggaran Anda. Ini merupakan pilihan yang tepat untuk data keuangan pada mesin sewaan. Konsekuensinya nyata: kata sandi enkripsi tidak pernah dikirim ke server. Jika Anda kehilangan kata sandi tersebut dan tidak memiliki salinan lokal anggaran, file itu akan hilang. Jika salinan lokal masih tersedia, Anda dapat mereset kunci enkripsi lalu melakukan sinkronisasi kembali. Catat kata sandi tersebut sebelum melewati layar itu.
Tetapkan saldo awal berdasarkan angka terkini dari bank Anda, bukan dengan mengimpor riwayat selama bertahun-tahun. Penganggaran berbasis envelope berjalan ke depan berdasarkan uang yang Anda miliki saat ini, sehingga tidak memiliki riwayat tidak menimbulkan masalah.
Memasukkan transaksi
Di sinilah kejujuran lebih penting daripada antusiasme, karena dukungan impor merupakan alasan utama orang berhenti menggunakan aplikasi budgeting self-hosted.
Input manual adalah dasar dan selalu berfungsi. Untuk metode amplop, input manual bisa dibilang merupakan inti metode tersebut, karena mengetikkan pembelian membuat Anda menyadarinya.
Impor file menangani sebagian besar transaksi. Actual dapat membaca CSV, QIF, OFX, QFX, dan CAMT. Impor transaksi per akun dari layar akun, lalu petakan kolom jika file tersebut berupa CSV.
Sinkronisasi bank otomatis tersedia, tetapi memerlukan layanan pihak ketiga karena server tidak dapat berkomunikasi dengan bank secara mandiri. Actual mendukung SimpleFIN Bridge untuk bank di Amerika Utara, Enable Banking untuk Eropa, Akahu untuk Selandia Baru, dan Pluggy.ai untuk Brasil. GoCardless masih didukung, tetapi tidak menerima akun baru. Anda harus mendaftar sendiri ke penyedia layanan, membuat kredensial, lalu menambahkannya ke server. Per Oktober 2026, SimpleFIN Bridge mengenakan biaya 15 US dollars per tahun ditambah pajak untuk hingga 25 institusi, sedangkan penyedia lainnya memiliki struktur harga yang berbeda.
Terima dua batasan berikut sebelum mengandalkan fitur ini. Kredensial API tersimpan di server dan tidak dilindungi oleh enkripsi end-to-end, karena server harus menggunakannya. Tidak ada sinkronisasi saat Actual ditutup: sinkronisasi otomatis dinonaktifkan secara default, dan setelah diaktifkan, sinkronisasi hanya berjalan selama aplikasi terbuka. Dengan demikian, server tidak pernah melakukan polling ke bank secara mandiri.
Backup, karena hanya berupa file
Semua data yang penting bagi Anda berada di /opt/actual/data. Tidak ada langkah ekspor dan tidak ada database dump yang perlu dibuatkan skrip.
Satu hal yang perlu diperhatikan adalah SQLite. Menyalin account.sqlite saat server sedang menulis ke dalamnya dapat menangkap transaksi yang belum selesai. Anda mungkin baru mengetahuinya saat mencoba melakukan restore. Hentikan container selama beberapa detik yang diperlukan untuk penyalinan:
cd /opt/actual
docker compose stop
restic -r sftp:backup@backup.example.com:/srv/restic backup /opt/actual/data
docker compose startJadwalkan proses tersebut menggunakan pendekatan pada backup restic pada VPS, yang mencakup penyiapan repository, retensi, dan uji restore. Jalankan uji restore. Backup yang belum pernah di-restore hanyalah perkiraan.
Fitur automatic backup bawaan Actual merupakan hal terpisah dan perlu diketahui, tetapi fitur ini hanya tersedia di aplikasi desktop. Actual menyimpan hingga 10 salinan terbaru file anggaran yang dapat diakses melalui File > Load Backup. Fitur ini menangani kasus “saya tidak sengaja menghapus kategori” tanpa menyentuh server sama sekali. Aplikasi web di browser tidak menyimpan salinan seperti itu. Jadi, jika semua orang di rumah menggunakan browser, jadwalkan backup server di atas. Anda juga dapat menyimpan backup anggaran secara manual melalui Settings > Export data.
Memperbarui server
cd /opt/actual
docker compose pull
docker compose up --detachCompose membuat ulang container dari image baru dan memasang kembali volume yang sama, sehingga data tetap tersedia. Perbarui client juga. Client yang lebih lama daripada data yang diterimanya akan berhenti menerapkan perubahan dan menampilkan pesan Update Required. Buat cadangan sebelum memperbarui, karena budget yang dibuka pada versi yang lebih baru mungkin tidak kompatibel dengan client yang lebih lama. Actual merekomendasikan tag floating latest, tetapi tetap menggunakan database SQLite, dan self-hosting Chatwoot menjelaskan tag yang dipatok serta dump sebelum upgrade yang diperlukan dalam pendekatan tersebut.
Hal yang gagal dan hal yang akan Anda lihat
Aplikasi terbuka, tetapi sinkronisasi tidak pernah selesai. Periksa log akses nginx untuk 413. Artinya, client_max_body_size disetel terlalu rendah. 502 justru berarti nginx tidak menerima respons yang dapat digunakan dari upstream. Penyebab yang paling sering adalah container berhenti atau tidak listening pada 5006. Karena itu, periksa docker compose ps --all dan log container terlebih dahulu.
Aplikasi tidak dapat dibuka pada perangkat lain, atau melaporkan bahwa SharedArrayBuffer tidak ada. Pastikan halaman menggunakan HTTPS dan menerima header isolasi lintas origin dari Actual. Jika bilah alamat menampilkan http:// dengan alamat IP atau hostname yang bukan localhost, perbaiki sertifikatnya, bukan mencari solusi sementara.
Muncul pesan bahwa file anggaran tidak kompatibel dengan versi ini. File tersebut telah dibuka menggunakan versi Actual yang lebih baru daripada client yang sedang Anda gunakan. Perbarui client setidaknya ke versi tersebut, atau pulihkan backup yang dibuat sebelum versi yang lebih baru mengubah file, lalu muat ulang.
Container melakukan restart berulang kali. Baca docker compose logs actual. Error izin pada /data berarti direktori yang di-mount tidak dapat ditulisi oleh user container. Error alamat sedang digunakan berarti ada proses lain yang sudah menggunakan 5006 pada loopback.
Pemuatan pertama terasa lambat. Seluruh file anggaran diunduh ke browser saat pertama kali dibuka pada suatu perangkat. Proses ini merupakan satu transfer besar, lalu pembacaan lokal. Ini bukan masalah kapasitas server, dan menambah RAM tidak akan mengubahnya.
FAQ
Apakah Actual Budget memerlukan HTTPS agar dapat berfungsi?
Ya, dalam praktiknya. Actual memerlukan fitur browser SharedArrayBuffer agar dapat berjalan, dan browser hanya mengaktifkannya dalam konteks aman, yaitu https:// atau http://localhost. Melalui HTTP biasa dari mesin lain, aplikasi tidak akan dimuat. Aplikasi iOS resmi masih dalam pengujian beta dan belum ada aplikasi Android resmi, sehingga sebagian besar ponsel menggunakan aplikasi web yang sama dan mengikuti aturan yang sama. (FAQ) Gunakan sertifikat Let's Encrypt pada hostname nyata, atau sertifikat self-signed dengan ACTUAL_HTTPS_KEY dan ACTUAL_HTTPS_CERT jika Anda dapat menerima peringatan sertifikat pada setiap perangkat.
Apakah Actual dapat mengimpor transaksi bank saya secara otomatis?
Hanya melalui layanan pihak ketiga yang Anda daftarkan sendiri: SimpleFIN Bridge di Amerika Utara, Enable Banking di Eropa, Akahu di Selandia Baru, atau Pluggy.ai di Brasil. GoCardless didukung, tetapi tidak menerima akun baru. Kredensial API tersebut tersimpan di server Anda dan tidak dilindungi oleh enkripsi end-to-end. Sinkronisasi otomatis dinonaktifkan secara default. Setelah diaktifkan, sinkronisasi hanya berjalan saat Actual terbuka, sehingga tidak ada proses yang melakukan polling di latar belakang pada server. Import CSV, QIF, OFX, QFX, dan CAMT sama sekali tidak memerlukan pihak ketiga.
Apa saja yang sebenarnya perlu saya cadangkan?
Direktori data yang di-mount, yaitu /opt/actual/data dalam panduan ini. Direktori tersebut berisi server-files/account.sqlite dengan data login dan sesi, serta user-files dengan file anggaran. Hentikan container sebelum menyalinnya karena menyalin database SQLite yang sedang aktif dapat menangkap penulisan yang belum lengkap. Tidak ada state lain yang tersimpan di server.
Apa yang terjadi jika saya kehilangan password enkripsi?
Jika Anda masih memiliki salinan lokal anggaran, Anda dapat mereset kunci enkripsi lalu melakukan sinkronisasi kembali. Jika password dan semua salinan lokal telah hilang, file terenkripsi tersebut tidak dapat dipulihkan. Simpan password di password manager segera setelah membuat file, dan simpan salinan di lokasi yang tidak bergantung pada server yang sama.
Berapa banyak sumber daya server yang diperlukan Actual Budget?
Sangat sedikit. Container menyajikan aset dan file statis, sedangkan penghitungan anggaran dilakukan di browser. Beban disk berasal dari backup dan container lain, bukan dari Actual. Jika Anda menentukan spesifikasi server yang juga harus menjalankan layanan yang lebih berat, server foto biasanya menjadi penentu kebutuhan minimum. Karena itu, periksa berapa RAM yang sebenarnya diperlukan PhotoPrism dan Immich sebelum memilih paket. Logika yang sama berlaku untuk media stack: transcoding menentukan paket, sedangkan frontend browser seperti Halcyon, yang mengubah library Jellyfin menjadi toko video tahun 90-an yang dapat dijelajahi membutuhkan sumber daya yang kira-kira sama sedikitnya dengan Actual.