Jinsi ya kusakinisha Actual Budget kwenye VPS yako
Jifunze kusakinisha Actual Budget kwa kutumia Docker Compose kwenye VPS. Pata mwongozo wa usanidi wa HTTPS, usimamizi wa data ya SQLite, uagizaji wa benki, na nakala za usalama.
Unachojenga
Actual Budget ni programu ya bajeti ya mfumo wa bahasha (envelope budgeting) inayojiendesha yenyewe (self-hosted), na ndiyo jibu la kawaida watu wanapotafta mbadala wa YNAB wanaoweza kujiendeshea wenyewe. Seva hii inajumuisha container moja, data volume moja, na jina moja la HTTPS. Seva hii huhifadhi faili na kuzisawazisha (sync).
Ni vyema kuelewa usanifu huu kabla ya kuanza kuandika amri yoyote. Bajeti yenyewe ni database ya SQLite inayokaa ndani ya kivinjari chako na ndani ya kila programu ya simu. Seva unayokaribia kusakinisha ni sehemu ya mwisho ya kusawazisha (sync endpoint): inashikilia orodha ya akaunti, faili za bajeti, na logi ya mabadiliko inayowezesha simu na kompyuta kupatana. Hii ndiyo sababu programu inaendelea kufanya kazi hata seva ikiwa imezimika, na ndiyo sababu kupoteza seva hakumaanishi kupoteza bajeti yako, mradi tu mteja mmoja (client) bado ana nakala.
Kwa nini seva inahitaji HTTPS
Actual inahitaji HTTPS, na hii siyo utaratibu wa kawaida tu. Actual inahitaji kipengele cha kivinjari kinachoitwa SharedArrayBuffer ili ifanye kazi, na vivinjari huwezesha kipengele hiki tu pale ukurasa unapokuwa umetengwa (cross-origin isolated) katika kile ambacho vipimo (specification) huita mazingira salama (secure context). Mazingira salama ni https:// au http://localhost. Pakia programu kutoka http://203.0.113.10:5006 kwenye kivinjari cha mashine nyingine na kivinjari hakitakabidhi kipengele hicho kwa ukurasa, hivyo bajeti haitapakia. Simu hazina ubaguzi wowote. FAQ ya Actual inasema kuwa programu rasmi ya iOS iko katika majaribio ya beta na huunganishwa kwenye seva yako mwenyewe, na kwamba bado hakuna programu rasmi ya Android, kwa hivyo kwenye simu nyingi unatumia programu ileile ya wavuti, iliyosakinishwa kwenye skrini ya nyumbani kama Progressive Web App, na kanuni ileile ya mazingira salama inatumika.
Kwa hivyo kuna usanidi mbili zinazofaa. Weka cheti halisi kwenye jina halisi mbele ya container, jambo ambalo mwongozo huu unafanya. Au ipatie seva cheti kilichojitolea (self-signed certificate) kwa kutumia ACTUAL_HTTPS_KEY na ACTUAL_HTTPS_CERT, jambo ambalo nyaraka za mradi zinaelezea, na ukubali onyo la kivinjari kwenye kila kifaa. Cheti cha bure kutoka Let's Encrypt huchukua dakika tano, kwa hivyo chagua chaguo la kwanza.
Sakinisha Actual Budget kwa kutumia Docker Compose
Sakinisha Docker kwanza ikiwa seva ni mpya. Ikiwa syntax ya faili ya Compose ni ngeni kwako, mwongozo wa misingi ya Docker Compose kwa VPS unaelezea sehemu zilizotumika hapa chini.
sudo install -d -m 755 /opt/actual
sudo install -d -m 700 /opt/actual/dataAndika /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:/dataMaelezo matatu katika faili hiyo ni muhimu.
Image inayotumika ni actualbudget/actual-server:latest, iliyochapishwa na mradi huu kwenye Docker Hub na kuwekwa kioo (mirrored) kwenye ghcr.io/actualbudget/actual. Kuna tag ya latest-alpine kwa mashine zenye nguvu ndogo ya kuchakata.
Container huandika kila kitu chini ya /data. Ndani yake utapata server-files, ambayo huhifadhi account.sqlite yenye taarifa zako za kuingia na token za session, na user-files, ambayo huhifadhi faili za bajeti zenyewe. Mount njia hiyo ili bajeti yako isipotee wakati wa kubadilisha container. ACTUAL_DATA_DIR inaweza kuhamisha njia hiyo, lakini chaguo-msingi ni sawa.
Port imechapishwa kwenye 127.0.0.1 pekee. 5006:5006 tupu huchapisha kwenye kila interface, na Docker huandika sheria zake mbele ya ufw, kwa hivyo programu ingekuwa wazi kwa Internet hata kama una firewall ya kuzuia kila kitu. Mshangao huo unaelezewa katika kwa nini ports zilizochapishwa na Docker hupita ufw. Kufunga kwenye loopback inamaanisha ni reverse proxy iliyo kwenye seva hiyo hiyo pekee ndiyo inayoweza kuifikia.
Ianzishe:
cd /opt/actual
docker compose up --detach
docker compose logs -f actualLog hutulia pindi seva inaporipoti kuwa inasikiliza kwenye port 5006. Ijaribu ndani ya seva kabla ya kugusa DNS:
curl -fsS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:5006/200 inamaanisha programu inafanya kazi. curl: (7) Failed to connect inamaanisha hakuna kilichokubali muunganisho kwenye 127.0.0.1:5006. Tekeleza docker compose ps --all, kwa sababu docker compose ps ya kawaida huorodhesha tu container zinazoendelea kufanya kazi. Ikiwa container inaonekana kama imetoka (exited), sababu ya kawaida ni tatizo la ruhusa (permission) kwenye volume iliyowekwa (mounted), ambayo huonekana kama mstari wa EACCES kwenye log.
Weka cheti na jina halisi mbele
Elekeza A record kwenye VPS, budget.example.com, na usubiri itatue (resolve). Kisha sakinisha nginx na utoe cheti. Mwongozo wa Certbot kwenye Ubuntu 24.04 na nginx unaelezea kikamilifu utoaji wa cheti na kipima muda cha kusasisha (renewal timer).
Kizuizi cha 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 ndiyo mstari ambao watu husahau. Usawazishaji wa kila siku hutuma mabadiliko yako pekee, lakini faili zima la bajeti hupakiwa (upload) unapojisajili kwa mara ya kwanza kwenye seva na tena kila unapoweka upya usawazishaji. Nginx ina kikomo cha kawaida cha 1 MB kwa request body, kwa hivyo faili likivuka ukubwa huo, upakiaji kamili hushindwa na kuleta 413 Request Entity Too Large kwenye log ya nginx, huku programu ikionyesha kosa la jumla la usawazishaji. Seva ina vikomo vyake tofauti: ACTUAL_UPLOAD_FILE_SYNC_SIZE_LIMIT_MB ina kikomo cha kawaida cha 20 na ACTUAL_UPLOAD_SYNC_ENCRYPTED_FILE_SYNC_SIZE_LIMIT_MB ina kikomo cha kawaida cha 50, kwa hivyo weka kikomo cha nginx juu ya kile kinachokuhusu.
Pakia upya na ujaribu:
sudo nginx -t && sudo systemctl reload nginx
curl -fsS -o /dev/null -w '%{http_code}\n' https://budget.example.com/Uendeshaji wa kwanza: nenosiri na faili yako ya kwanza ya bajeti
Fungua https://budget.example.com kwenye kivinjari. Skrini ya kwanza inakuomba uweke nenosiri la seva. Nenosiri hilo moja hulinda seva nzima, kwa hivyo tengeneza nenosiri refu na la kubahatisha, kisha ulihifadhi mahali ambapo utalipata tena, kama vile meneja wa nenosiri wa Vaultwarden unayojiendeshea mwenyewe. Kwa kawaida hakuna akaunti za watumiaji za kutengeneza: seva ina nenosiri moja, kwa hivyo kushiriki bajeti kunamaanisha kushiriki nenosiri hilo. Kuingia kwa akaunti tofauti kunawezekana tu ikiwa utaunganisha mtoa huduma wa OpenID, jambo ambalo Actual inaliunga mkono kwa usanidi wa watumiaji wengi.
Kisha tengeneza faili ya bajeti. Fungua Settings na ubofye Enable encryption katika sehemu ya Encryption. Iwezeshe na seva itahifadhi maandishi yaliyosimbwa (ciphertext) pekee kwa data yako ya bajeti, ambayo ndiyo njia sahihi ya kuhifadhi data ya kifedha kwenye mashine iliyokodishwa. Gharama yake ni ya kweli: nenosiri la usimbaji halifiki kwenye seva, kwa hivyo ukilipoteza na huna nakala ya ndani ya bajeti, faili hiyo itapotea. Ikiwa nakala ya ndani ipo, unaweza kuweka upya ufunguo wa usimbaji na kusawazisha tena. Liandike kabla ya kubofya ili kupita skrini hiyo.
Weka salio lako la kuanzia kulingana na takwimu za sasa za benki yako badala ya kuingiza historia ya miaka mingi. Uwekaji bajeti wa bahasha (envelope budgeting) hufanya kazi kuanzia pesa uliyo nayo sasa, kwa hivyo kutokuwa na historia hakukugharimu chochote.
Kuingiza miamala
Hapa ndipo uaminifu unapokuwa muhimu kuliko shauku, kwa sababu mchakato wa kuingiza data ndiyo sababu kuu inayowafanya watu kuacha kutumia programu ya bajeti wanayojiendeshea wenyewe (self-hosted).
Uingizaji wa mikono ndio msingi na hufanya kazi kila wakati. Kwa mbinu ya bahasha (envelope method), hii ndiyo hoja kuu, kwa sababu kuandika ununuzi ndiko kunakokufanya uutambue.
Uingizaji wa faili hushughulikia kiasi kikubwa cha data. Actual inasoma CSV, QIF, OFX, QFX na CAMT. Ingiza data kwa kila akaunti kutoka kwenye skrini ya akaunti, na uweke ramani ya safu wima (map the columns) wakati faili ni CSV.
Usawazishaji wa benki wa kiotomatiki upo, na unahitaji huduma ya wahusika wengine kwa sababu seva haiwezi kuwasiliana na benki zenyewe. Actual inasaidia SimpleFIN Bridge kwa benki za Amerika Kaskazini, Enable Banking kwa Ulaya, Akahu kwa New Zealand, na Pluggy.ai kwa Brazili. GoCardless bado inasaidiwa lakini haikubali akaunti mpya. Unajisajili na mtoa huduma mwenyewe, unatengeneza vitambulisho (credentials), na kuviongeza kwenye seva. SimpleFIN Bridge inatoza dola 15 za Marekani kwa mwaka pamoja na kodi kwa hadi taasisi 25 kufikia Oktoba 2026, na wengine wana bei tofauti.
Kuna mipaka miwili ya kukubali kabla ya kutegemea mfumo huu. Vitambulisho vya API hukaa kwenye seva na havijalindwa na end-to-end encryption, kwa sababu seva lazima ivitumie. Na hakuna kinachosawazishwa wakati Actual imefungwa: usawazishaji wa kiotomatiki umezimwa kwa chaguo-msingi, na ukishauwasha, hufanya kazi tu wakati programu imefunguliwa, kwa hivyo seva haichunguzi benki zako yenyewe.
Hifadhi rudufu (backups), kwa sababu ni faili tu
Kila kitu unachokijali kipo chini ya /opt/actual/data. Hakuna hatua ya kusafirisha (export) na hakuna database dump ya kuandikia script.
Mtego mmoja ni SQLite. Kunakili account.sqlite wakati seva inaandika ndani yake kunaweza kunasa transaction ambayo haijakamilika, na hutajua hilo hadi utakapojaribu kurejesha (restore). Simamisha container kwa sekunde chache ambazo nakala inachukua:
cd /opt/actual
docker compose stop
restic -r sftp:backup@backup.example.com:/srv/restic backup /opt/actual/data
docker compose startWeka hilo kwenye ratiba kwa kutumia mbinu iliyo kwenye restic backups on a VPS, ambayo inashughulikia usanidi wa repository, uhifadhi wa muda mrefu (retention) na mazoezi ya kurejesha. Fanya mazoezi ya kurejesha. Hifadhi rudufu ambayo hujawahi kuirejesha ni kubahatisha tu.
Hifadhi rudufu za kiotomatiki za Actual ni kitu tofauti na inafaa kuzijua, lakini zipo kwenye desktop app pekee. Inahifadhi hadi nakala 10 za hivi karibuni za faili ya bajeti, zinazopatikana kupitia File > Load Backup, jambo linaloshughulikia "nimefuta kategoria kimakosa" bila kugusa seva hata kidogo. Web app kwenye kivinjari haihifadhi nakala kama hizo, kwa hivyo ikiwa kila mtu nyumbani anatumia kivinjari, panga ratiba ya hifadhi rudufu ya seva kama ilivyo hapo juu. Unaweza pia kuhifadhi hifadhi rudufu ya bajeti kwa mikono kupitia Settings > Export data.
Kusasisha seva
cd /opt/actual
docker compose pull
docker compose up --detachCompose hutengeneza upya container kutoka kwenye image mpya na kuunganisha tena volume ileile, hivyo data haipotei. Sasisha pia clients. Client iliyo ya zamani kuliko data inayopokea huacha kutumia mabadiliko na kuonyesha ujumbe wa Update Required. Tengeneza backup kabla ya kusasisha, kwa sababu bajeti iliyofunguliwa katika toleo jipya inaweza kutooana na client ya zamani. Actual inapendekeza kutumia tag ya latest, lakini bado inatumia database za SQLite, na kujihostisha Chatwoot inaelezea hatua za kutumia tag zilizofungwa (pinned tags) na dump ya kabla ya upgrade ambayo mazoea haya yanahitaji.
Nini kinaharibika, na nini utaona
App inapakia lakini usawazishaji (sync) haukamiliki. Kagua log ya access ya nginx kwa ajili ya 413. Hiyo inamaanisha client_max_body_size imewekwa chini sana. 502 badala yake inamaanisha nginx haikupata jibu linaloweza kutumika kutoka kwa upstream. Mara nyingi hii hutokea kwa sababu container imesimama au haisikilizi kwenye 5006, kwa hivyo kagua docker compose ps --all na log ya container kabla ya kitu kingine chochote.
App haitapakia kwenye kifaa kingine, au inaripoti kuwa SharedArrayBuffer haipo. Hakikisha ukurasa unatumia HTTPS na unapokea header za cross-origin isolation kutoka kwa Actual. Ikiwa upau wa anwani unaonyesha http:// pamoja na anwani ya IP au hostname ambayo si localhost, rekebisha cheti badala ya kutafuta njia za mkato.
Ujumbe kwamba faili la bajeti halioani na toleo hili. Faili limefunguliwa katika toleo jipya zaidi la Actual kuliko mteja (client) unayotumia sasa. Sasisha mteja hadi toleo hilo au zaidi, au rudisha backup iliyochukuliwa kabla ya toleo jipya kugusa faili hilo, kisha pakia upya.
Container inajianzisha upya kwa mzunguko. Soma docker compose logs actual. Hitilafu ya ruhusa (permission error) kwenye /data inamaanisha saraka iliyopachikwa (mounted directory) haiwezi kuandikwa na mtumiaji wa container. Hitilafu ya address-in-use inamaanisha kuna kitu kingine kinachoshikilia 5006 kwenye loopback.
Upakiaji wa kwanza unaonekana kuwa wa polepole. Faili zima la bajeti hupakuliwa kwenye kivinjari unapolifungua kwa mara ya kwanza kwenye kifaa. Hiyo ni uhamishaji mmoja mkubwa, kisha usomaji wa ndani (local reads). Hili si tatizo la ukubwa wa seva, na kuongeza RAM hakutabadilisha hali hiyo.
FAQ
Je, Actual Budget inahitaji HTTPS ili kufanya kazi?
Ndiyo, kwa vitendo. Actual inahitaji kipengele cha SharedArrayBuffer cha kivinjari ili kufanya kazi, na vivinjari huwezesha kipengele hicho katika muktadha salama pekee, yaani https:// au http://localhost. Ukitumia HTTP ya kawaida kutoka kwenye mashine nyingine, programu haitapakia. Programu rasmi ya iOS iko kwenye majaribio ya beta na hakuna programu rasmi ya Android bado, kwa hivyo simu nyingi hutumia programu hiyo hiyo ya wavuti na hukutana na sheria hiyo hiyo. (FAQ) Tumia cheti cha Let's Encrypt kwenye hostname halisi, au cheti cha self-signed chenye ACTUAL_HTTPS_KEY na ACTUAL_HTTPS_CERT ikiwa unaweza kuvumilia onyo la cheti kwenye kila kifaa.
Je, Actual inaweza kuingiza miamala yangu ya benki kiotomatiki?
Inawezekana kupitia huduma ya wahusika wengine unayojisajili mwenyewe: SimpleFIN Bridge katika Amerika Kaskazini, Enable Banking katika Ulaya, Akahu katika New Zealand, au Pluggy.ai katika Brazil. GoCardless inatumika lakini haikubali akaunti mpya. Vitambulisho hivyo vya API hukaa kwenye seva yako na havijalindwa na end-to-end encryption. Usawazishaji wa kiotomatiki umezimwa kwa chaguo-msingi na, ukishawezeshwa, hufanya kazi tu wakati Actual imefunguliwa, kwa hivyo hakuna kinachofanya kazi chinichini kwenye seva. Uingizaji wa faili za CSV, QIF, OFX, QFX na CAMT hauhitaji mhusika mwingine yeyote.
Ni nini hasa ninachopaswa kuhifadhi (backup)?
Saraka ya data iliyopachikwa (mounted data directory), ambayo ni /opt/actual/data katika mwongozo huu. Ina server-files/account.sqlite yenye taarifa za kuingia na vipindi vya matumizi (sessions), na user-files yenye faili za bajeti. Simamisha container kabla ya kunakili, kwa sababu kunakili database ya SQLite inayotumika kunaweza kunasa data isiyokamilika. Hakuna kitu kingine kwenye seva kinachohifadhi hali (state).
Nini kitatokea nikipoteza nenosiri la encryption?
Ikiwa bado una nakala ya ndani ya bajeti, unaweza kuweka upya ufunguo wa encryption na kusawazisha tena. Ikiwa umepoteza nenosiri na kila nakala ya ndani, faili iliyosimbwa haiwezi kurejeshwa. Ihifadhi kwenye password manager wakati unapoitengeneza faili hiyo, na uweke nakala mahali pengine pasipotegemea seva hii hiyo.
Actual Budget inahitaji seva ya ukubwa gani?
Kidogo sana. Container hutoa rasilimali tuli (static assets) na faili, na hesabu za bajeti hufanyika kwenye kivinjari. Shinikizo la diski hutokana na backups zako na container zako nyingine, si kutoka kwa Actual. Ikiwa unapanga ukubwa wa seva inayopaswa kuendesha programu nzito zaidi kando yake, seva ya picha ndiyo inayoweka kiwango cha chini, kwa hivyo angalia kiasi cha RAM ambacho PhotoPrism na Immich zinahitaji hasa kabla ya kuchagua mpango. Mantiki hiyo hiyo inahusu media stack: transcoding ndiyo huamua mpango, wakati front end ya kivinjari kama Halcyon, inayobadilisha maktaba ya Jellyfin kuwa duka la video la miaka ya 90 inagharimu kidogo kama Actual.