Paano i-self-host ang Actual Budget sa VPS

Ang itinatayo mo

Ang Actual Budget ay isang self-hosted envelope budgeting app. Karaniwan itong pinipili ng mga naghahanap ng alternatibong YNAB na maaari nilang i-host mismo. Ang server ay binubuo ng isang container, isang data volume, at isang HTTPS name. Maayos na tatakbo rito ang lahat ng kailangan ng karaniwang budget sa pinakamaliit na VPS na maaari mong rentahan. Pangunahing nag-iimbak lang ng mga file at nagsi-sync ang server.

Mahalagang maunawaan ang architecture bago ka mag-type ng anuman. Ang budget mismo ay isang SQLite database na nasa loob ng iyong browser at ng bawat mobile app. Ang server na ii-install mo ay isang sync endpoint. Dito nito hinahawakan ang listahan ng mga account, mga budget file, at change log na ginagamit para magkasundo ang phone at laptop tungkol sa mga pagbabago. Kaya patuloy na gumagana ang app kapag down ang server. Kaya hindi mawawala ang budget mo kapag nawala ang server, basta may kopya pa nito ang kahit isang client.

Bakit kailangan ng server ng HTTPS

Humihingi ang Actual ng HTTPS, at hindi ito simpleng pormalidad. Ipinapakita lamang ng mga browser ang Web Crypto API, ang interface na ginagamit ng Actual para sa end-to-end encryption, kapag nasa tinatawag ng specification na secure context. Ang secure context ay https:// o http://localhost. Kapag binuksan ang app mula sa http://203.0.113.10:5006 gamit ang browser sa ibang machine, wala ang mga feature na iyon dahil hindi ipinasa ng browser ang mga ito sa page. Tinatanggihan din ng mga opisyal na mobile build ang plain na http:// server URL.

May dalawang praktikal na setup. Maglagay ng totoong certificate sa isang totoong domain name sa harap ng container, gaya ng ginagawa ng guide na ito. O bigyan ang server ng self-signed certificate gamit ang ACTUAL_HTTPS_KEY at ACTUAL_HTTPS_CERT, gaya ng nakadokumento sa project, at tanggapin ang browser warning sa bawat device. Limang minuto lang ang pagkuha ng libreng certificate mula sa Let's Encrypt, kaya piliin ang unang option.

I-install ang Actual Budget gamit ang Docker Compose

I-install muna ang Docker kung bagong setup ang server. Kung bago sa iyo ang syntax ng Compose file, ipinapaliwanag sa gabay na Mga pangunahing kaalaman sa Docker Compose para sa isang VPS ang mga field na gagamitin sa ibaba.

sudo install -d -m 755 /opt/actual
sudo install -d -m 700 /opt/actual/data

Isulat ang /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:/data

Mahalaga ang tatlong detalye sa file na iyon.

Ang image ay actualbudget/actual-server:latest, na inilabas ng project sa Docker Hub at naka-mirror sa ghcr.io/actualbudget/actual. May latest-alpine tag para sa mga low-power machine.

Isinusulat ng container ang lahat sa ilalim ng /data. Sa loob nito ay makikita ang server-files, na naglalaman ng account.sqlite kasama ang iyong login at session token, at ang user-files, na naglalaman mismo ng mga budget file. I-mount ang path na iyon; kung hindi, buburahin ng susunod na docker compose pull ang iyong budget. Maaaring ilipat ito ng ACTUAL_DATA_DIR, pero sapat na ang default.

Sa 127.0.0.1 lang naka-publish ang port. Kapag bare 5006:5006 ang ginamit, naka-publish ito sa lahat ng interface. Gumagawa ang Docker ng sarili nitong rules bago ang ufw, kaya magiging bukas sa internet ang app kahit may deny-all firewall. Ipinaliliwanag ang isyung ito sa kung bakit nilalampasan ng mga Docker published port ang ufw. Kapag naka-bind sa loopback, reverse proxy lang sa parehong server ang makaka-access dito.

Simulan ito:

cd /opt/actual
docker compose up --detach
docker compose logs -f actual

Titigil ang mga pagbabago sa log kapag iniulat ng server na nakikinig ito sa port 5006. Suriin muna ito locally bago baguhin ang DNS:

curl -fsS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:5006/

Ibig sabihin ng 200 ay nagse-serve ang app. Ibig sabihin ng curl: (7) Failed to connect ay hindi tumatakbo ang container, at ipapakita ng docker compose ps na nag-exit ito. Karaniwang sanhi nito ang problema sa permission sa mounted volume, na makikita bilang EACCES line sa log.

Maglagay ng certificate at totoong pangalan sa harap

Ituro ang isang A record sa VPS, budget.example.com, at hintaying mag-resolve ito. Pagkatapos, i-install ang nginx at mag-issue ng certificate. Saklaw nang buo ng gabay na Certbot sa Ubuntu 24.04 gamit ang nginx ang pag-isyu at ang renewal timer.

