Jinsi ya kusakinisha Actual Budget kwenye VPS yako

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 kujiendesha wenyewe. Seva hii inajumuisha container moja, data volume moja, na jina moja la HTTPS. Kila kitu kinachohitajika kwa bajeti ya kawaida kinafanya kazi vizuri kwenye VPS ndogo zaidi unayoweza kukodisha, kwa sababu seva hiyo huhifadhi faili na kuzisawazisha (sync).

Ni muhimu kuelewa usanifu huu kabla ya kuandika chochote. 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 ndogo kukubaliana. Hii ndiyo sababu programu bado inafanya kazi seva inapokuwa imezimika, na ndiyo sababu kupoteza seva hakufanyi upoteze bajeti yako mradi mteja mmoja bado anashikilia nakala.

Kwa nini seva inahitaji HTTPS

Actual inahitaji HTTPS, na hii siyo utaratibu wa kawaida tu. Vivinjari hufichua Web Crypto API, kiolesura ambacho Actual hutumia kwa ajili ya usimbaji fiche wa mwisho-hadi-mwisho (end-to-end encryption), katika kile ambacho vipimo (specification) huita muktadha salama (secure context). Muktadha salama ni https:// au http://localhost. Pakia programu kutoka http://203.0.113.10:5006 kwenye kivinjari cha mashine nyingine na vipengele hivyo vitakosekana kabisa, kwa sababu kivinjari hakikukabidhi vipengele hivyo kwenye ukurasa. Programu rasmi za simu pia hukataa URL ya seva ya http:// isiyo na usalama.

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, kama mradi unavyoelekeza, 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/data

Andika /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

Maelezo matatu katika faili hiyo ni muhimu.

Image ni actualbudget/actual-server:latest, iliyochapishwa na mradi huo kwenye Docker Hub na kuwekwa kioo (mirrored) kwenye ghcr.io/actualbudget/actual. Kuna tag ya latest-alpine kwa mashine zenye nguvu ndogo.

Container huandika kila kitu chini ya /data. Ndani yake utapata server-files, ambayo huhifadhi account.sqlite yenye login na session tokens zako, na user-files, ambayo huhifadhi faili za bajeti zenyewe. Mount njia hiyo au docker compose pull inayofuata itafuta bajeti yako. ACTUAL_DATA_DIR inaweza kuihamisha, lakini chaguo-msingi ni sawa.

Port imechapishwa kwenye 127.0.0.1 pekee. 5006:5006 tupu huchapisha kwenye interface zote, na Docker huandika sheria zake mbele ya ufw, kwa hivyo programu ingekuwa wazi kwa Internet hata ukiwa na firewall ya deny-all. Mshangao huo unaelezwa katika kwa nini ports zilizochapishwa na Docker hupita ufw. Kufunga kwenye loopback inamaanisha kuwa reverse proxy iliyo kwenye seva hiyo hiyo pekee ndiyo inayoweza kuifikia.

Ianzishe:

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

Log hutulia pindi seva inaporipoti kuwa inasikiliza kwenye port 5006. Iangalie 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 container haiendeshi, na docker compose ps itaonyesha kuwa imetoka (exited). Sababu ya kawaida ni tatizo la ruhusa (permission) kwenye volume iliyowekwa (mounted), inayoonekana 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. Faili la bajeti hupakiwa zima wakati wa full sync. Nginx ina kikomo cha kawaida cha 1 MB kwa request body, kwa hivyo faili likivuka ukubwa huo, sync inafeli na kuonyesha 413 Request Entity Too Large kwenye log ya nginx wakati app inaonyesha kosa la jumla la sync. 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 kwenye meneja wa nenosiri wa Vaultwarden unayojiendeshea mwenyewe. Hakuna akaunti za watumiaji za kutengeneza. Seva ya Actual imeundwa kwa nenosiri moja pekee, kwa hivyo kushiriki bajeti kunamaanisha kushiriki nenosiri hilo.

Kisha tengeneza faili ya bajeti. Actual inakuuliza kama ungependa kuwezesha usimbaji fiche wa mwisho-hadi-mwisho (end-to-end encryption). Kubali, na seva itahifadhi data iliyosimbwa pekee, ambayo ndiyo njia sahihi ya kuhifadhi data ya kifedha kwenye mashine iliyokodishwa. Gharama yake ni halisi: nenosiri la usimbaji fiche halifiki kwenye seva, kwa hivyo ukilipoteza, faili hiyo itapotea na hakuna njia ya kuirejesha. Liandike mahali salama kabla ya kuendelea na skrini inayofuata.

