VPS'te Actual Budget Docker ile Nasıl Kurulur?

Ne oluşturuluyor

Actual Budget, kendi sunucunuzda barındırabileceğiniz bir zarf bütçeleme uygulamasıdır. Kendi sunucularında barındırabilecekleri bir YNAB alternatifi arayanlar için genellikle tercih edilen çözümdür. Sunucu tek bir container, tek bir veri volume'u ve tek bir HTTPS adından oluşur. Sıradan bir bütçenin gerektirdiği işlemler, kiralanabilecek en küçük VPS üzerinde bile sorunsuz çalışır. Bunun nedeni, sunucunun çoğunlukla dosyaları depolaması ve bunları senkronize etmesidir.

Herhangi bir komut çalıştırmadan önce mimariyi anlamak gerekir. Bütçenin kendisi, tarayıcınızda ve her mobil uygulamada bulunan bir SQLite veritabanıdır. Kurulmak üzere olan sunucu bir senkronizasyon endpoint'idir. Hesap listesini, bütçe dosyalarını ve telefon ile dizüstü bilgisayarın aynı veriler üzerinde anlaşmasını sağlayan değişiklik günlüğünü barındırır. Bu nedenle sunucu kullanılamadığında uygulama çalışmaya devam eder. Ayrıca istemcilerden en az biri bir kopyayı koruduğu sürece sunucunun kaybedilmesi bütçenin kaybedilmesine yol açmaz.

Sunucunun HTTPS gerektirmesinin nedeni

Actual, HTTPS ister; 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 belirtimde güvenli bağlam olarak adlandırılan ortamda sunar. Güvenli bağlam, https:// veya http://localhost şeklindedir. Uygulama başka bir makinedeki tarayıcıda http://203.0.113.10:5006 üzerinden açılırsa bu özellikler kullanılamaz; çünkü tarayıcı bunları sayfaya hiç sunmamıştır. Resmi mobil derlemeler de düz http:// sunucu URL'lerini reddeder.

Bu nedenle kullanılabilecek iki kurulum vardır. Bu kılavuzda yapıldığı gibi, container'ın önüne gerçek bir ad için geçerli bir sertifika yerleştirilebilir. Alternatif olarak sunucuya ACTUAL_HTTPS_KEY ve ACTUAL_HTTPS_CERT ile self-signed bir sertifika verilebilir; proje bunu belgelendirir, ancak her cihazda tarayıcı uyarısı kabul edilmelidir. Let's Encrypt tarafından sağlanan ücretsiz bir sertifikanın alınması beş dakika sürdüğünden ilk seçenek tercih edilmelidir.

Docker Compose ile Actual Budget Kurulumu

Makine yeni kurulmuşsa önce Docker kurulur. Compose dosyası söz dizimi yeni öğreniliyorsa aşağıdaki alanlar VPS için Docker Compose temelleri kılavuzunda açıklanır.

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

/opt/actual/docker-compose.yml yazılır:

services:
  actual:
    image: actualbudget/actual-server:latest
    container_name: actual
    restart: unless-stopped
    ports:
      - '127.0.0.1:5006:5006'
    volumes:
      - ./data:/data

Bu dosyada üç ayrıntı önemlidir.

Kullanılan image, proje tarafından Docker Hub'da yayımlanan ve ghcr.io/actualbudget/actual adresinde yansılanan actualbudget/actual-server:latest değeridir. Düşük güç tüketen makineler için latest-alpine etiketi bulunur.

Container, tüm verileri /data altında yazar. Bunun içinde, oturum açma ve oturum belirteçlerini içeren account.sqlite dosyasının bulunduğu server-files ile bütçe dosyalarının kendisini içeren user-files bulunur. Bu yolu mount edin; aksi takdirde bir sonraki docker compose pull bütçenizi siler. ACTUAL_DATA_DIR bu yolu değiştirebilir, ancak varsayılan değer uygundur.