Ang proxy block:

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 ang linyang madalas nakakaligtaan. Buong ina-upload ang budget file kapag full sync. Naka-default ang Nginx sa 1 MB na request body, kaya kapag lumampas ang file sa limitasyong ito, mabibigo ang sync at lalabas ang 413 Request Entity Too Large sa nginx access log, habang generic sync error lang ang ipinapakita ng app. May hiwalay na limitasyon ang server: naka-default sa 20 ang ACTUAL_UPLOAD_FILE_SYNC_SIZE_LIMIT_MB at sa 50 ang ACTUAL_UPLOAD_SYNC_ENCRYPTED_FILE_SYNC_SIZE_LIMIT_MB, kaya itakda ang nginx limit na mas mataas sa limitasyong naaangkop sa iyo.

I-reload at subukan:

sudo nginx -t && sudo systemctl reload nginx
curl -fsS -o /dev/null -w '%{http_code}\n' https://budget.example.com/

Unang pagtakbo: ang password at ang una mong budget file

Buksan ang https://budget.example.com sa isang browser. Hihilingin sa unang screen na magtakda ka ng server password. Pinoprotektahan ng password na ito ang buong server, kaya gumawa ng mahaba at random na password at itago ito sa lugar na mahahanap mo ulit, gaya ng isang self-hosted na Vaultwarden password manager. Walang kailangang gawin na user account. Dinisenyo ang Actual server para sa iisang password, kaya ang pagbabahagi ng budget ay nangangahulugan ding pagbabahagi ng password na iyon.

Pagkatapos, gumawa ng budget file. Itatanong ng Actual kung ie-enable ang end-to-end encryption. Piliin ang yes; ciphertext lamang ang ise-save ng server, na tamang opsyon para sa financial data sa isang nirentahang machine. May kapalit ito: hindi ipinapadala sa server ang encryption password, kaya mawawala ang file kung makalimutan mo ito at walang reset na magagamit. Isulat ito bago ka mag-click lampas sa screen na iyon.

Itakda ang starting balances batay sa kasalukuyang figures ng iyong bangko sa halip na mag-import ng maraming taong history. Gumagana ang envelope budgeting mula sa perang mayroon ka ngayon, kaya walang mawawala sa iyo kung walang history.

Pag-import ng mga transaksyon

Dito mas mahalaga ang katapatan kaysa sa labis na optimismo, dahil ang paraan ng pag-import ang pangunahing dahilan kung bakit umaayaw ang mga tao sa self-hosted budgeting.

Ang manual na paglalagay ang batayang paraan at palagi itong gumagana. Para sa envelope method, masasabi ring ito ang pangunahing layunin, dahil ang pag-type ng isang pagbili ang nagpapaalala sa iyo na napansin mo ito.

Ang file import ang humahawak sa karamihan ng mga transaksyon. Nababasá ng Actual ang CSV, QIF, OFX at QFX, at bawat bangko ay nag-e-export ng kahit isa sa mga format na ito. Mag-import para sa bawat account mula sa screen ng account, i-map ang mga column nang isang beses, at tatandaan ng Actual ang layout na iyon para sa account.

May automatic bank sync, ngunit kailangan nito ng third-party service dahil hindi direktang makakonekta ang server sa mga bangko. Sinusuportahan ng Actual ang SimpleFIN Bridge para sa mga bangko sa North America, Enable Banking para sa Europe, Akahu para sa New Zealand, at Pluggy.ai para sa Brazil. Sinusuportahan pa rin ang GoCardless, ngunit hindi na ito tumatanggap ng mga bagong account. Ikaw mismo ang mag-sign up sa provider, gumawa ng mga credential, at idagdag ang mga ito sa server. Naniningil ang SimpleFIN Bridge ng 15 US dollars bawat taon para sa hanggang 25 institusyon noong July 2026, at iba ang presyo ng iba pang provider.

May dalawang limitasyong dapat mong tanggapin bago ka umasa rito. Nasa server ang mga API credential at hindi saklaw ng end-to-end encryption, dahil kailangang gamitin ng server ang mga ito. Hindi rin nagpo-poll ang Actual: isang button ang pinipindot mo para mag-sync, hindi ito background job.

Mga backup, dahil mga file lang ito

Lahat ng mahalaga sa iyo ay nasa ilalim ng /opt/actual/data. Walang export step at walang database dump na kailangang i-script.

Ang tanging bitag ay SQLite. Kung kokopyahin ang account.sqlite habang sinusulatan ito ng server, maaaring makuha ang hindi pa tapos na transaction. Malalaman mo lang ito kapag sinubukan mong mag-restore. Ihinto ang container sa ilang segundong kailangan para makumpleto ang pagkopya:

cd /opt/actual
docker compose stop
restic -r sftp:backup@backup.example.com:/srv/restic backup /opt/actual/data
docker compose start

Isama ito sa schedule gamit ang approach sa restic backups sa isang VPS, na sumasaklaw sa repository setup, retention at restore drill. Isagawa ang restore drill. Ang backup na hindi mo pa na-restore ay hula lamang.