Weka salio lako la kuanzia kulingana na takwimu za sasa za benki yako badala ya kuingiza historia ya miaka mingi. Mfumo wa bajeti ya bahasha (envelope budgeting) hufanya kazi kuanzia pesa uliyo nayo sasa, kwa hivyo kutokuwa na historia ya awali hakukugharimu chochote.

Kuingiza miamala

Hapa ndipo uaminifu unapokuwa muhimu zaidi kuliko shauku, kwa sababu mchakato wa kuingiza data ndiyo sababu kuu inayowafanya watu kuacha kutumia programu za bajeti wanazojiendeshea wenyewe (self-hosted).

Uingizaji wa mikono (manual entry) ndio msingi na hufanya kazi kila wakati. Kwa njia ya bahasha (envelope method), hii inaweza kusemekana ndiyo kiini cha mambo, kwa sababu kuandika ununuzi ndiko kunakokufanya uutambue.

Uingizaji wa faili (file import) hushughulikia kiasi kikubwa cha data. Actual husoma CSV, QIF, OFX na QFX, na kila benki hutoa angalau moja ya miundo hiyo. Ingiza data kwa kila akaunti kutoka kwenye skrini ya akaunti, panga safu wima mara moja, na Actual itakumbuka mpangilio huo kwa ajili ya akaunti hiyo.

Usawazishaji wa benki wa kiotomatiki (automatic bank sync) 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 kwa hadi taasisi 25 kufikia Julai 2026, na wengine wana bei tofauti.

Kuna mipaka miwili ya kukubali kabla ya kutegemea mfumo huu. Vitambulisho vya API hukaa kwenye seva na havijafunikwa na usimbaji fiche wa mwisho-hadi-mwisho (end-to-end encryption), kwa sababu seva lazima ivitumie. Na Actual haifanyi uchunguzi wa kiotomatiki (polling): kusawazisha ni kitufe unachobonyeza, si kazi ya nyuma (background job).

Hifadhi rudufu (backups), kwa sababu ni faili tu

Kila kitu unachokijali kipo chini ya /opt/actual/data. Hakuna hatua ya kusafirisha data (export) wala database dump ya kuandikia script.

Mtego mmoja ni SQLite. Kunakili account.sqlite wakati seva inaandika ndani yake kunaweza kunasa miamala ambayo haijakamilika, na hutajua hilo hadi utakapojaribu kufanya 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 start

Weka hilo kwenye ratiba kwa kutumia mbinu iliyo katika restic backups on a VPS, ambayo inaelezea usanidi wa repository, uhifadhi wa data (retention) na mazoezi ya restore. Fanya mazoezi ya restore. Hifadhi rudufu ambayo hujawahi kuifanyia restore ni kubahatisha tu.

Hifadhi rudufu za upande wa mteja (client-side backups) za Actual ni kitu tofauti na ni vyema kukifahamu. Kivinjari huhifadhi nakala za hivi karibuni za faili ya bajeti, zinazopatikana kutoka kwenye menyu ya faili, jambo ambalo linashughulikia "Nimefuta kategoria kimakosa" bila kugusa seva hata kidogo.

Kusasisha seva

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

Compose huunda upya container kwa kutumia image mpya na kuunganisha tena volume ileile, hivyo data inabaki. Sasisha clients pia. Inatarajiwa kwamba matoleo ya server na app yatabaki karibu. Client iliyo na toleo la zamani sana kuliko server inaweza kukataa kusawazisha na kuonyesha ujumbe wa kutolingana kwa matoleo. Tengeneza backup kabla ya kuruka matoleo makuu, kwa sababu migrations huendeshwa wakati wa kuanza kwa mara ya kwanza na hakuna njia ya kurudi kwenye toleo la awali. Actual huvumilia tag ya latest inayobadilika kwa sababu state yake ni directory ya files. App yenye database halisi haivumilii hali hiyo. kujiendeshea Chatwoot inaeleza tag zilizowekwa wazi na dump ya kabla ya uboreshaji ambayo utaratibu huo unahitaji.

Nini kinaharibika, na nini utaona