Port yalnızca 127.0.0.1 üzerinde yayımlanır. Tek başına kullanılan 5006:5006 tüm arayüzlerde yayımlama yapar. Docker kendi kurallarını ufw kurallarının önüne yazdığı için uygulama, tüm trafiği reddeden bir firewall olsa bile internete açık olur. Bu beklenmeyen durum Docker tarafından yayımlanan portların ufw'yi neden aştığı bölümünde açıklanır. Loopback'e bağlamak, yalnızca aynı makinedeki reverse proxy'nin uygulamaya erişebilmesini sağlar.

Başlatılır:

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

Sunucu 5006 portunu dinlediğini bildirdiğinde log durulur. DNS ile ilgili işlem yapmadan önce yerel olarak denetlenir:

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

200 çıktısı, uygulamanın hizmet verdiği anlamına gelir. curl: (7) Failed to connect, container'ın çalışmadığı anlamına gelir. docker compose ps container'ın çıkış yaptığını gösterir. Yaygın neden, mount edilen volume üzerindeki bir izin sorunudur. Bu sorun logda EACCES satırı olarak görülür.

Önüne bir sertifika ve gerçek bir ad koyun

VPS'ye bir A kaydı, budget.example.com, yönlendirin ve çözümlenmesini bekleyin. Ardından nginx'i kurun ve sertifikayı oluşturun. Ubuntu 24.04 üzerinde nginx ile Certbot kılavuzunda sertifika oluşturma ve yenileme zamanlayıcısı ayrıntılı olarak açıklanmaktadı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, çoğu kişinin unuttuğu satırdır. Tam senkronizasyonda bütçe dosyasının tamamı yüklenir. Nginx, istek gövdesi için varsayılan olarak 1 MB sınırı kullanır. Bu nedenle dosya bu boyutu aştığında senkronizasyon başarısız olur. Nginx access log içinde 413 Request Entity Too Large görülürken uygulama yalnızca genel bir senkronizasyon hatası gösterir. Sunucunun ayrıca kendi sınırları vardır: ACTUAL_UPLOAD_FILE_SYNC_SIZE_LIMIT_MB varsayılan olarak 20, ACTUAL_UPLOAD_SYNC_ENCRYPTED_FILE_SYNC_SIZE_LIMIT_MB ise 50 değerini kullanır. Bu nedenle nginx sınırını, sizin için geçerli olan değerin üzerine ayarlayın.

Yapılandırmayı 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 dosyanız

Bir tarayıcıda https://budget.example.com adresini açın. İlk ekran sizden bir sunucu parolası belirlemenizi ister. Bu parola tüm sunucuyu korur. Bu nedenle uzun ve rastgele bir parola oluşturun ve kendi barındırdığınız Vaultwarden parola yöneticisi gibi tekrar bulabileceğiniz güvenli bir yerde saklayın. Oluşturulacak kullanıcı hesabı yoktur. Actual, tasarım gereği tek parolayla çalışır. Bu nedenle bütçe paylaşımı, bu parolanın paylaşılması anlamına gelir.

Ardından bir bütçe dosyası oluşturun. Actual, uçtan uca şifrelemeyi etkinleştirip etkinleştirmeyeceğinizi sorar. Evet seçeneğini belirleyin. Böylece sunucu yalnızca şifreli metni depolar. Kiralanmış bir makinede finansal veriler için doğru yaklaşım budur. Bunun gerçek bir bedeli vardır: Şifreleme parolası sunucuya hiçbir zaman ulaşmaz. Bu parolayı kaybederseniz dosya kaybolur ve parola sıfırlama seçeneği bulunmaz. Bu ekrandan ilerlemeden önce parolayı bir yere yazın.

Başlangıç bakiyelerinizi yıllar boyunca biriktirilmiş geçmişi içe aktarmak yerine bankanızdaki güncel tutarlara göre ayarlayın. Zarf bütçeleme, elinizdeki mevcut parayla ileriye doğru çalışır. Bu nedenle geçmiş verilerin bulunmaması sorun oluşturmaz.

İşlemleri içe aktarma

Burada heves yerine dürüstlük önemlidir. Çünkü içe aktarma deneyimi, insanların kendi barındırdıkları bütçe sistemlerini kullanmayı bırakmasının başlıca nedenidir.