Hiwalay na feature ang mga client-side backup ng Actual at mahalagang malaman ang tungkol dito. Pinananatili ng browser ang mga kamakailang kopya ng budget file. Maa-access ang mga ito mula sa file menu. Sapat ito para sa sitwasyong “aksidenteng nabura ko ang isang category” nang hindi ginagalaw ang server.

Pag-update ng server

cd /opt/actual
docker compose pull
docker compose up --detach

Muling ginagawa ng Compose ang container mula sa bagong image at ikinakabit muli ang parehong volume, kaya nananatili ang data. I-update rin ang mga client. Inaasahang magkalapit ang mga bersyon ng server at app, at maaaring tumangging mag-sync ang client na masyadong luma kumpara sa server dahil sa mensahe ng hindi pagtutugma ng bersyon. Gumawa ng backup bago lumipat sa mas bagong major version, dahil tumatakbo ang mga migration sa unang pagsisimula at walang paraan para mag-downgrade.

Ano ang nasisira at ano ang makikita mo

Naglo-load ang app pero hindi kailanman natatapos ang sync. Suriin ang nginx access log para sa 413. Ibig sabihin, masyadong mababa ang itinakda sa client_max_body_size. Samantala, ang 502 ay nangangahulugang gumagana ang nginx pero hindi ang container.

Walang mga opsyon sa encryption, o tinatanggihan ng mobile app ang URL. Hindi secure ang context ng page. Ipapakita sa address bar ang http:// na may IP address o hostname na hindi localhost. Ayusin ang certificate sa halip na gumamit ng workaround.

May mensaheng hindi compatible ang budget file sa bersyong ito. Hindi na magkatugma ang mga bersyon ng client at server. I-update ang dalawa sa parehong release, pagkatapos ay i-reload.

Paulit-ulit na nagre-restart ang container. Basahin ang docker compose logs actual. Ang permission error sa /data ay nangangahulugang hindi maaaring sulatan ng user ng container ang naka-mount na directory. Ang address-in-use error ay nangangahulugang may ibang gumagamit na ng 5006 sa loopback.

Mabagal ang unang pag-load. Ida-download sa browser ang buong budget file kapag binuksan mo ito. Isa itong malaking transfer, na susundan ng mga lokal na pagbasa. Hindi ito problema sa server sizing, at hindi ito mababago ng pagdagdag ng RAM.

FAQ

Kailangan ba ng Actual Budget ang HTTPS para gumana?

Oo, sa aktuwal na paggamit. Gumagamit ang end-to-end encryption ng Actual ng Web Crypto API ng browser. Inilalantad lang ito ng mga browser sa isang secure context, gaya ng https:// o http://localhost. Kapag plain HTTP mula sa ibang machine, hindi available ang mga feature na ito. Tinatanggihan din ng mga opisyal na mobile app ang URL ng plain HTTP server. Gumamit ng Let's Encrypt certificate sa isang totoong hostname. Maaari ka ring gumamit ng self-signed certificate na may ACTUAL_HTTPS_KEY at ACTUAL_HTTPS_CERT kung desktop browser lang ang palagi mong gagamitin.

Maaari bang awtomatikong i-import ng Actual ang mga transaksiyon ko sa bangko?

Sa pamamagitan lang ng third-party service na ikaw mismo ang sesign up: SimpleFIN Bridge sa North America, Enable Banking sa Europe, Akahu sa New Zealand, o Pluggy.ai sa Brazil. Supported ang GoCardless, pero hindi ito tumatanggap ng mga bagong account. Nasa server mo ang mga API credential na ito at hindi saklaw ng end-to-end encryption. Manual din ang sync. Pinipindot mo ang isang button, at walang nagpo-poll sa background. Hindi kailangan ng third party para sa pag-import ng CSV, QIF, OFX at QFX.

Ano mismo ang kailangan kong i-back up?

Ang naka-mount na data directory, na /opt/actual/data sa gabay na ito. Naglalaman ito ng server-files/account.sqlite para sa mga login at session, at user-files para sa mga budget file. Ihinto ang container bago kumopya. Maaaring makuha ng pagkopya sa isang live na SQLite database ang bahagyang naisulat pa lamang na data. Walang ibang state na nakaimbak sa server.

Ano ang mangyayari kung mawala ko ang encryption password?

Hindi na mare-recover ang file. Hindi kailanman ipinapadala ang password sa server. Ito ang pangunahing layunin ng end-to-end encryption. Kaya walang reset at walang support path. Itago ang password sa isang password manager kaagad pagkatapos mong gawin ang file. Magtabi rin ng kopya sa isang lugar na hindi umaasa sa server na ito.

Gaano karaming server resources ang kailangan ng Actual Budget?

Napakakaunti. Nagsisilbi ang container ng mga static asset at file. Sa browser isinasagawa ang mga pagkalkula ng budget. Kayang patakbuhin ito ng isang shared vCPU na may 1 GB ng RAM nang walang problema. Ang data directory para sa budget ng isang household na may ilang taon ng history ay karaniwang nasa ilang sampung megabyte lamang. Ang disk pressure ay nagmumula sa iyong mga backup at iba pang container, hindi sa Actual.