Actual Budget VPS uzerinde nasil kurulur?

Ne inşa ediyorsunuz

Actual Budget, kendi sunucunuzda barındırabileceğiniz bir zarf usulü bütçeleme uygulamasıdır ve YNAB alternatifi arayanların kendi sunucularında barındırabilecekleri yaygın bir çözümdür. Sunucu; tek bir container, tek bir veri birimi ve tek bir HTTPS adından oluşur. Normal bir bütçenin ihtiyaç duyduğu her şey, kiralayabileceğiniz en küçük VPS üzerinde bile rahatlıkla çalışır; çünkü sunucu temel olarak dosyaları saklar ve bunları senkronize eder.

Herhangi bir işlem yapmadan önce mimariyi anlamak faydalıdır. Bütçenin kendisi, tarayıcınızın ve her bir mobil uygulamanın içinde yaşayan bir SQLite veritabanıdır. Kurmak üzere olduğunuz sunucu bir senkronizasyon uç noktasıdır; hesap listesini, bütçe dosyalarını ve bir telefon ile dizüstü bilgisayarın uyumlu kalmasını sağlayan değişiklik günlüğünü tutar. Uygulamanın sunucu kapalıyken bile çalışmaya devam etmesinin ve bir istemcide kopyası bulunduğu sürece sunucunun kaybedilmesinin bütçenizi yok etmemesinin nedeni budur.

Sunucunun neden HTTPS'e ihtiyaç duyduğu

Actual, HTTPS gerektirir ve bu bir formalite değildir. Tarayıcılar, Actual'ın uçtan uca şifreleme için kullandığı arayüz olan Web Crypto API'yi yalnızca spesifikasyonun güvenli bağlam (secure context) olarak adlandırdığı durumlarda kullanıma sunar. Güvenli bağlam, https:// veya http://localhost adresidir. Uygulamayı başka bir makinedeki tarayıcıdan http://203.0.113.10:5006 üzerinden yüklerseniz, tarayıcı bu özellikleri sayfaya sağlamayacağı için ilgili işlevler çalışmayacaktır. Resmi mobil sürümler de şifrelenmemiş http:// sunucu URL'lerini kabul etmez.

Bu nedenle iki uygulanabilir kurulum yöntemi mevcuttur. Bu kılavuzda uygulandığı gibi, container'ın önüne gerçek bir alan adı ve gerçek bir sertifika koymak. Veya proje belgelerinde açıklandığı üzere, ACTUAL_HTTPS_KEY ve ACTUAL_HTTPS_CERT kullanarak sunucuya kendinden imzalı (self-signed) bir sertifika tanımlamak ve her cihazda tarayıcı uyarısını kabul etmek. Let's Encrypt üzerinden ücretsiz bir sertifika almak beş dakika sürer, bu yüzden ilk seçeneği tercih edin.

Install Actual Budget with Docker Compose

Install Docker first if the box is fresh. If Compose file syntax is new to you, the Docker Compose basics for a VPS guide covers the fields used below.

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

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

Three details in that file matter.

The image is actualbudget/actual-server:latest, published by the project to Docker Hub and mirrored at ghcr.io/actualbudget/actual. There is a latest-alpine tag for low-power machines.

The container writes everything under /data. Inside it you get server-files, which holds account.sqlite with your login and session tokens, and user-files, which holds the budget files themselves. Mount that path or the next docker compose pull throws your budget away. ACTUAL_DATA_DIR can move it, but the default is fine.

The port is published on 127.0.0.1 only. A bare 5006:5006 publishes on every interface, and Docker writes its own rules ahead of ufw, so the app would be open to the internet even with a deny-all firewall. That surprise is explained in why Docker published ports bypass ufw. Binding to loopback means only the reverse proxy on the same box can reach it.

Start it:

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

The log settles once the server reports it is listening on port 5006. Check it locally before you touch DNS:

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

A 200 means the app is serving. curl: (7) Failed to connect means the container is not running, and docker compose ps will show it exited. The usual cause is a permission problem on the mounted volume, visible as an EACCES line in the log.

Sertifika ve gerçek bir alan adı yapılandırma