Elle giriş temel yöntemdir ve her zaman çalışır. Zarf yöntemi açısından bu, tartışmalı olarak yöntemin özüdür. Çünkü bir satın alma işlemini yazmak, harcamayı fark etmenizi sağlar.

Dosya içe aktarma işlemlerin çoğunu karşılar. Actual; CSV, QIF, OFX ve QFX dosyalarını okuyabilir. Her banka bu biçimlerden en az birinde dışa aktarma yapar. Hesap ekranından her hesap için içe aktarma başlatılır. Sütunlar bir kez eşleştirilir. Actual bu düzeni hesap için hatırlar.

Otomatik banka senkronizasyonu vardır. Ancak sunucu bankalarla kendi başına iletişim kuramadığı için üçüncü taraf bir hizmet gerekir. Actual; Kuzey Amerika bankaları için SimpleFIN Bridge, Avrupa için Enable Banking, Yeni Zelanda için Akahu ve Brezilya için Pluggy.ai destekler. GoCardless hâlâ desteklenir, ancak yeni hesap kabul etmemektedir. Sağlayıcıya kendiniz kaydolmanız, kimlik bilgilerini oluşturmanız ve bunları sunucuya eklemeniz gerekir. SimpleFIN Bridge, Temmuz 2026 itibarıyla en fazla 25 kurum için yıllık 15 US dollars ücret alır. Diğer sağlayıcıların fiyatlandırması farklıdır.

Bu özelliğe güvenmeden önce iki sınırlama kabul edilmelidir. API kimlik bilgileri sunucuda tutulur ve uçtan uca şifreleme kapsamında değildir. Çünkü sunucunun bu bilgileri kullanması gerekir. Ayrıca Actual yoklama yapmaz. Senkronizasyon, basılan bir düğmeyle başlatılır; arka plan işi olarak çalışmaz.

Yedekler, çünkü yalnızca dosyalar var

Önem verdiğiniz her şey /opt/actual/data altında bulunur. Bir dışa aktarma adımı yoktur ve komut dosyasıyla çalıştırılacak bir veritabanı dökümü gerekmez.

Tek sorun SQLite'tır. Sunucu yazma işlemi gerçekleştirirken account.sqlite dosyasının kopyalanması, işlemin tamamlanmamış bir bölümünü yakalayabilir. Bunu ancak geri yüklemeyi denediğinizde fark edebilirsiniz. Kopyalama işleminin sürdüğü birkaç saniye boyunca container'ı 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 kurulumunu, saklama ilkelerini ve geri yükleme tatbikatını kapsayan VPS üzerinde restic yedekleri yaklaşımıyla bir zamanlamaya bağlayın. Geri yükleme tatbikatını gerçekleştirin. Hiç geri yüklemediğiniz bir yedek yalnızca bir varsayımdır.

Actual'ın kendi istemci tarafı yedekleri ayrı bir konudur ve bilinmeleri yararlıdır. Tarayıcı, bütçe dosyasının son kopyalarını tutar. Bu kopyalara dosya menüsünden erişilebilir. Böylece sunucuya hiç dokunmadan "bir kategoriyi yanlışlıkla sildim" durumunu çözebilirsiniz.

Sunucuyu güncelleme

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

Compose, yeni image kullanarak container'ı yeniden oluşturur ve aynı volume'ü 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ı göstererek 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.

Ne bozulur ve ne görülür

Uygulama yüklenir, ancak eşitleme hiç tamamlanmaz. nginx erişim günlüğünde 413 değerini kontrol edin. Bu, client_max_body_size değerinin çok düşük olduğu anlamına gelir. 502 ise nginx'in çalıştığını ve container'ın çalışmadığını gösterir.

Şifreleme seçenekleri yok veya mobil uygulama URL'yi reddediyor. Sayfa güvenli bir bağlamda değil. Adres çubuğunda bir IP adresiyle veya localhost olmayan bir ana bilgisayar adıyla birlikte http:// görünür. Geçici çözüm uygulamak yerine sertifikayı düzeltin.