Programu inapakia lakini usawazishaji (sync) haukamiliki. Kagua logi ya ufikiaji ya nginx kwa ajili ya 413. Hiyo inamaanisha client_max_body_size imewekwa chini sana. 502 badala yake inamaanisha nginx inafanya kazi lakini kontena haifanyi kazi.

Chaguzi za usimbaji (encryption) hazipo, au programu ya simu inakataa URL. Ukurasa haupo katika muktadha salama. Upau wa anwani utaonyesha http:// pamoja na anwani ya IP au hostname ambayo si localhost. Rekebisha cheti badala ya kutafuta njia za mkato.

Ujumbe unasema faili ya bajeti haioani na toleo hili. Matoleo ya mteja (client) na seva yamepishana. Sasisha yote mawili kwenye toleo moja na uanzishe upya.

Kontena inajianzisha upya bila kikomo. Soma docker compose logs actual. Hitilafu ya ruhusa (permission error) kwenye /data inamaanisha saraka iliyopachikwa (mounted directory) haiwezi kuandikwa na mtumiaji wa kontena. Hitilafu ya "address-in-use" inamaanisha kuna kitu kingine kinachotumia port 5006 kwenye loopback.

Upakiaji wa kwanza unahisi kuwa polepole. Faili nzima ya bajeti hupakuliwa kwenye kivinjari unapoiifungua. 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. Usimbaji wa mwisho-hadi-mwisho (end-to-end encryption) wa Actual hutumia Web Crypto API ya kivinjari, na vivinjari hufungua API hiyo katika muktadha salama pekee, yaani https:// au http://localhost. Ukitumia HTTP ya kawaida kutoka kwa mashine nyingine, vipengele hivyo havipatikani, na programu rasmi za simu hukataa URL ya seva ya HTTP ya kawaida. Tumia cheti cha Let's Encrypt kwenye hostname halisi, au cheti kilichojitolea (self-signed) chenye ACTUAL_HTTPS_KEY na ACTUAL_HTTPS_CERT ikiwa unatumia kivinjari cha kompyuta pekee.

Je, Actual inaweza kuingiza miamala yangu ya benki kiotomatiki?

Inawezekana kupitia huduma ya wahusika wengine unayojisajili mwenyewe: SimpleFIN Bridge kwa Amerika Kaskazini, Enable Banking kwa Ulaya, Akahu kwa New Zealand, au Pluggy.ai kwa Brazil. GoCardless inatumika lakini haikubali akaunti mpya. Vitambulisho hivyo vya API hukaa kwenye seva yako na havijalindwa na usimbaji wa mwisho-hadi-mwisho. Usawazishaji (sync) pia hufanywa kwa mikono, kwa hivyo unabonyeza kitufe na hakuna kinachofanya kazi chinichini. Uingizaji wa faili za CSV, QIF, OFX na QFX 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 kusababisha nakala isiyo kamili. Hakuna kitu kingine kwenye seva kinachohifadhi hali ya programu (state).

Nini kitatokea nikipoteza nenosiri la usimbaji?

Faili haiwezi kurejeshwa. Nenosiri halifiki kwenye seva, na hiyo ndiyo maana kuu ya usimbaji wa mwisho-hadi-mwisho, kwa hivyo hakuna njia ya kuweka upya (reset) wala msaada wa kiufundi. Hifadhi nenosiri hilo kwenye kidhibiti cha manenosiri (password manager) mara tu unapounda faili, na uweke nakala mahali ambapo hakutegemei seva hii hii.

Actual Budget inahitaji rasilimali kiasi gani za seva?

Kidogo sana. Container hutoa faili tuli (static assets), na hesabu za bajeti hufanyika ndani ya kivinjari. vCPU moja iliyoshirikiwa na 1 GB ya RAM inatosha kuiendesha bila matatizo, na saraka ya data kwa ajili ya bajeti ya kaya yenye historia ya miaka kadhaa haizidi megabytes chache. Shinikizo kwenye diski hutokana na backups zako na containers nyingine, si kutoka kwa Actual. Ikiwa unapanga ukubwa wa seva itakayohudumia programu nzito zaidi, seva ya picha ndiyo inayoweka kiwango cha chini, kwa hivyo angalia kiasi cha RAM ambacho PhotoPrism na Immich zinahitaji hasa kabla ya kuchagua mpango.