VPS adresinize bir A kaydı tanımlayın, budget.example.com, ve çözümleme işleminin gerçekleşmesini bekleyin. Ardından nginx kurulumunu yapın ve sertifikayı oluşturun. Ubuntu 24.04 üzerinde nginx ile Certbot kılavuzu, sertifika oluşturma ve yenileme zamanlayıcısı süreçlerini tüm detaylarıyla açıklamaktadır.

Proxy bloğu:

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, kullanıcıların genellikle unuttuğu satırdır. Bütçe dosyası, tam eşitleme sırasında bir bütün olarak yüklenir. Nginx varsayılan olarak 1 MB istek gövdesi sınırına sahiptir; bu nedenle dosya boyutu bu sınırı aştığında, nginx erişim günlüğünde 413 Request Entity Too Large hatası oluşur ve uygulama yalnızca genel bir eşitleme hatası gösterir. Sunucunun kendi ayrı sınırları mevcuttur: ACTUAL_UPLOAD_FILE_SYNC_SIZE_LIMIT_MB varsayılan olarak 20, ACTUAL_UPLOAD_SYNC_ENCRYPTED_FILE_SYNC_SIZE_LIMIT_MB ise varsayılan olarak 50 değerindedir; bu nedenle nginx sınırını, sizin için geçerli olan değerin üzerinde bir seviyeye ayarlayın.

Yeniden yükleyin ve test edin:

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

İlk çalıştırma: parola ve ilk bütçe dosyası

Tarayıcıda https://budget.example.com adresini açın. İlk ekran sizden bir sunucu parolası belirlemenizi ister. Bu tek parola tüm sunucuyu korur; bu nedenle uzun ve rastgele bir parola oluşturun ve self-hosted Vaultwarden parola yöneticisi gibi erişebileceğiniz bir yerde saklayın. Oluşturulacak herhangi bir kullanıcı hesabı yoktur. Actual sunucusu tasarım gereği tek parolalıdır; bu nedenle bir bütçeyi paylaşmak, o parolayı paylaşmak anlamına gelir.

Ardından bir bütçe dosyası oluşturun. Actual, uçtan uca şifrelemenin etkinleştirilip etkinleştirilmeyeceğini sorar. Evet yanıtını verin; böylece sunucu yalnızca şifreli metin verilerini saklar. Kiralık bir makinedeki finansal veriler için doğru yaklaşım budur. Bunun bir bedeli vardır: şifreleme parolası sunucuya asla ulaşmaz; bu nedenle parolayı kaybederseniz dosya geri döndürülemez şekilde kaybolur ve parola sıfırlama seçeneği bulunmaz. Bu ekranı geçmeden önce parolayı not edin.

Başlangıç bakiyelerinizi, yıllarca süren geçmiş verileri içe aktarmak yerine bankanızın güncel rakamlarına göre ayarlayın. Zarf bütçeleme yöntemi, elinizde bulunan mevcut paradan ileriye doğru çalışır; bu nedenle geçmiş verilerin boş olması size bir kayıp yaşatmaz.

İşlemleri içeri aktarma

İçe aktarma süreci, insanların self-hosted bütçeleme araçlarını kullanmayı bırakmalarının ana nedeni olduğundan, burada dürüstlük hevesli olmaktan daha önemlidir.

Manuel giriş temel yöntemdir ve her zaman çalışır. Zarf yöntemi için bu durum tartışmasız bir gerekliliktir, çünkü bir harcamayı elle yazmak onu fark etmenizi sağlar.

Dosya içe aktarma işlemi toplu veriler için kullanılır. Actual; CSV, QIF, OFX ve QFX formatlarını okuyabilir ve her banka bu formatlardan en az birini dışa aktarır. İçe aktarma işlemini hesap ekranından hesap bazlı yapın, sütunları bir kez eşleştirin; Actual bu düzeni ilgili hesap için hatırlar.

Otomatik banka senkronizasyonu mevcuttur ancak sunucu bankalarla doğrudan iletişim kuramadığı için üçüncü taraf bir servis gerektirir. Actual; Kuzey Amerika bankaları için SimpleFIN Bridge, Avrupa için Enable Banking, Yeni Zelanda için Akahu ve Brezilya için Pluggy.ai servislerini destekler. GoCardless hala desteklenmektedir ancak yeni hesap kabul etmemektedir. Sağlayıcıya kendiniz kaydolun, kimlik bilgileri oluşturun ve bunları sunucuya ekleyin. Temmuz 2026 itibarıyla SimpleFIN Bridge, 25 kuruma kadar yıllık 15 ABD doları ücret almaktadır; diğer servislerin fiyatlandırması farklıdır.

