اپنے VPS پر Actual Budget کیسے host کریں
Docker Compose سے VPS پر Actual Budget چلائیں: data volume محفوظ کریں، HTTPS کی browser شرط سمجھیں، پہلا budget بنائیں، bank imports اور backups ترتیب دیں۔
آپ کیا بنا رہے ہیں
Actual Budget ایک self-hosted envelope budgeting ایپ ہے۔ جب لوگ ایسا YNAB متبادل تلاش کرتے ہیں جسے وہ خود host کر سکیں، تو عموماً Actual Budget ہی منتخب کرتے ہیں۔ سرور ایک container، ایک data volume اور ایک HTTPS نام پر مشتمل ہے۔ سرور بنیادی طور پر files محفوظ کرتا اور انہیں sync کرتا ہے۔
کسی بھی command کو type کرنے سے پہلے architecture کو سمجھنا ضروری ہے۔ اصل budget ایک SQLite database ہے جو آپ کے browser اور ہر mobile app کے اندر موجود ہوتا ہے۔ جس سرور کو آپ اب install کرنے والے ہیں، وہ sync endpoint ہے۔ یہ account list، budget files اور change log محفوظ رکھتا ہے، تاکہ phone اور laptop ایک ہی حالت پر متفق رہیں۔ اسی وجہ سے server down ہونے پر بھی app کام کرتی رہتی ہے۔ اسی طرح، اگر کسی ایک client کے پاس copy موجود ہو تو server ضائع ہونے سے آپ کا budget ضائع نہیں ہوتا۔
سرور کو HTTPS کی ضرورت کیوں ہے
Actual کو HTTPS درکار ہے، اور یہ محض رسمی تقاضا نہیں ہے۔ Actual کو ایک browser feature درکار ہے جسے SharedArrayBuffer کہا جاتا ہے، اور browsers اسے اسی وقت فعال کرتے ہیں جب صفحہ specification کی اصطلاح میں secure context کے اندر cross-origin isolated ہو۔ Secure context https:// یا http://localhost ہوتا ہے۔ کسی دوسری مشین پر موجود browser میں http://203.0.113.10:5006 سے app load کریں تو browser یہ feature صفحے کو فراہم نہیں کرتا، اس لیے budget load نہیں ہوتا۔ Phones کے لیے اس میں کوئی استثنا نہیں ہے۔ Actual کے FAQ کے مطابق official iOS app beta testing میں ہے اور آپ کے اپنے server سے connect ہوتی ہے، جبکہ ابھی کوئی official Android app موجود نہیں ہے۔ اس لیے زیادہ تر phones پر آپ وہی web app استعمال کرتے ہیں، اسے Progressive Web App کے طور پر home screen پر install کرتے ہیں، اور secure-context کا وہی اصول لاگو ہوتا ہے۔
اس لیے دو قابلِ عمل setups ہیں۔ Container کے سامنے کسی حقیقی name پر حقیقی certificate لگائیں، جیسا کہ یہ guide کرتی ہے۔ یا ACTUAL_HTTPS_KEY اور ACTUAL_HTTPS_CERT کے ساتھ server کو self-signed certificate دیں، جیسا کہ project کی documentation میں بتایا گیا ہے، اور ہر device پر browser warning قبول کریں۔ Let's Encrypt کا مفت certificate پانچ منٹ میں حاصل ہو جاتا ہے، اس لیے پہلا option منتخب کریں۔
Docker Compose کے ساتھ Actual Budget انسٹال کریں
اگر سرور نیا ہے تو پہلے Docker انسٹال کریں۔ اگر Compose فائل کا syntax آپ کے لیے نیا ہے تو VPS کے لیے Docker Compose کی بنیادی باتیں گائیڈ میں ذیل میں استعمال ہونے والے fields کی وضاحت موجود ہے۔
sudo install -d -m 755 /opt/actual
sudo install -d -m 700 /opt/actual/data/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اس فائل میں تین تفصیلات اہم ہیں۔
image actualbudget/actual-server:latest ہے، جسے project نے Docker Hub پر publish کیا ہے اور ghcr.io/actualbudget/actual پر mirror کیا گیا ہے۔ کم توانائی استعمال کرنے والی machines کے لیے latest-alpine tag موجود ہے۔
container تمام data /data کے تحت لکھتا ہے۔ اس کے اندر server-files موجود ہے، جس میں آپ کے login اور session tokens رکھنے والی account.sqlite شامل ہے، اور user-files موجود ہے، جس میں خود budget files رکھی جاتی ہیں۔ اس path کو mount کریں تاکہ container تبدیل ہونے کے بعد بھی آپ کا budget محفوظ رہے۔ ACTUAL_DATA_DIR اسے تبدیل کر سکتا ہے، لیکن default کافی ہے۔
port صرف 127.0.0.1 پر publish کیا گیا ہے۔ سادہ 5006:5006 ہر interface پر publish کرتا ہے، اور Docker اپنے rules کو ufw سے پہلے لکھتا ہے۔ اس لیے deny-all firewall کے باوجود app internet کے لیے کھلی رہتی۔ اس غیر متوقع رویے کی وضاحت Docker کے published ports ufw کو bypass کیوں کرتے ہیں میں موجود ہے۔ loopback پر bind کرنے سے صرف اسی server پر موجود reverse proxy اس تک پہنچ سکتا ہے۔
اسے start کریں:
cd /opt/actual
docker compose up --detach
docker compose logs -f actualجب server port 5006 پر listening کی اطلاع دیتا ہے تو log مستحکم ہو جاتا ہے۔ DNS تبدیل کرنے سے پہلے اسے مقامی طور پر check کریں:
curl -fsS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:5006/200 کا مطلب ہے کہ app requests serve کر رہی ہے۔ curl: (7) Failed to connect کا مطلب ہے کہ 127.0.0.1:5006 پر کسی process نے connection قبول نہیں کیا۔ docker compose ps --all چلائیں، کیونکہ سادہ docker compose ps صرف running containers دکھاتا ہے۔ اگر container exited حالت میں دکھائی دے تو عام وجہ mounted volume کا permission مسئلہ ہوتی ہے، جو log میں EACCES line کے طور پر نظر آتا ہے۔
سامنے certificate اور حقیقی نام لگائیں
VPS کی طرف A record point کریں، budget.example.com، اور اس کے resolve ہونے کا انتظار کریں۔ پھر nginx install کریں اور certificate issue کریں۔ Ubuntu 24.04 پر nginx کے ساتھ Certbot گائیڈ میں issuance اور renewal timer کی مکمل وضاحت موجود ہے۔
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 وہ line ہے جسے لوگ بھول جاتے ہیں۔ روزمرہ sync میں صرف آپ کی تبدیلیاں بھیجی جاتی ہیں، لیکن جب آپ پہلی بار server کے ساتھ budget register کرتے ہیں اور جب بھی sync reset کرتے ہیں، پوری budget file upload ہوتی ہے۔ nginx میں request body کی default حد 1 MB ہوتی ہے۔ اس لیے file اس حد سے بڑی ہو جائے تو یہ مکمل uploads ناکام ہو جاتے ہیں۔ nginx access log میں 413 Request Entity Too Large دکھائی دیتا ہے، جبکہ app صرف عمومی sync error دکھاتی ہے۔ Server کی اپنی الگ limits ہیں: ACTUAL_UPLOAD_FILE_SYNC_SIZE_LIMIT_MB کی default قدر 20 اور ACTUAL_UPLOAD_SYNC_ENCRYPTED_FILE_SYNC_SIZE_LIMIT_MB کی default قدر 50 ہے۔ اس لیے nginx کی limit اپنے لیے لاگو ہونے والی حد سے زیادہ مقرر کریں۔
Reload کریں اور test کریں:
sudo nginx -t && sudo systemctl reload nginx
curl -fsS -o /dev/null -w '%{http_code}\n' https://budget.example.com/پہلی بار چلانا: پاس ورڈ اور پہلی بجٹ فائل
https://budget.example.com کو browser میں کھولیں۔ پہلی screen آپ سے server password مقرر کرنے کو کہتی ہے۔ یہ واحد password پورے server کی حفاظت کرتا ہے، اس لیے ایک طویل اور random password بنائیں اور اسے ایسی جگہ محفوظ کریں جہاں آپ اسے دوبارہ تلاش کر سکیں، مثلاً خود میزبان Vaultwarden password manager میں۔ ابتدائی طور پر کوئی user accounts بنانے کی ضرورت نہیں ہوتی: server میں صرف ایک password ہوتا ہے، اس لیے budget share کرنے کا مطلب بھی وہ password share کرنا ہے۔ الگ logins صرف اسی صورت ممکن ہیں جب آپ OpenID provider connect کریں، جسے Actual multi-user setups کے لیے support کرتا ہے۔
پھر ایک budget file بنائیں۔ Settings کھولیں اور Encryption section میں Enable encryption پر click کریں۔ اسے enable کرنے کے بعد server آپ کے budget data کے لیے صرف ciphertext محفوظ کرتا ہے۔ کرائے کی machine پر financial data کے لیے یہی درست طریقہ ہے۔ اس کی حقیقی لاگت بھی ہے: encryption password کبھی server تک نہیں پہنچتا، اس لیے اگر آپ اسے کھو دیں اور budget کی کوئی local copy موجود نہ ہو تو file ختم ہو جاتی ہے۔ اگر local copy محفوظ ہو تو آپ encryption key reset کرکے دوبارہ sync کر سکتے ہیں۔ اس screen سے آگے بڑھنے سے پہلے اسے لکھ کر محفوظ کریں۔
اپنے starting balances بینک کے موجودہ figures کے مطابق مقرر کریں، برسوں کی history import نہ کریں۔ Envelope budgeting آپ کے موجودہ پیسوں سے آگے کا حساب چلاتا ہے، اس لیے خالی history سے آپ کا کچھ ضائع نہیں ہوتا۔
ٹرانزیکشنز درج کرنا
یہاں جوش سے زیادہ دیانت داری اہم ہے، کیونکہ import کا طریقہ وہ بنیادی وجہ ہے جس کی بنا پر لوگ self-hosted budgeting سے بددل ہو جاتے ہیں۔
دستی اندراج بنیادی طریقہ ہے اور یہ ہمیشہ کام کرتا ہے۔ envelope method میں یہ طریقہ کسی حد تک اصل مقصد ہی ہے، کیونکہ خریداری کی تفصیل ٹائپ کرنے سے آپ اس پر توجہ دیتے ہیں۔
فائل import بڑی تعداد میں ٹرانزیکشنز سنبھال لیتا ہے۔ Actual، CSV، QIF، OFX، QFX اور CAMT پڑھتا ہے۔ account screen سے ہر account کے لیے الگ import کریں، اور اگر فائل CSV ہو تو columns map کریں۔
خودکار bank sync موجود ہے، لیکن اس کے لیے third-party service درکار ہوتی ہے، کیونکہ server خود بینکوں سے رابطہ نہیں کر سکتا۔ Actual شمالی امریکا کے بینکوں کے لیے SimpleFIN Bridge، یورپ کے لیے Enable Banking، نیوزی لینڈ کے لیے Akahu، اور برازیل کے لیے Pluggy.ai کو support کرتا ہے۔ GoCardless اب بھی supported ہے، لیکن یہ نئے accounts قبول نہیں کر رہا۔ آپ provider کے ساتھ خود sign up کریں، credentials generate کریں، اور انہیں server میں شامل کریں۔ October 2026 تک SimpleFIN Bridge، زیادہ سے زیادہ 25 institutions کے لیے، tax کے علاوہ، ہر سال 15 US dollars وصول کرتا ہے۔ دیگر providers کی قیمتیں مختلف ہیں۔
اس پر انحصار کرنے سے پہلے دو حدود تسلیم کریں۔ API credentials server پر موجود رہتے ہیں اور end-to-end encryption کے دائرے میں نہیں آتے، کیونکہ server کو انہیں استعمال کرنا ہوتا ہے۔ دوسری بات یہ ہے کہ Actual بند ہونے پر کچھ بھی sync نہیں ہوتا: automatic syncing default طور پر بند ہے، اور اسے فعال کرنے کے بعد بھی یہ صرف اس وقت چلتی ہے جب app کھلی ہو۔ اس لیے server خود آپ کے بینکوں کو poll نہیں کرتا۔
بیک اپس، کیونکہ یہ صرف فائلیں ہیں
آپ کے لیے اہم تمام ڈیٹا /opt/actual/data کے اندر موجود ہے۔ کسی export مرحلے یا script کے ذریعے database dump کی ضرورت نہیں ہے۔
واحد اہم احتیاط SQLite ہے۔ سرور کے اس میں لکھنے کے دوران account.sqlite کو copy کرنے سے نامکمل transaction محفوظ ہو سکتی ہے، اور اس کا پتا restore کی کوشش تک نہیں چلتا۔ Copy مکمل ہونے میں جتنے چند سیکنڈ لگتے ہیں، اتنی دیر کے لیے container روک دیں:
cd /opt/actual
docker compose stop
restic -r sftp:backup@backup.example.com:/srv/restic backup /opt/actual/data
docker compose startاسے VPS پر restic backups کے طریقے سے schedule کریں۔ اس میں repository setup، retention اور restore drill شامل ہیں۔ Restore drill ضرور چلائیں۔ ایسا backup جسے آپ نے کبھی restore نہ کیا ہو، صرف ایک اندازہ ہے۔
Actual کے اپنے automatic backups الگ خصوصیت ہیں اور ان کے بارے میں جاننا مفید ہے، لیکن یہ صرف desktop app میں دستیاب ہیں۔ یہ budget file کی حالیہ 10 copies تک محفوظ رکھتا ہے۔ یہ copies File > Load Backup سے دستیاب ہوتی ہیں۔ اس سے "میں نے غلطی سے کوئی category delete کر دی" جیسی صورت حال server کو بالکل متاثر کیے بغیر حل ہو جاتی ہے۔ Browser میں چلنے والی web app ایسی copies محفوظ نہیں رکھتی۔ اس لیے اگر گھر میں سب لوگ browser استعمال کرتے ہیں تو اوپر بیان کردہ server backup schedule کریں۔ آپ Settings > Export data سے budget کا manual backup بھی محفوظ کر سکتے ہیں۔
سرور کو اپ ڈیٹ کرنا
cd /opt/actual
docker compose pull
docker compose up --detachCompose نئے image سے container دوبارہ بناتا ہے اور وہی volume دوبارہ منسلک کرتا ہے، اس لیے data برقرار رہتا ہے۔ Clients کو بھی اپ ڈیٹ کریں۔ اگر client موصول ہونے والے data سے پرانا ہو تو وہ تبدیلیاں لاگو کرنا بند کر دیتا ہے اور Update Required کا پیغام دکھاتا ہے۔ اپ ڈیٹ سے پہلے backup لیں، کیونکہ نئے version میں کھولا گیا budget پرانے client کے ساتھ incompatible ہو سکتا ہے۔ Actual floating latest tag استعمال کرنے کی سفارش کرتا ہے، لیکن یہ اب بھی SQLite databases استعمال کرتا ہے، اور Chatwoot کی self-hosting میں pinned tags اور pre-upgrade dump کے اس معمول کی وضاحت کی گئی ہے۔
کیا خراب ہوتا ہے، اور آپ کو کیا نظر آئے گا
ایپ کھلتی ہے، لیکن sync کبھی مکمل نہیں ہوتی۔ nginx access log میں 413 دیکھیں۔ اس کا مطلب ہے کہ client_max_body_size بہت کم مقرر کیا گیا ہے۔ اس کے برعکس 502 کا مطلب ہے کہ nginx کو upstream سے قابلِ استعمال response نہیں ملا۔ اکثر وجہ یہ ہوتی ہے کہ container بند ہے یا 5006 پر listen نہیں کر رہا۔ اس لیے پہلے docker compose ps --all اور container log چیک کریں۔
ایپ دوسرے آلے پر لوڈ نہیں ہوتی، یا بتاتی ہے کہ SharedArrayBuffer موجود نہیں ہے۔ تصدیق کریں کہ صفحہ HTTPS استعمال کرتا ہے اور اسے Actual کی طرف سے cross-origin isolation headers موصول ہو رہے ہیں۔ اگر address bar میں IP address یا ایسا hostname ہو جو localhost نہیں ہے اور اس کے ساتھ http:// دکھائی دے، تو workaround کرنے کے بجائے certificate درست کریں۔
یہ پیغام کہ budget file اس version کے ساتھ compatible نہیں ہے۔ یہ file Actual کے اس client سے زیادہ نئے version میں کھولی گئی ہے جسے آپ اس وقت استعمال کر رہے ہیں۔ client کو کم از کم اسی version تک update کریں، یا newer version کے ذریعے file میں تبدیلی سے پہلے لیا گیا backup restore کریں، پھر reload کریں۔
Container مسلسل restart loop میں ہے۔ docker compose logs actual پڑھیں۔ /data پر permission error کا مطلب ہے کہ mounted directory، container کے user کے لیے writable نہیں ہے۔ address-in-use error کا مطلب ہے کہ کوئی اور process پہلے ہی loopback پر 5006 پر listening کر رہا ہے۔
پہلی بار لوڈ ہونے میں تاخیر محسوس ہوتی ہے۔ کسی device پر پہلی بار budget file کھولنے پر پوری file browser میں download ہوتی ہے۔ یہ ایک بڑی transfer ہے، جس کے بعد مقامی reads ہوتی ہیں۔ یہ server sizing کا مسئلہ نہیں ہے، اور RAM بڑھانے سے اس میں تبدیلی نہیں آئے گی۔
FAQ
کیا Actual Budget کے کام کرنے کے لیے HTTPS ضروری ہے؟
عملی طور پر، ہاں۔ Actual کو چلنے کے لیے براؤزر کا SharedArrayBuffer فیچر درکار ہوتا ہے، اور براؤزر اسے صرف secure context میں فعال کرتے ہیں، یعنی https:// یا http://localhost۔ کسی دوسرے machine سے plain HTTP کے ذریعے ایپ load نہیں ہوگی۔ سرکاری iOS ایپ beta testing میں ہے، اور ابھی کوئی سرکاری Android ایپ موجود نہیں؛ اس لیے زیادہ تر phones یہی web app استعمال کرتے ہیں اور اسی rule کے تابع ہوتے ہیں۔ (FAQ) کسی حقیقی hostname پر Let's Encrypt certificate استعمال کریں، یا ACTUAL_HTTPS_KEY اور ACTUAL_HTTPS_CERT کے ساتھ self-signed certificate استعمال کریں، بشرطیکہ ہر device پر certificate warning قبول کر سکتے ہوں۔
کیا Actual میرے bank transactions خودکار طور پر import کر سکتا ہے؟
صرف کسی third-party service کے ذریعے، جس کے لیے آپ خود sign up کریں: North America میں SimpleFIN Bridge، Europe میں Enable Banking، New Zealand میں Akahu، یا Brazil میں Pluggy.ai۔ GoCardless supported ہے، لیکن نئے accounts قبول نہیں کر رہا۔ ان API credentials کو آپ کے server پر رکھا جاتا ہے اور یہ end-to-end encryption کے دائرے میں نہیں آتے۔ Automatic syncing by default بند ہوتی ہے اور فعال کرنے کے بعد صرف اس وقت چلتی ہے جب Actual کھلا ہو؛ اس لیے server پر پس منظر میں کوئی polling نہیں ہوتی۔ CSV، QIF، OFX، QFX اور CAMT import کے لیے کسی third party کی ضرورت نہیں۔
مجھے بالکل کس چیز کا backup لینا ہوگا؟
Mounted data directory کا، جو اس guide میں /opt/actual/data ہے۔ اس میں logins اور sessions کے ساتھ server-files/account.sqlite، اور budget files کے ساتھ user-files موجود ہے۔ Copy بنانے سے پہلے container کو stop کریں، کیونکہ live SQLite database کو copy کرنے سے partial write محفوظ ہو سکتی ہے۔ Server پر کوئی دوسری چیز state محفوظ نہیں کرتی۔
اگر encryption password ضائع ہو جائے تو کیا ہوگا؟
اگر budget کی local copy اب بھی موجود ہے تو آپ encryption key reset کر کے دوبارہ sync کر سکتے ہیں۔ اگر password اور تمام local copies دونوں ضائع ہو جائیں تو encrypted file recover نہیں کی جا سکتی۔ File بناتے ہی اسے password manager میں محفوظ کریں، اور ایک copy ایسی جگہ رکھیں جو اسی server پر منحصر نہ ہو۔
Actual Budget کو کتنے server resources درکار ہیں؟
بہت کم۔ Container static assets اور files serve کرتا ہے، جبکہ budget calculations browser میں ہوتی ہیں۔ Disk pressure آپ کے backups اور دوسرے containers سے آتا ہے، Actual سے نہیں۔ اگر آپ ایسے box کی capacity طے کر رہے ہیں جس پر اس کے ساتھ زیادہ resources استعمال کرنے والی کوئی چیز بھی چلنی ہو، تو عموماً photo server minimum capacity طے کرتا ہے؛ اس لیے plan منتخب کرنے سے پہلے یہ دیکھیں کہ PhotoPrism اور Immich کو حقیقت میں کتنی RAM درکار ہے۔ یہی منطق media stack پر بھی لاگو ہوتی ہے: plan کا فیصلہ transcoding کرتا ہے، جبکہ Halcyon، جو Jellyfin library کو 90s کی ایسی video store میں بدل دیتا ہے جہاں browser کے ذریعے گھوما جا سکتا ہے جیسا browser front end Actual جتنے کم resources استعمال کرتا ہے۔