Bütçe dosyasının bu sürümle uyumlu olmadığına dair bir ileti görüntüleniyor. İstemci ve sunucu sürümleri birbirinden ayrılmıştır. Her ikisini de aynı release sürümüne güncelleyin ve yeniden yükleyin.

Container bir döngü içinde yeniden başlıyor. docker compose logs actual dosyasını okuyun. /data üzerinde görülen bir izin hatası, bağlanan dizinin container kullanıcısı tarafından yazılabilir olmadığı anlamına gelir. Adresin kullanımda olduğunu belirten bir hata, başka bir işlemin loopback üzerinde 5006 numaralı bağlantı noktasını zaten kullandığını gösterir.

İlk yükleme yavaş görünüyor. Bütçe dosyasının tamamı açıldığında tarayıcıya indirilir. Önce tek ve büyük bir aktarım yapılır, ardından yerel okuma işlemleri gerçekleştirilir. Bu bir sunucu boyutlandırma sorunu değildir ve RAM eklemek bunu değiştirmez.

FAQ

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

Uygulamada evet. Actual'ın uçtan uca şifrelemesi tarayıcının Web Crypto API'sini kullanır. Tarayıcılar bu API'yi yalnızca güvenli bağlamda, yani https:// veya http://localhost üzerinden sunar. Başka bir makineden düz HTTP kullanıldığında bu özellikler kullanılamaz. Resmî mobil uygulamalar da düz HTTP sunucu URL'lerini kabul etmez. Gerçek bir ana makine adıyla Let's Encrypt sertifikası kullanın. Yalnızca masaüstü tarayıcısı kullanacaksanız ACTUAL_HTTPS_KEY ve ACTUAL_HTTPS_CERT ile imzalanan bir sertifika da kullanılabilir.

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

Yalnızca kendiniz kaydolduğunuz bir üçüncü taraf hizmeti üzerinden aktarabilir: Kuzey Amerika'da SimpleFIN Bridge, Avrupa'da Enable Banking, Yeni Zelanda'da Akahu veya Brezilya'da Pluggy.ai. GoCardless desteklenir, ancak yeni hesapları kabul etmemektedir. Bu API kimlik bilgileri sunucunuzda bulunur ve uçtan uca şifreleme kapsamına girmez. Eşitleme de el ile yapılır. Bir düğmeye basmanız gerekir; arka planda yoklama yapılmaz. CSV, QIF, OFX ve QFX içe aktarma işlemleri için üçüncü taraf hizmeti gerekmez.

Tam olarak nelerin yedeğini almalıyım?

Bu kılavuzda /opt/actual/data olan bağlanmış veri dizininin yedeğini alın. Bu dizinde oturum açma bilgileri ve oturumları içeren server-files/account.sqlite ile bütçe dosyalarını içeren user-files bulunur. Kopyalama işleminden önce container'ı durdurun. Çalışan bir SQLite veritabanını kopyalamak eksik bir yazma işlemi yakalayabilir. Sunucudaki başka hiçbir bileşen durum bilgisi tutmaz.

Şifreleme parolasını kaybedersem ne olur?

Dosya kurtarılamaz. Uçtan uca şifrelemenin temel amacı gereği parola sunucuya hiçbir zaman ulaşmaz. Bu nedenle parola sıfırlama veya destek yoluyla kurtarma mümkün değildir. Dosyayı oluşturduğunuz anda parolayı bir parola yöneticisine kaydedin. Ayrıca aynı sunucuya bağlı olmayan bir yerde de kopyasını saklayın.

Actual Budget ne kadar sunucu kaynağı gerektirir?

Çok az kaynak gerektirir. Container statik varlıkları ve dosyaları sunar. Bütçe hesaplamaları tarayıcıda yapılır. 1 GB RAM'e sahip tek bir paylaşımlı vCPU, Actual Budget'ı sorunsuz çalıştırır. Birkaç yıllık geçmişi olan ev bütçesinin veri dizini onlarca megabayt boyutunda kalır. Disk kullanımındaki artışa Actual değil, yedekleriniz ve diğer container'larınız neden olur.