Buna güvenmeden önce kabul etmeniz gereken iki sınırlama vardır. API kimlik bilgileri sunucuda tutulur ve sunucunun bunları kullanması gerektiği için uçtan uca şifreleme kapsamında değildir. Ayrıca Actual otomatik sorgulama yapmaz: senkronizasyon arka planda çalışan bir iş değil, sizin bastığınız bir düğmedir.

Yedekleme, çünkü sadece dosyalardan ibarettir

Önem verdiğiniz her şey /opt/actual/data dizini altındadır. Herhangi bir dışa aktarma adımı veya betiklenmesi gereken bir veritabanı dökümü yoktur.

Buradaki tek tuzak SQLite kullanımıdır. Sunucu yazma işlemi yaparken account.sqlite dosyasını kopyalamak, yarım kalmış bir işlemin kopyalanmasına neden olabilir; bunu ancak geri yükleme yapmaya çalıştığınızda fark edersiniz. Kopyalama işleminin sürdüğü birkaç saniye boyunca container sürecini durdurun:

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

Bunu, depo kurulumu, saklama politikaları ve geri yükleme tatbikatını kapsayan VPS üzerinde restic yedekleme yaklaşımıyla bir zamanlamaya bağlayın. Geri yükleme tatbikatını mutlaka gerçekleştirin. Daha önce geri yüklemediğiniz bir yedek, sadece bir tahmindir.

Actual uygulamasının kendi istemci tarafı yedeklemeleri ayrı bir konudur ve bilinmesi faydalıdır. Tarayıcı, bütçe dosyasının güncel kopyalarını dosya menüsünden erişilebilir şekilde tutar. Bu özellik, sunucuya hiç dokunmadan "yanlışlıkla bir kategori sildim" gibi durumları çözmenizi sağlar.

Sunucunun güncellenmesi

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

Compose, yeni image üzerinden container’ı yeniden oluşturur ve aynı volume’u yeniden bağlar; bu nedenle veriler korunur. İstemciler de güncellenmelidir. Sunucu ve uygulama sürümlerinin birbirine yakın olması beklenir. Sunucudan çok daha eski bir istemci, sürüm uyuşmazlığı mesajı vererek senkronizasyonu reddedebilir. Büyük bir sürüm geçişinden önce yedek alınmalıdır. Çünkü migration işlemleri ilk başlatmada çalışır ve downgrade yolu yoktur. Actual, durumu bir dosya dizini olduğundan, değişken bir latest tag kullanımını tolere eder. Gerçek bir veritabanı taşıyan uygulamalarda bu durum geçerli değildir. Chatwoot'u self-host etme başlığında, kullanılacak sabit tag değerleri ve yükseltme öncesinde alınması gereken dump işlemi açıklanır.

Neler bozulur ve ne ile karşılaşırsınız

Uygulama yükleniyor ancak eşitleme asla tamamlanmıyor. 413 için nginx erişim günlüğünü kontrol edin. Bu, client_max_body_size değerinin çok düşük ayarlandığı anlamına gelir. 502 hatası ise nginx'in çalıştığını ancak container'ın çalışmadığını gösterir.

Şifreleme seçenekleri eksik veya mobil uygulama URL'yi reddediyor. Sayfa güvenli bir bağlamda değildir. Adres çubuğu, bir IP adresi veya localhost olmayan bir ana bilgisayar adı ile http:// uyarısını gösterecektir. Sorunu geçici çözümlerle aşmak yerine sertifikayı düzeltin.

Bütçe dosyasının bu sürümle uyumlu olmadığına dair bir mesaj. İstemci ve sunucu sürümleri birbirinden uzaklaşmıştır. Her ikisini de aynı sürüme güncelleyin ve yeniden yükleyin.

