Docker ile AFFiNE self-host kurulum rehberi
AFFiNE uygulamasını Docker Compose ile kendi sunucunuzda çalıştırın. Dört container yapısı, veri dizinleri, yedekleme stratejileri ve 2 GB RAM ile performans analizi.
AFFiNE self-host kurulumunda elde edecekleriniz
AFFiNE uygulamasını kendi sunucunuzda barındırmak, kontrolü sizde olan bir sunucu üzerinde Notion benzeri bir çalışma alanı sağlar. Bu kurulum; uygulama, tek seferlik geçiş işi (migration job), Postgres ve Redis olmak üzere dört container ile çalışır. Kendi kendine barındırılan bir çalışma alanında varsayılan olarak 10 kullanıcıya kadar gerçek zamanlı iş birliği desteği mevcuttur. Kurulum, bir adet compose dosyası ve bir adet JSON yapılandırma dosyasından oluşur. Görüntü etiketleri (image tags), disk düzeni, bellek sınırı ve önüne koyacağınız proxy yapısı üzerinde dikkatle düşünülmelidir.
AFFiNE, bir belge düzenleyiciyi ve sonsuz bir tuvali aynı çalışma alanında tutar; böylece bir sayfa hem belge olarak okunabilir hem de beyaz tahta olarak genişletilebilir. Hangi uygulamayı çalıştıracağınıza henüz karar vermediyseniz, önce kendi kendine barındırılan Notion alternatiflerinin karşılaştırması bölümünü okuyun. Bu kılavuz, kararın verildiğini varsayar ve karşılaştırma yapmak yerine AFFiNE uygulamasının düzgün bir şekilde çalıştırılmasına odaklanır.
Buradaki tüm bilgiler, 8 Ağustos 2026 tarihinde AFFiNE self-host belgeleri ve yayınlanan sürüm dosyaları ile kontrol edilmiştir. O tarihteki en yeni kararlı sürüm, 23 Temmuz 2026 tarihinde yayınlanan 0.27.3 sürümüdür. Aşağıda daha ileri bir tarih içeren iddialar, 12 Ekim 2026 tarihinde birincil kaynakları üzerinden tekrar doğrulanmıştır; bu tarihte en yeni kararlı sürüm, 18 Ağustos 2026 tarihinde yayınlanan 0.27.4 sürümüdür.
Dört container'ın gerçek işlevleri
affine, tek bir imaj içerisinde hem sunucu hem de web istemcisidir. 3010 numaralı portu dinler.
affine_migration, node ./scripts/self-host-predeploy.js komutunu çalıştıran, veritabanı migrasyonlarını uygulayan ve ardından sonlanan tek seferlik bir görevdir. Uygulama, bu görev üzerinde condition: service_completed_successfully tanımlar; bu nedenle sıfırdan farklı bir durum koduyla sonlanan bir migrasyon, affine servisinin hiç başlamayacağı anlamına gelir. Web arayüzü açılmadığında, ilk okunması gereken yer bu görevin günlük kayıtlarıdır.
postgres; belgelerinizi, kullanıcılarınızı, çalışma alanlarınızı ve izinlerinizi tutar. Sunulan imaj, pgvector eklentisi derlenmiş standart Postgres 16 olan pgvector/pgvector:pg16 imajıdır. pgvector, Postgres'e vector sütun türünü ekler; bu, metinlerin anlamlarına göre aranabilmesi için gömmelerin (embeddings) saklandığı sayısal formdur.
redis zorunlu bir bağımlılıktır: hem sunucu hem de migrasyon görevi, başlamadan önce bu servisin sağlık kontrolünün (health check) geçmesini bekler. Sunulan compose dosyasının Redis'e bir volume tanımlamadığına dikkat edin. İçindeki hiçbir veri docker compose down sonrasında kalıcı olmaz; bu da Redis'in size ait herhangi bir içerik barındırmadığını ve yedeklenmesine gerek olmadığını açıkça gösterir.
Postgres imajının neden stok postgres değil de pgvector olduğu
Bu gereksinim bir tercihten değil, AFFiNE şemasından kaynaklanmaktadır. v0.27.4 sürümünde schema.prisma hala extensions = [pgvector(map: "vector")] bildirmektedir ancak herhangi bir embedding sütunu içermemektedir. v0.27.3 sürümünde vector(1024) tipinde embedding sütunlarına sahip dört model, v0.27.4 sürümünde bulunmamaktadır. Sağlanan pgvector/pgvector:pg16 imajını kullanmaya devam edin: eklenti hala bildirilmektedir ve stok postgres:16 bu eklentiyi içermemektedir.
Resmi v0.27.4 şablonu pgvector imajını kullanmaktadır; v0.21.0 şablonu ise hala postgres:16 kullanıyordu. Eski bir kurulumda imaj satırını düzenlemek yükseltme işleminin tamamı değildir; bu nedenle herhangi bir işlem yapmadan önce AFFiNE self-host belgeleri sayfasındaki yükseltme bölümünü okuyun.
Bu etiketle ilgili bir husus daha bulunmaktadır. pg16, Postgres 16 anlamına gelir ve Postgres ana sürümü öylece yükseltilebilecek bir sayı değildir. Mevcut bir veri dizini üzerinde sürümü pg17 olarak değiştirirseniz, Postgres docker compose logs postgres içerisinde The data directory was initialized by PostgreSQL version 16, which is not compatible with this version 17 benzeri bir satırla başlamayı reddeder. Bir ana sürüm değişikliği, PostgreSQL 17 sürüm notlarında belirtilen üç yöntemden birini gerektirir: dump alıp yeni bir veri dizinine geri yükleme, pg_upgrade veya mantıksal replikasyon. Tek bir Compose kurulumunda dump alıp geri yükleme genellikle en basit yöntemdir, çünkü pg_upgrade eski ve yeni sunucu binary dosyalarının yan yana bulunmasını gerektirir.
Self-hosted AFFiNE ne kadar CPU ve RAM gerektirir
AFFiNE gereksinimler sayfası en az 4 CPU çekirdeği ve 2 GB RAM talep eder; belgeleriniz 10.000 kelimeyi geçtiğinde ise bellek ihtiyacını 4 GB'a çıkarır. Aynı sayfa belleğin nereye harcandığını belirtir: senkronizasyon sistemi ve belge birleştirme işlemleri. Akılda tutulması gereken bir veri şudur: 10.000 değişiklik içeren bir belgeyi birleştirmek 1 GB'a kadar bellek kullanımı oluşturabilir.
Bu durumu, iki kişinin yazı yazdığı 2 GB'lık bir planla karşılaştırın. Ortalama kullanım uygundur. Postgres ve Node süreci, sınırın altında kalarak yeterli alan bırakır. Sorun, anlık zirve değerleridir. Tek bir büyük birleştirme işlemi, sunucunun bellek kullanımını yaklaşık 1 GB'lık bir zirveye taşıyabilir. Swap alanı olmayan 2 GB'lık bir sunucuda, bu zirve değeri Postgres ve diğer yerleşik süreçlerle birleştiğinde belleği tüketebilir. Çekirdeğin out-of-memory (OOM) killer mekanizması, belleği boşaltmak için bir süreci sonlandırır. Docker belgelerinde herhangi bir sürecin seçilebileceği açıkça belirtilse de, en büyük süreç olduğu için AFFiNE sunucusu muhtemelen kurban olacaktır.
AFFiNE sunucusu sonlandırıldığında, iş arkadaşınız bir hata görmez. Sayfanın yeniden yüklendiğini görür, çünkü restart: unless-stopped konteyneri saniyeler içinde tekrar ayağa kaldırır. Tahmin yürütmeyin, doğrulayın:
docker inspect affine_server --format '{{.State.OOMKilled}} {{.RestartCount}}'
sudo dmesg -T | grep -i -E 'out of memory|killed process'İlk komuttan gelen true veya ikinci komuttan node adını içeren bir Killed process satırı, bir hata bulduğunuzu değil, belleğinizin tükendiğini gösterir. Sorunu her iki taraftan da çözün. Önce swap ekleyin; böylece OOM killer devreye girmeden önce anlık yük artışlarının taşabileceği bir tampon alan oluşur:
sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab
free -hfree -h artık toplam 2.0Gi swap alanı bildirmelidir. Swap, AFFiNE'i hızlandırmaz ve amacı bu değildir. Anlık yük artışlarına gidecek bir yer sağlar; böylece bu artışın bir konteynerin ölmesine neden olması yerine, bir saniyelik yavaşlamaya yol açması daha olasıdır. Bu bir tampon alandır, garanti değildir. Çözümün diğer ayağı, Postgres'in önbelleğini birleştirme sırasında uygulamanın ihtiyaç duyduğu alana doğru genişletmesini durdurmaktır; Compose servisi üzerindeki bellek sınırları bunun içindir. Her iki işlemden sonra da sonlandırmalar devam ederse, sunucunun AFFiNE gereksinimler sayfasında daha büyük belgeler için talep edilen 4 GB belleğe ihtiyacı vardır.
Depolama alanını tahmin etmek çok daha kolaydır. Bunlar, AFFiNE'in aynı sayfada yayınladığı rakamlardır:
Bu grafiğin arkasındaki veriler
[
{
"label": "Server install",
"gb": 1.5
},
{
"label": "Postgres per 1,000 docs",
"gb": 0.1
},
{
"label": "Blob store per 1,000 uploads",
"gb": 10
}
]Sunucu kurulumu 1.5 GB yer kaplar. Her biri yaklaşık bin kelimeden oluşan bin belge, Postgres verisi olarak 0.1 GB ekler ki bu neredeyse yok denecek kadar azdır. Bin adet yüklenen dosya ise 10 GB ekler; hikayenin tamamı budur. Bunlar çalışan bir örnekten alınan ölçümlerden ziyade yayınlanmış planlama rakamlarıdır, bu yüzden bunları bir söz olarak değil, bir genel çerçeve olarak değerlendirin. Önemli olan bu çerçevedir: veritabanınız küçük kalır, disk kullanımınızı ise yüklediğiniz dosyalar belirler.
Compose dosyasını kendiniz oluşturun ve etiketleri sabitleyin
Belgelenmiş kurulum, curl -L -o docker-compose.yml https://github.com/toeverything/AFFiNE/releases/latest/download/docker-compose.yml ile hazır bir dosya indirir. Bu yöntem çalışır. Ancak güvenmeden önce bilinmesi gereken bir detay vardır: 8 Ağustos 2026 itibarıyla 0.27.3 sürümüne ekli dosya, yollarını hala bir .env dosyasından, ${UPLOAD_LOCATION}, ${CONFIG_LOCATION} ve ${DB_DATA_LOCATION} kullanarak okumaktaydı. Oysa belgelendirme referans sayfası, depolama ve PostgreSQL verilerini ./data altına alan, yapılandırmayı ./config altında tutan ve hiç .env gerektirmeyen daha yeni bir düzen göstermekteydi. 0.27.4 sürümü, ekli dosyayı bu yeni düzene taşıdı ve 12 Ekim 2026 itibarıyla her iki kaynak da uyumludur. Eğer eski dosyadan kurulum yaptıysanız yollarınız hala .env üzerinden gelir. AFFiNE yükseltme sayfası, bu ayarları taşımadan compose dosyasını değiştirmenin Postgres'i boş bir veri diziniyle başlatabileceği konusunda uyarır. Dosyayı kendiniz yazmak bu sorunu tamamen ortadan kaldırır; ayrıca imajları sabitlemek ve veritabanı şifresini ayarlamak için dosyayı zaten düzenlemeniz gerekecektir.
mkdir -p ~/affine/config ~/affine/data
cd ~/affine
printf 'DB_PASSWORD=%s\n' "$(openssl rand -hex 24)" > .env
chmod 600 .envCompose, .env dosyasını proje dizininden otomatik olarak okur ve ${DB_PASSWORD} değerini sizin yerinize yerleştirir; böylece şifre, destek forumlarında paylaşacağınız dosyada asla görünmez. Bu alışkanlığı çalıştırdığınız her yığın için sürdürmelisiniz; gerekçesi gizli bilgileri compose dosyasının dışında tutmak başlığında açıklanmıştır.
Şimdi ~/affine/docker-compose.yml dosyasını oluşturun:
name: affine
services:
affine:
image: ghcr.io/toeverything/affine:stable
container_name: affine_server
ports:
- '127.0.0.1:3010:3010'
depends_on:
redis:
condition: service_healthy
postgres:
condition: service_healthy
affine_migration:
condition: service_completed_successfully
volumes:
- ./data/storage:/root/.affine/storage
- ./config:/root/.affine/config
environment:
- REDIS_SERVER_HOST=redis
- DATABASE_URL=postgresql://affine:${DB_PASSWORD}@postgres:5432/affine
- AFFINE_INDEXER_ENABLED=false
restart: unless-stopped
affine_migration:
image: ghcr.io/toeverything/affine:stable
container_name: affine_migration_job
command: ['sh', '-c', 'node ./scripts/self-host-predeploy.js']
volumes:
- ./data/storage:/root/.affine/storage
- ./config:/root/.affine/config
environment:
- REDIS_SERVER_HOST=redis
- DATABASE_URL=postgresql://affine:${DB_PASSWORD}@postgres:5432/affine
- AFFINE_INDEXER_ENABLED=false
depends_on:
postgres:
condition: service_healthy
redis:
condition: service_healthy
redis:
image: redis:8-alpine
container_name: affine_redis
healthcheck:
test: ['CMD', 'redis-cli', '--raw', 'incr', 'ping']
interval: 10s
timeout: 5s
retries: 5
restart: unless-stopped
postgres:
image: pgvector/pgvector:pg16
container_name: affine_postgres
volumes:
- ./data/postgres:/var/lib/postgresql/data
environment:
POSTGRES_USER: affine
POSTGRES_PASSWORD: ${DB_PASSWORD}
POSTGRES_DB: affine
POSTGRES_INITDB_ARGS: '--data-checksums'
healthcheck:
test: ['CMD', 'pg_isready', '-U', 'affine', '-d', 'affine']
interval: 10s
timeout: 5s
retries: 5
restart: unless-stoppedUpstream tarafından sunulan dosyadan dört fark vardır ve her birinin bir nedeni bulunur.
127.0.0.1:3010:3010, portu yalnızca loopback adresi üzerinden yayınlar. 28.0.0 öncesi Docker sürümleri, aynı L2 segmentindeki ana bilgisayarların localhost üzerinden yayınlanan portlara erişmesine izin verir. Yapılandırılmış doğrudan yönlendirme (direct routing), loopback yayınlamasına rağmen container portunu dışarıya açabilir. Docker 28.0.0 veya daha yeni bir sürüm kullanın ve kurulum sırasında doğrudan yönlendirmeyi devre dışı bırakın. Upstream'3010:3010'ayarı tüm arayüzleri bağlar; çoğu VPS imajında bu, genel arayüzü de kapsar.POSTGRES_HOST_AUTH_METHOD: trustkaldırılmış ve yerine bir şifre atanmıştır. Trust kimlik doğrulaması, o veritabanına yapılan her bağlantıyı şifresiz olarakaffinekullanıcısı ile kabul eder. Bu durum yalnızca özel Compose ağı ile sınırlıdır; ancak o ağa başka bir container bağladığınızda veya hata ayıklama sırasında 5432 portunu yayınladığınızda risk oluşturur.redis:8-alpine,latestadresine çözümlenen çıplakredisifadesinin yerini alır. Ağustos 2026 itibarıyla bu Redis 8'dir; sabitleme işlemi, test ettiğiniz ana sürümü korur ve alakasız birdocker compose pullsırasında gelecekte Redis 9'un yüklenmesini engeller.pgvector/pgvector:pg16, yukarıda belirtilen nedenlerden dolayı upstream tarafından belirlendiği şekilde kalır.
POSTGRES_PASSWORD yalnızca Postgres veri dizinini ilk kez oluşturduğunda okunur. Hali hazırda var olan bir örnekte, şifreyi docker compose exec postgres psql -U affine -c "ALTER USER affine WITH PASSWORD 'yourpassword'" ile ayarlayın ve ardından DATABASE_URL dosyasını buna uygun şekilde güncelleyin.
Yapılandırma config/config.json dosyasında tutulur
AFFiNE ayarlarını config/config.json dizininden okur; bu dizin /root/.affine/config konumuna bağladığınız dizindir. Bu dosyayı sizin yerinize oluşturan bir süreç yoktur, bu nedenle ilk başlatmadan önce dosyayı oluşturun. ~/affine/config/config.json dosyasını bir düzenleyici ile açın ve örnek yerine kendi alan adınızı kullanarak içeriği şu şekilde düzenleyin:
{
"$schema": "https://github.com/toeverything/affine/releases/latest/download/config.schema.json",
"server": {
"name": "Team workspace",
"externalUrl": "https://affine.example.com"
},
"copilot": {
"enabled": false,
"byok": {
"enabled": false
}
}
}server.externalUrl, kullanıcılarınızın tarayıcıda gerçekten açtığı adres olmalıdır. AFFiNE, paylaşım bağlantılarını ve çalışma alanı davetlerini bu değer üzerinden oluşturur. Eğer http://localhost:3010 olarak bırakılırsa, gönderdiğiniz davet alıcıyı kendi yerel makinesine yönlendirir ve bağlantı başarısız olur. İlk başlatmadan önce bu değeri genel HTTPS adresi olarak ayarlayın; böylece dosya ile yönetim paneli arasında tutarsızlık oluşmaz. Daha sonra yönetim panelinden değiştirdiğiniz ayarlar veritabanına kaydedilir, bu dosyaya geri yazılmaz.
copilot, yapay zeka özelliklerini kontrol eder. copilot.byok.enabled, çalışma alanı sahibinin kendi model sağlayıcı anahtarını çalışma alanı ayarlarına girmesine olanak tanıyan "kendi anahtarını getir" anahtarıdır. AFFiNE self-hosting kurulumu bir yapay zeka aboneliği içermez. Eğer bu özelliği istemiyorsanız her iki ayarı da false olarak bırakın.
Stack'i başlatın:
docker compose up -d
docker compose ps --alldocker compose ps --all komutu affine_postgres ve affine_redis servislerini sağlıklı (healthy), affine_server servisini çalışıyor (running) ve affine_migration_job servisini exited (0) durumunda listelemelidir. --all önemlidir: bu parametre olmadan docker compose ps yalnızca çalışan container'ları gösterir; bu durumda başarıyla tamamlanmış bir taşıma (migration) işi listede görünmez. Taşıma işinde başka bir çıkış kodu alırsanız, sorunun kaynağı odur; günlük kayıtları durmaya neden olan adımı belirtir:
docker compose logs affine_migrationUnutmadan önce imajı sabitleyin
stable hareketli bir etikettir. AFFiNE'in sürüm iş akışı, her kararlı derlemede birden fazla etiketi günceller; bunlardan ikisi burada önem taşır: her sürümde yeniden işaretlenen stable ve git kısa hash değeri ile takip edilen stable-. stable üzerinde bırakıldığında, altı ay sonra yapılacak bir docker compose pull işlemi farklı bir imajı çeker ve veritabanı migrasyonlarını sizin seçmediğiniz bir anda çalıştırır. Test ettiğiniz imajı tam olarak sabitleyin:
docker compose pull
docker image inspect ghcr.io/toeverything/affine:stable --format '{{index .RepoDigests 0}}'Bu komut, ghcr.io/toeverything/affine@sha256: ve ardından uzun bir hash değeri içeren bir satır çıktısı verir. Tüm dizgiyi hem affine hem de affine_migration dosyalarındaki image: satırına yapıştırın. Bu iki dosya her zaman eşleşmelidir; çünkü aynı imaj iki farklı rolü üstlenmektedir ve bir uyumsuzluk, veritabanının bir şemaya göre migre edilip diğeriyle sunulması anlamına gelir. Yükseltme işlemi böylece sürpriz bir durum olmaktan çıkıp bilinçli bir düzenlemeye dönüşür: digest değerini değiştirin, yedek alın, docker compose pull komutunu çalıştırın ve docker compose up -d işlemini gerçekleştirin.
Yönetici hesabını başkası oluşturmadan önce siz oluşturun
Yeni bir kurulumda /admin adresini açtığınızda, sunucuda henüz bir yönetici bulunmadığı için AFFiNE sizi hesap oluşturma sayfasına yönlendirir. Bu akışta herhangi bir davet kodu veya kurulum belirteci (setup token) bulunmaz. Kaydı tamamlayan ilk kişi sunucunun yöneticisi olur; bu nedenle siz kaydınızı yapana kadar port kapalı tutulmalıdır.
Yukarıdaki compose dosyasının 127.0.0.1 adresine bağlanmasının nedeni budur. Buraya kendi makinenizden bir SSH tüneli aracılığıyla erişin:
ssh -L 3010:127.0.0.1:3010 you@your-server-ipTüneli açık bırakın ve yerel tarayıcınızda http://127.0.0.1:3010/admin adresini açın. Kaydolun ve giriş yapın, ardından tüneli kapatın. Ancak bu aşamadan sonra örneği herkese açık bir alan adına taşımak güvenlidir. Aynı yarış durumu diğer self-hosted uygulamalarda da mevcuttur; hatta ilk girişin ana makine adına bağlı bir passkey oluşturduğu durumlarda bu durum daha kritiktir. Bu yüzden openGym self-host kurulumu yaparken TLS ve nihai alan adı ayarlarının ilk hesaptan önce tamamlanması gerekir.
AFFiNE verilerinizi nerede tutar
Her şey üç farklı dizinde tutulur ve bunların tamamı oluşturduğunuz dizinin içerisindedir.
./data/postgres, Postgres veri dizinidir: belgeler, kullanıcılar, çalışma alanları, izinler ve yönetici panelinden kaydedilen tüm sunucu ayarları burada bulunur../data/storage, container içerisinde/root/.affine/storagedizinine mount edilir ve yüklenen tüm dosyaları barındırır../config,/root/.affine/configdizinine mount edilir veconfig.jsonile migration işi tarafından oluşturulanprivate.keydosyasını tutar.
Upstream, burada named volume yerine bind mount kullanır; bu bilinçli bir tercihtir: Docker'a dosyaların nerede olduğunu sormanıza gerek kalmadan, bu dizinleri standart komutlarla tar arşivine alabilir veya kopyalayabilirsiniz. Bunun bedeli ise ana makinedeki dosya sahipliği yönetiminin size ait olmasıdır; bu konu bind mount ve named volume bölümünde ele alınan takasın bir parçasıdır.
AFFiNE yedekleme yöntemi
Yedeklenmesi gereken iki farklı bileşen vardır ve bunlar farklı yöntemlerle yedeklenir. Veritabanı canlı bir sunucudur; bu nedenle dosyaları çalışma anında kopyalamak bozuk bir yedek oluşturmanıza neden olur. Bunun yerine bir döküm (dump) alın:
mkdir -p ~/affine/backup
cd ~/affine
docker compose exec -T postgres pg_dump --format c --username affine affine \
> backup/affine-$(date +%F).dump
ls -lh backup/Döküm işlemi container içerisinde yerel soket üzerinden gerçekleştirildiği için parola istemez. ls çıktısındaki dosya boyutunu kontrol edin. Birkaç yüz baytlık bir dosya, döküm işleminin başarısız olduğu ancak shell'in yine de boş bir dosya oluşturduğu anlamına gelir; bu, kullanıcıların genellikle altı ay sonra fark ettiği bir hatadır. -T bayrağı da önemlidir; bu bayrak olmadan Compose bir terminal tahsis edebilir ve ikili veri akışını bozabilir.
Yüklenen dosyalar sadece dosyalardan ibarettir, bu yüzden bunları tar ile arşivleyin:
tar czf backup/storage-$(date +%F).tgz -C data storage
tar czf backup/config-$(date +%F).tgz config docker-compose.yml .envTüm config dizinini, Compose dosyasını ve .env dosyasını yedeğinizde tutun; çünkü döküm dosyası bunları içermez. Taşıma (migration) işlemi ayrıca config/private.key dosyasını oluşturur, bu nedenle yalnızca config.json dosyasını kopyalamak bu dosyayı eksik bırakır. Yönetim panelinde kaydedilen ayarlar veritabanında saklanır, bu yüzden yukarıdaki döküm bunları zaten içerir. 12 Ekim 2026 itibarıyla AFFiNE yedekleme sayfası, değiştirilmiş sunucu ayarlarının yönetim panelinden de dışa aktarılabileceğini belirtmektedir. Her üç dosyayı da sunucunun dışına kopyalayın. Koruduğu verilerle aynı diskte tutulan bir yedek, yedek sayılmaz. Veritabanı dökümü ve yükleme dizininin tar arşivinden oluşan bu ayrım, çalıştırdığınız diğer tüm durum bilgisi tutan (stateful) container'lar için tekrarlanması gereken bir yöntemdir. Bu yöntem, destek masası olarak Chatwoot self-host ederken konuşma geçmişini ve ekleri güvende tutan yöntemle aynıdır.
Geri yükleme ve yayınlanan adımlardaki bir tuzak
Resmi geri yükleme adımlarını ihtiyaç duymadan önce okuyun ve dikkatle inceleyin. Ağustos 2026'da yayınlandığı şekliyle, affine.backup adlı bir dosyayı container içine kopyalayıp ardından ./pg.backup üzerinden geri yükleme yapıyorlardı; bunlar iki farklı isimdir. Ayrıca, mevcut compose dosyası verilerini ./data/postgres içinde tutarken, onlar bir ./postgres dizinini siliyorlardı. 12 Ekim 2026 itibarıyla sayfa genelinde affine.backup kullanılıyor ve geri yükleme doğrulanana kadar eski Postgres dizininin tutulması gerektiği belirtiliyor. Yani tuzak kaynakta düzeltildi, ancak bu tarihten önce kaydedilen adımların kopyaları hala bu hatayı taşıyor. Her iki durumda da, herhangi bir kod parçacığındaki yollar yerine kendi kullandığınız yolları takip edin. Bu kılavuzdaki yerleşime göre izlenecek sıra şöyledir:
cd ~/affine
docker compose down
sudo mv data/postgres data/postgres.old
docker compose up -d postgres
docker compose cp backup/affine-2026-08-08.dump postgres:/tmp/affine.dump
docker compose exec postgres pg_restore --format c --username affine \
--dbname affine --verbose /tmp/affine.dump
docker compose up -drm yerine mv kullanıldığına dikkat edin. Bir kopyasını almadığınız veritabanının üzerine geri yükleme yapmak, tek bir hatalı komutun toplam veri kaybına dönüşmesine neden olur; eski dizini kenara taşımak ise hiçbir maliyet getirmez. Yüklemeleri de tar xzf backup/storage-2026-08-08.tgz -C data ile geri yükleyin, aksi takdirde her belge bozuk eklerle görüntülenir. Ardından giriş yapın ve içinde bir görsel bulunan bir belgeyi açın. Test budur. Tarayıcıda açmadığınız bir geri yükleme, yedek değil, sadece bir dosyadır.
AFFiNE'i mevcut bir proxy arkasına almak
AFFiNE, WebSocket protokolünü kullanır ve bu zorunludur. Dokümantasyon bu konuda nettir: WebSocket, AFFiNE senkronizasyon ve iş birliği sisteminin temelidir; bu bağlantıları yükseltmeyen (upgrade) bir proxy, düzenlemelerin senkronize edilmediği bir çalışma alanı oluşturur. Sayfa yüklenir, giriş çalışır ancak bir tarayıcıda yapılan düzenleme diğerine ulaşmaz. Tarayıcınızın geliştirici araçlarında Network sekmesini açın ve WS filtresini uygulayın. Sürekli açılıp kapanan bir bağlantı, proxy'nin yükseltme işlemini gerçekleştirmediği anlamına gelir.
Diğer container'larınız için halihazırda Traefik kullanıyorsanız, AFFiNE'i normal bir servis olarak ekleyebilirsiniz. ports: bloğunu affine servisinden silin ve ardından şunları ekleyin:
networks:
- default
- proxy
labels:
- 'traefik.enable=true'
- 'traefik.docker.network=proxy'
- 'traefik.http.routers.affine.rule=Host(`affine.example.com`)'
- 'traefik.http.routers.affine.entrypoints=websecure'
- 'traefik.http.routers.affine.tls.certresolver=letsencrypt'
- 'traefik.http.services.affine.loadbalancer.server.port=3010'Dosyanın en altına, services: ile aynı hizaya şunları ekleyin:
networks:
proxy:
external: trueSertifika çözümleyici ismi, Traefik yapılandırmanızda tanımlı olanla eşleşmelidir ve loadbalancer.server.port, host portu değil, container portu olan 3010'dur. Traefik, WebSocket bağlantılarını ek bir yapılandırma gerektirmeden proxy'ler, bu yüzden başka bir işlem yapmanıza gerek yoktur. Eğer yığınınızın geri kalanı halihazırda tek oturum açma için Authentik arkasında duruyorsa, bu router üzerindeki bir forward auth middleware, tarayıcı erişimini kısıtlayacaktır. Ancak tarayıcı oturumu taşımayan ve senkronizasyon hatası verecek olan masaüstü uygulamasını test edene kadar bu özelliği kapalı tutun. Tek bir instance arkasında birden fazla uygulama çalıştırmak birden fazla uygulama için tek bir Traefik başlığında ele alınmıştır.
nginx üzerinde yükseltme işlemini açıkça belirtmeniz gerekir:
location / {
proxy_pass http://127.0.0.1:3010;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
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 100m;
}client_max_body_size, nginx üzerinde varsayılan olarak 1 MB değerindedir; bu satır olmadan küçük bir fotoğraftan büyük her yükleme 413 durumuyla başarısız olur ve istek hiç ulaşmadığı için AFFiNE günlüklerinde hiçbir şey görünmez. Caddy ise sadece reverse_proxy http://127.0.0.1:3010 satırına ihtiyaç duyar; sertifikaları ve WebSocket yükseltmelerini kendisi yönetir.
Self-hosted kurulumun eksikleri
Bir ekibi bu sisteme geçirmeden önce kendinize karşı dürüst olun.
Gerçek zamanlı iş birliği mevcuttur ve boyutlandırma tavsiyelerinin tamamı bu özellik üzerine kuruludur; çünkü AFFiNE'in kendi belgeleri bellek kullanımını senkronizasyon sistemine ve belge birleştirme işlemine bağlamaktadır. Çevrim dışı düzenleme, birçok kişinin yerel öncelikli (local-first) bir araç istemesinin temel nedenidir ve masaüstü uygulaması, self-hosted sunucunuzu çalışma alanı listenize ekleyerek giriş yapmanıza olanak tanır. Sisteme geçiş yapmadan önce ekibinizin ihtiyaç duyduğu çevrim dışı davranışları mutlaka test edin: ağ bağlantısı kapalıyken masaüstü uygulamasında düzenleme yapın, tekrar bağlanın ve sonucu ikinci bir cihaz üzerinden kontrol edin. Özellik listeleri bir kanıt niteliği taşımaz, bu liste de buna dahildir.
Sunucu tarafındaki tam metin arama özelliği, AFFINE_INDEXER_ENABLED=false değişkeninin sunucu ve migration işi üzerinde tanımlı olduğu varsayılan compose dosyasında kapalıdır. Bu özelliği açmak, beşinci bir servis olan Manticore Search container'ının eklenmesi ve dolayısıyla daha fazla bellek kullanımı anlamına gelir. 2 GB belleğe sahip bir sunucuda, sistemi sınırın ötesine taşıyacak olan değişiklik budur. İstemci tarafındaki arama, açık olan çalışma alanınızda çalışmaya devam eder.
Kullanıcıları davet etmeden önce bilinmesi gereken iki sınır vardır. Self-hosted bir çalışma alanına en fazla 10 kullanıcı tanımlanabilir; bu sayının aşılması durumunda AFFiNE'den bir Team lisansı alınması gerekir. Self-hosted kurulumlar için sınırsız blob depolama ve sınırsız blob boyutu özellikleri, Ekim 2026 itibarıyla belgelerde hedeflenen ancak henüz tam olarak uygulanmamış özellikler olarak belirtilmiştir. Bu durum, bireysel kullanıcılar veya küçük ekipler için bir sorun teşkil etmez. Ancak kırk kişilik bir ekibi taşımayı planlıyorsanız, her iki durum da önem arz eder.
Yükseltmeler
Özellikle 0.26 sürümünden 0.27 sürümüne geçiş gibi küçük sürüm güncellemelerinde, köklü değişiklikler (breaking changes) içerebileceğinden öncelikle sürüm notlarını okuyun. Herhangi bir işlem yapmadan önce veritabanını ve depolama dizinini yedekleyin; çünkü geçiş işlemi bir sonraki başlatmada şemanızı değiştirir ve bu işlemin geri dönüşü yoktur. Ardından sabitlenmiş (pinned) digest değerini değiştirin, docker compose pull komutunu ve ardından docker compose up -d komutunu çalıştırın, sonrasında docker compose logs -f affine_migration komutunun temiz bir şekilde çıkış yapmasını izleyin. docker image prune komutu, işlem sonrasında eski katmanları temizler. Çok eski bir kurulum kullananlar için tarihsel bir not: 0.23.0 sürümünden itibaren imaj adı affine-graphql yerine affine olarak değiştirilmiştir; bu nedenle daha eski bir compose dosyası kullanıyorsanız, yeni bir çekme (pull) işleminin sonuç vermesi için imaj satırlarının yeniden yazılması gerekir. Ayrıca 0.27.4 sürümünden itibaren resmi compose şablonu Postgres, yükleme ve yapılandırma yollarını taşımış ve varsayılan veritabanı bağlantısını değiştirmiştir; bu yüzden yeni dosyayı mevcut çalışan kurulumunuzun üzerine kopyalamak yerine kendi dosyanızla karşılaştırın.
FAQ
AFFiNE container'ı neden hiç başlamıyor?
affine servisi, affine_migration işi üzerinde condition: service_completed_successfully tanımlar; bu nedenle migrasyon işlemi 0 dışında bir durum koduyla sonlanırsa sunucu asla başlatılmaz ve web arayüzü görüntülenmez. Hangi adımın durduğunu görmek için docker compose logs affine_migration komutunu çalıştırın. Elle düzenlediğiniz compose dosyasının hala pgvector/pgvector:pg16 kullandığından emin olun: v0.27.4 sürümü v0.27.3'te bulunan dört embedding modelini artık tanımlamıyor olsa da, standart Postgres, AFFiNE şemasının hala talep ettiği pgvector eklentisini içermez.
Self-hosted AFFiNE ne kadar RAM gerektirir?
AFFiNE gereksinimler sayfası en az 4 CPU çekirdeği ve 2 GB RAM talep eder; belgeler 10.000 kelimeyi geçtiğinde bu ihtiyaç 4 GB'a çıkar. 10.000 değişiklik içeren bir belgeyi birleştirmenin 1 GB'lık bir tepe noktası oluşturabileceği belirtilir. 2 GB'lık bir sunucuda sistemi çökerten şey boşta çalışma yükü değil, bu tepe noktasıdır: çekirdeğin out-of-memory killer mekanizması durdurulacak bir süreç seçer, bu genellikle en büyük süreç olan AFFiNE sunucusudur ve restart: unless-stopped onu tekrar başlatır; bu yüzden kullanıcılar hata yerine sayfa yenilemesi görür. Durumu docker inspect affine_server --format '{{.State.OOMKilled}}' ve sudo dmesg -T | grep -i 'out of memory' ile doğrulayın, ardından kısa süreli ani yüklenmelere karşı tampon olarak 2 GB swap dosyası ekleyin; çökmeler devam ederse 4 GB RAM'e geçin.
AFFiNE verilerimi nerede saklıyor ve neleri yedeklemeliyim?
Compose dizininiz altındaki üç yol her şeyi barındırır: veritabanı için ./data/postgres, yüklenen dosyalar için ./data/storage ve config.json ile oluşturulan private.key için ./config. Çalışan bir Postgres kopyalanamayacağı için veritabanını dosya kopyalamak yerine docker compose exec -T postgres pg_dump --format c --username affine affine > affine.dump ile yedekleyin. AFFiNE ayarları veritabanında sakladığı için bu dump, yönetici panelinde kaydedilen tüm ayarları da içerir. Yüklemeler için ./data/storage dizinini tar ile arşivleyin ve tüm config dizinini, Compose dosyasını ve .env dosyasını saklayın; çünkü bu dosyalar veritabanının bir parçası değildir.
Self-hosted AFFiNE üzerinde gerçek zamanlı iş birliği çalışıyor mu?
Evet, bunun için herhangi bir ayar yapılması gerekmez. Tek gereksinim reverse proxy yapılandırmanızdır, çünkü senkronizasyon WebSocket bağlantıları üzerinden yürütülür. Nginx üzerinde bu, proxy_http_version 1.1 ile birlikte Upgrade ve Connection: upgrade başlıklarının ayarlanması anlamına gelir; Traefik ve Caddy ise bu bağlantıları ek bir yapılandırma gerektirmeden iletir. Bağlantıları yükseltmeyen (upgrade) bir proxy'nin belirtisi, çalışma alanının normal şekilde yüklenip giriş yapılmasına rağmen bir tarayıcıda yapılan düzenlemelerin diğerinde asla görünmemesidir.
AFFiNE'i standart bir Postgres imajı ile çalıştırabilir miyim?
pgvector eklentisi derlenmiş Postgres 16 olan pgvector/pgvector:pg16 kullanın. AFFiNE v0.27.4, schema.prisma içerisinde hala extensions = [pgvector(map: "vector")] tanımlar ancak v0.27.3'te bulunan vector(1024) embedding sütunlarına sahip dört modeli artık tanımlamaz. Standart Postgres, talep edilen eklentiyi içermez. Eğer AFFiNE'i harici bir Postgres sunucusuna yönlendiriyorsanız, o sunucuya pgvector kurun ve migrasyonu çalıştırmadan önce hedef veritabanında eklentiyi oluşturun.