Container döngüsel olarak yeniden başlatılıyor. docker compose logs actual dosyasını okuyun. /data üzerindeki bir izin hatası, bağlanan dizinin container kullanıcısı tarafından yazılamaz olduğu anlamına gelir. Adres kullanımda hatası ise başka bir sürecin loopback üzerinde 5006 numaralı portu zaten tuttuğunu gösterir.

İlk yükleme yavaş hissettiriyor. Bütçe dosyasının tamamı, açtığınızda tarayıcıya indirilir. Bu tek bir büyük aktarımdır, sonrasında okumalar yerel olarak yapılır. Bu bir sunucu boyutlandırma sorunu değildir ve RAM eklemek durumu değiştirmeyecektir.

FAQ

Actual Budget'in çalışması için HTTPS gerekli mi?

Evet, pratikte gereklidir. Actual'ın uçtan uca şifreleme mekanizması tarayıcının Web Crypto API'sini kullanır ve tarayıcılar bu API'yi yalnızca güvenli bağlamlarda, yani https:// veya http://localhost üzerinden erişime açar. Başka bir makineden düz HTTP üzerinden bağlanıldığında bu özellikler kullanılamaz ve resmi mobil uygulamalar düz HTTP sunucu URL'lerini kabul etmez. Gerçek bir alan adı üzerinde Let's Encrypt sertifikası kullanın veya yalnızca masaüstü tarayıcı kullanacaksanız ACTUAL_HTTPS_KEY ve ACTUAL_HTTPS_CERT ile kendi imzaladığınız (self-signed) bir sertifika oluşturun.

Actual banka işlemlerimi otomatik olarak içe aktarabilir mi?

Yalnızca kendinizin kaydolduğu üçüncü taraf servisler aracılığıyla: Kuzey Amerika'da SimpleFIN Bridge, Avrupa'da Enable Banking, Yeni Zelanda'da Akahu veya Brezilya'da Pluggy.ai. GoCardless desteklenmektedir ancak yeni hesap kabul etmemektedir. Bu API kimlik bilgileri sunucunuzda tutulur ve uçtan uca şifreleme kapsamında değildir. Senkronizasyon da manueldir; yani bir düğmeye basarsınız ve arka planda hiçbir veri çekme işlemi gerçekleşmez. CSV, QIF, OFX ve QFX içe aktarma işlemleri için herhangi bir üçüncü tarafa ihtiyaç duyulmaz.

Tam olarak neleri yedeklemem gerekiyor?

Bu rehberde /opt/actual/data olarak belirtilen mount edilmiş veri dizini. Bu dizin, giriş bilgilerini ve oturumları içeren server-files/account.sqlite dosyasını ve bütçe dosyalarını içeren user-files klasörünü barındırır. Kopyalama işleminden önce container'ı durdurun; çünkü çalışan bir SQLite veritabanını kopyalamak, veritabanının kısmi yazılmış bir halini almanıza neden olabilir. Sunucuda durum bilgisi tutan başka hiçbir öğe yoktur.

Şifreleme şifremi kaybedersem ne olur?

Dosya kurtarılamaz. Şifre hiçbir zaman sunucuya ulaşmaz; uçtan uca şifrelemenin temel amacı budur, bu nedenle bir sıfırlama seçeneği veya destek yolu bulunmamaktadır. Dosyayı oluşturduğunuz anda şifreyi bir parola yöneticisine kaydedin ve bu sunucuya bağımlı olmayan bir yerde bir kopyasını saklayın.

Actual Budget ne kadar sunucu kaynağına ihtiyaç duyar?

Çok az. Container statik varlıkları ve dosyaları sunar, bütçe hesaplamaları ise tarayıcıda gerçekleşir. 1 GB RAM'e sahip paylaşımlı bir vCPU, uygulamayı sorunsuz çalıştırır; birkaç yıllık geçmişe sahip bir hane bütçesinin veri dizini ise yalnızca onlarca megabayt yer kaplar. Disk üzerindeki yük Actual'dan değil, yedeklerinizden ve diğer container'larınızdan kaynaklanır. Yanında daha fazla kaynak tüketen başka uygulamalar çalıştıracak bir sunucu planlıyorsanız, genellikle fotoğraf sunucuları sistem gereksinimlerini belirler; bu yüzden bir plan seçmeden önce PhotoPrism ve Immich'in ne kadar RAM'e ihtiyaç duyduğuna göz atın.