SSD Nodes Learn Hosting plans →
Panduan Matt ConnorOleh Matt Connor

Self-host AFFiNE: Workspace seperti Notion

Jalankan AFFiNE di satu VPS dengan Docker Compose: empat container, tag image yang dipatok, lokasi data, pencadangan, dan kapasitas nyata RAM 2 GB.

Hasil self-hosting AFFiNE

Self-hosting AFFiNE memberi Anda workspace bergaya Notion pada server yang Anda kendalikan. AFFiNE berjalan sebagai empat container: aplikasi, job migrasi sekali jalan, Postgres, dan Redis. Kolaborasi real-time sudah tersedia, hingga 10 seat yang secara default diberikan kepada workspace self-hosted. Instalasinya terdiri atas satu file compose dan satu file konfigurasi JSON. Hal yang perlu diperhatikan adalah tag image, tata letak disk, batas memori, dan proxy yang ditempatkan di depannya.

AFFiNE menggabungkan editor dokumen dan kanvas tanpa batas dalam workspace yang sama. Dengan demikian, satu halaman dapat dibaca sebagai dokumen atau dibentangkan sebagai whiteboard. Jika Anda masih menentukan layanan yang akan dijalankan, baca perbandingan alternatif Notion self-hosted terlebih dahulu. Panduan ini mengasumsikan bahwa pilihan tersebut sudah ditetapkan. Fokusnya adalah menjalankan AFFiNE dengan benar, bukan membandingkannya kembali.

Semua informasi di sini diperiksa berdasarkan dokumentasi self-host AFFiNE dan file rilis yang dipublikasikan pada 8 August 2026. Rilis stabil terbaru pada tanggal tersebut adalah 0.27.3, yang dipublikasikan pada 23 July 2026. Klaim di bawah yang mencantumkan tanggal setelahnya diperiksa kembali berdasarkan sumber primernya pada 12 October 2026. Pada saat itu, rilis stabil terbaru adalah 0.27.4, yang dipublikasikan pada 18 August 2026.

Apa yang sebenarnya dilakukan keempat container

affine adalah server dan klien web dalam satu image. Container ini mendengarkan pada port 3010.

affine_migration adalah job sekali jalan yang menjalankan node ./scripts/self-host-predeploy.js, menerapkan migrasi database, lalu berhenti. Aplikasi mendeklarasikan condition: service_completed_successfully pada job tersebut. Karena itu, migrasi yang berhenti dengan status non-zero berarti affine sama sekali tidak akan dimulai. Jika antarmuka web tidak dapat diakses, log job tersebut adalah hal pertama yang harus dibaca.

postgres menyimpan dokumen, pengguna, workspace, dan permission Anda. Image yang disediakan adalah pgvector/pgvector:pg16, yaitu Postgres 16 biasa dengan ekstensi pgvector yang sudah dikompilasi di dalamnya. pgvector menambahkan tipe kolom vector ke Postgres. Tipe ini menyimpan embedding dalam bentuk numerik agar teks dapat dicari berdasarkan maknanya.

redis adalah dependensi wajib. Server dan job migrasi sama-sama menunggu health check-nya sebelum mulai. Perhatikan bahwa file compose yang disediakan tidak memberikan volume kepada Redis. Tidak ada data di dalamnya yang bertahan setelah docker compose down. Ini menunjukkan bahwa Redis tidak menyimpan konten milik Anda dan tidak memerlukan backup.

Mengapa image Postgres adalah pgvector, bukan postgres standar

Persyaratan ini berasal dari skema AFFiNE, bukan dari preferensi. Pada v0.27.4, schema.prisma masih mendeklarasikan extensions = [pgvector(map: "vector")], tetapi tidak berisi kolom embedding. Empat model dengan kolom embedding bertipe vector(1024) pada v0.27.3 tidak ada pada v0.27.4. Gunakan image pgvector/pgvector:pg16 yang disediakan: ekstensi tersebut masih dideklarasikan, sedangkan postgres:16 standar tidak menyertakannya.

Template resmi v0.27.4 menggunakan image pgvector; template v0.21.0 masih menggunakan postgres:16. Pada instalasi lama, mengedit baris image saja tidak cukup untuk melakukan upgrade. Oleh karena itu, baca halaman upgrade pada dokumentasi self-host AFFiNE sebelum melakukan pull.

Ada satu hal lagi tentang tag tersebut. pg16 berarti Postgres 16, dan versi mayor Postgres bukan angka yang dapat dinaikkan begitu saja. Jika Anda mengubahnya menjadi pg17 pada data directory yang sudah ada, Postgres menolak untuk start, dengan baris seperti The data directory was initialized by PostgreSQL version 16, which is not compatible with this version 17 di docker compose logs postgres. Perpindahan versi mayor memerlukan salah satu dari tiga metode yang disebutkan dalam catatan rilis PostgreSQL 17: dump dan restore ke data directory baru, pg_upgrade, atau replikasi logis. Pada satu instalasi Compose, dump dan restore biasanya merupakan metode paling sederhana karena pg_upgrade memerlukan binary server lama dan baru secara berdampingan.

Kebutuhan CPU dan RAM untuk AFFiNE yang di-hosting sendiri

Halaman persyaratan AFFiNE meminta setidaknya 4 core CPU dan 2 GB RAM, lalu menaikkan kebutuhan memori menjadi 4 GB setelah dokumen Anda melebihi 10.000 kata. Halaman yang sama menjelaskan penggunaan memori tersebut: sistem sinkronisasi dan penggabungan dokumen. Halaman itu juga mencantumkan satu angka yang perlu diingat, yaitu penggabungan dokumen dengan 10.000 modifikasi dapat mencapai puncak penggunaan 1 GB.

Bandingkan angka tersebut dengan paket 2 GB yang digunakan oleh dua orang untuk menulis. Penggunaan rata-ratanya tidak bermasalah. Postgres dan proses Node tetap berada di bawah batas dengan sisa ruang. Masalahnya terjadi pada penggunaan puncak. Satu operasi penggabungan besar dapat meningkatkan penggunaan memori server hingga sekitar 1 GB. Pada server dengan RAM 2 GB tanpa swap, penggunaan puncak tersebut, ditambah Postgres dan proses lain yang berada di memori, dapat menghabiskan seluruh memori. Kernel kemudian menjalankan pembunuh out-of-memory (OOM) untuk membebaskan memori. Server AFFiNE, sebagai proses terbesar, kemungkinan besar akan menjadi korbannya, meskipun dokumentasi Docker menjelaskan bahwa proses apa pun dapat dipilih, termasuk Docker itu sendiri.

Jika yang dihentikan adalah server AFFiNE, rekan Anda tidak melihat pesan error. Halaman hanya dimuat ulang karena restart: unless-stopped menghidupkan kembali container dalam hitungan detik. Jangan menebak. Konfirmasikan hal ini:

docker inspect affine_server --format '{{.State.OOMKilled}} {{.RestartCount}}'
sudo dmesg -T | grep -i -E 'out of memory|killed process'

true dari perintah pertama, atau baris Killed process yang menyebut node dari perintah kedua, berarti memori Anda habis, bukan berarti Anda menemukan bug. Perbaiki masalah ini dari kedua sisi. Tambahkan swap terlebih dahulu agar lonjakan penggunaan memiliki ruang untuk dialihkan sebelum OOM killer bertindak:

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 -h

free -h sekarang seharusnya melaporkan total swap sebesar 2.0Gi. Swap tidak membuat AFFiNE berjalan lebih cepat, dan memang bukan itu tujuannya. Swap menyediakan tempat sementara untuk lonjakan penggunaan, sehingga lonjakan tersebut jauh lebih mungkin hanya menyebabkan perlambatan selama satu detik daripada mematikan container. Swap adalah penyangga, bukan jaminan. Sisi perbaikan lainnya adalah mencegah Postgres memperbesar cache hingga menggunakan ruang yang dibutuhkan aplikasi saat penggabungan berlangsung. Untuk itulah batas memori pada service Compose digunakan. Jika proses penghentian masih terjadi setelah kedua langkah tersebut, server memerlukan 4 GB sesuai persyaratan AFFiNE untuk dokumen yang lebih besar.

Kebutuhan storage jauh lebih mudah diperkirakan. Berikut angka yang dipublikasikan AFFiNE pada halaman yang sama:

GrafikPublished AFFiNE storage figures, August 2026
Data di balik grafik ini
[
  {
    "label": "Server install",
    "gb": 1.5
  },
  {
    "label": "Postgres per 1,000 docs",
    "gb": 0.1
  },
  {
    "label": "Blob store per 1,000 uploads",
    "gb": 10
  }
]

Instalasi server memerlukan 1.5 GB. Seribu dokumen dengan panjang sekitar seribu kata masing-masing menambah 0.1 GB data Postgres, yang hampir tidak berarti. Seribu file yang diunggah menambah 10 GB, dan itulah faktor utamanya. Angka ini merupakan perkiraan perencanaan yang dipublikasikan, bukan hasil pengukuran dari instance yang sedang berjalan. Karena itu, gunakan angka tersebut untuk memahami polanya, bukan sebagai jaminan. Polanya yang penting: database Anda tetap kecil, sedangkan file yang diunggah menentukan kebutuhan disk.

Tulis file compose sendiri dengan tag yang dipatok

Dokumentasi instalasi mengunduh file siap pakai dengan curl -L -o docker-compose.yml https://github.com/toeverything/AFFiNE/releases/latest/download/docker-compose.yml. Cara ini berfungsi. Namun, ada satu hal yang perlu diketahui sebelum Anda mengandalkannya: per 8 August 2026, file yang dilampirkan pada release 0.27.3 masih membaca path dari file .env menggunakan ${UPLOAD_LOCATION}, ${CONFIG_LOCATION}, dan ${DB_DATA_LOCATION}, sedangkan halaman referensi dokumentasi menampilkan tata letak yang lebih baru. Tata letak tersebut menempatkan storage dan data PostgreSQL di bawah ./data, menyimpan konfigurasi di bawah ./config, dan tidak memerlukan .env sama sekali. Release 0.27.4 memindahkan file yang dilampirkan ke tata letak tersebut. Per 12 October 2026, keduanya sudah sesuai. Jika Anda menginstal dari file lama, path Anda masih berasal dari .env. Halaman upgrade AFFiNE memperingatkan bahwa mengganti file compose tanpa mempertahankan pengaturan tersebut dapat membuat Postgres berjalan dengan direktori data kosong. Menulis file sendiri menghindari masalah tersebut. Anda juga memang harus mengeditnya untuk mematok image dan menetapkan password database.

mkdir -p ~/affine/config ~/affine/data
cd ~/affine
printf 'DB_PASSWORD=%s\n' "$(openssl rand -hex 24)" > .env
chmod 600 .env

Compose membaca .env dari direktori project secara otomatis dan mengganti ${DB_PASSWORD} untuk Anda. Dengan demikian, password tidak pernah muncul di file yang Anda tempel ke thread dukungan. Pertahankan kebiasaan ini pada setiap stack yang Anda jalankan. Alasannya dijelaskan dalam menyimpan secret di luar file compose.

Sekarang tulis ~/affine/docker-compose.yml:

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-stopped

Ada empat perbedaan dari file yang dirilis upstream, dan masing-masing memiliki alasan.

  • 127.0.0.1:3010:3010 hanya memublikasikan port pada alamat loopback. Docker sebelum versi 28.0.0 memungkinkan host pada segmen L2 yang sama mengakses port yang dipublikasikan ke localhost. Konfigurasi direct routing juga dapat mengekspos port container meskipun port tersebut dipublikasikan ke loopback. Gunakan Docker 28.0.0 atau yang lebih baru dan tetap nonaktifkan direct routing selama penyiapan. '3010:3010' dari upstream mengikat setiap interface. Pada sebagian besar image VPS, ini mencakup interface publik.
  • POSTGRES_HOST_AUTH_METHOD: trust dihapus dan password ditetapkan sebagai gantinya. Autentikasi trust menerima koneksi apa pun ke database tersebut sebagai user affine tanpa password. Akses ini dibatasi ke jaringan Compose privat. Namun, kondisi tersebut dapat menjadi masalah ketika Anda menambahkan satu container lagi ke jaringan itu atau memublikasikan 5432 saat melakukan debugging.
  • redis:8-alpine menggantikan redis yang tidak memiliki versi, yang mengarah ke latest. Per August 2026, versi tersebut adalah Redis 8. Pematokan ini mempertahankan major version yang telah Anda uji dan mencegah Redis 9 terpasang saat terjadi docker compose pull yang tidak terkait.
  • pgvector/pgvector:pg16 tetap persis seperti yang ditetapkan upstream karena alasan yang dijelaskan di atas.

POSTGRES_PASSWORD hanya dibaca ketika Postgres membuat direktori datanya untuk pertama kali. Pada instance yang sudah ada, tetapkan password dengan docker compose exec postgres psql -U affine -c "ALTER USER affine WITH PASSWORD 'yourpassword'", lalu perbarui DATABASE_URL agar sesuai.

Konfigurasi disimpan di config/config.json

AFFiNE membaca pengaturannya dari config/config.json, yaitu direktori yang Anda mount ke /root/.affine/config. File tersebut tidak dibuat secara otomatis, jadi buat file itu sebelum menjalankan aplikasi untuk pertama kali. Buka ~/affine/config/config.json di editor, lalu isi dengan konten berikut. Ganti contoh domain dengan domain Anda sendiri:

{
  "$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 harus berupa alamat yang benar-benar dibuka pengguna di browser. AFFiNE membuat tautan berbagi dan undangan workspace berdasarkan nilai tersebut. Jika nilainya tetap http://localhost:3010, undangan yang Anda kirim akan mengarahkan penerima ke komputer mereka sendiri dan gagal dibuka. Tetapkan alamat HTTPS publik sebelum menjalankan aplikasi untuk pertama kali agar isi file dan panel admin selalu konsisten. Pengaturan yang Anda ubah melalui panel admin selanjutnya disimpan di database, bukan ditulis kembali ke file ini.

copilot mengontrol fitur AI. copilot.byok.enabled adalah opsi bring-your-own-key yang memungkinkan pemilik workspace memasukkan key penyedia model mereka sendiri ke pengaturan workspace. Self-hosting AFFiNE tidak menyediakan langganan AI. Biarkan keduanya false jika Anda tidak membutuhkannya.

Jalankan stack:

docker compose up -d
docker compose ps --all

docker compose ps --all harus menampilkan affine_postgres dan affine_redis sebagai sehat, affine_server sebagai berjalan, serta affine_migration_job dengan status exited (0). Opsi --all penting. Tanpa opsi tersebut, docker compose ps hanya menampilkan container yang sedang berjalan, sehingga job migrasi yang selesai dengan baik tidak akan ditampilkan. Kode keluar lain pada job migrasi harus segera diperiksa. Log job tersebut menunjukkan langkah yang berhenti:

docker compose logs affine_migration

Tetapkan image sebelum lupa

stable adalah tag yang dapat berubah. Alur rilis AFFiNE menunjuk beberapa tag ke setiap build stabil, dan dua di antaranya penting di sini: stable, yang diarahkan ulang pada setiap rilis, dan stable- yang diikuti hash singkat git, yang tidak berubah. Jika tetap menggunakan stable, docker compose pull enam bulan dari sekarang akan mengambil image yang berbeda dan menjalankan migrasinya terhadap database pada waktu yang tidak Anda tentukan. Tetapkan image persis yang telah Anda uji:

docker compose pull
docker image inspect ghcr.io/toeverything/affine:stable --format '{{index .RepoDigests 0}}'

Perintah tersebut mencetak baris seperti ghcr.io/toeverything/affine@sha256: yang diikuti hash panjang. Salin seluruh string tersebut ke baris image: pada keduanya, yaitu affine dan affine_migration. Keduanya harus selalu sama karena merupakan image yang sama dengan dua peran berbeda. Ketidaksesuaian berarti database dimigrasikan ke satu skema, tetapi dilayani dengan skema lain. Dengan demikian, upgrade menjadi perubahan yang dilakukan secara sengaja, bukan kejutan: ubah digest, buat cadangan, docker compose pull, docker compose up -d.

Buat akun admin sebelum orang lain melakukannya

Buka /admin pada instance baru. AFFiNE akan mengarahkan Anda ke halaman pembuatan akun karena server tersebut belum memiliki administrator. Alur ini tidak menggunakan kode undangan atau token setup. Orang pertama yang menyelesaikan pendaftaran akan menjadi administrator server Anda. Karena itu, port harus tetap tertutup sampai Anda selesai mendaftar.

Itulah alasan file compose di atas mengikat ke 127.0.0.1. Akses alamat tersebut melalui tunnel SSH dari mesin Anda sendiri:

ssh -L 3010:127.0.0.1:3010 you@your-server-ip

Biarkan proses tersebut tetap berjalan, lalu buka http://127.0.0.1:3010/admin di browser lokal Anda. Daftar dan login, kemudian tutup tunnel. Setelah itu, barulah aman untuk menempatkan instance pada nama publik. Risiko yang sama juga terdapat pada aplikasi self-hosted lainnya. Risikonya lebih besar pada aplikasi yang membuat passkey pertama dan mengikatnya ke hostname saat login pertama. Karena itu, TLS dan domain final harus ditetapkan sebelum akun pertama dibuat saat Anda meng-host openGym sendiri.

Lokasi penyimpanan data AFFiNE

Tiga path menyimpan seluruh data, dan semuanya berada di dalam direktori yang Anda buat.

  • ./data/postgres adalah direktori data Postgres: dokumen, pengguna, workspace, izin, dan pengaturan server yang disimpan melalui panel admin.
  • ./data/storage di-mount pada /root/.affine/storage di dalam container dan menyimpan semua file yang diunggah.
  • ./config di-mount pada /root/.affine/config dan menyimpan config.json serta private.key yang dibuat oleh migration job.

Upstream menggunakan bind mount di sini, bukan named volume, dan pilihan ini disengaja: Anda dapat membuat arsip tar dan menyalin path tersebut dengan perintah biasa, tanpa meminta Docker menunjukkan lokasi penyimpanannya. Konsekuensinya, Anda harus menangani ownership file pada host. Trade-off ini dibahas dalam bind mount dan named volume.

Cara mencadangkan AFFiNE

Ada dua hal yang perlu dicadangkan, dan metode pencadangannya berbeda. Database adalah server aktif, sehingga menyalin file-nya saat server berjalan akan menghasilkan salinan yang korup. Gunakan dump sebagai gantinya:

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/

Dump dijalankan di dalam container melalui local socket, sehingga tidak meminta password. Periksa ukurannya pada output ls tersebut. File berukuran beberapa ratus byte berarti dump gagal, tetapi shell tetap membuat file. Kegagalan ini sering baru diketahui enam bulan kemudian. -T juga penting: tanpa opsi tersebut, Compose dapat mengalokasikan terminal dan merusak binary stream.

Uploaded files hanyalah file, jadi arsipkan dengan tar:

tar czf backup/storage-$(date +%F).tgz -C data storage
tar czf backup/config-$(date +%F).tgz config docker-compose.yml .env

Simpan seluruh direktori config, file Compose, dan .env dalam backup Anda karena dump tidak memuat semua itu. Migration job juga membuat config/private.key, sehingga hanya menyalin config.json akan membuat file tersebut tidak ikut tersalin. Pengaturan yang disimpan di admin panel berada di database, sehingga dump di atas sudah mencakupnya. Per 12 October 2026, halaman backup AFFiNE juga menyatakan bahwa server settings yang telah diubah dapat diekspor dari admin panel. Salin ketiga file tersebut ke luar server. Backup yang disimpan pada disk yang sama dengan data yang dilindunginya bukanlah backup. Pemisahan antara database dump dan arsip tar dari direktori uploads ini adalah pola yang perlu diulangi pada setiap stateful container lain yang Anda jalankan. Pola yang sama menjaga conversation history dan attachments tetap aman saat Anda menjalankan Chatwoot sendiri sebagai support desk.

Pemulihan dan satu jebakan pada langkah yang dipublikasikan

Baca langkah pemulihan resmi sebelum Anda membutuhkannya, dan baca dengan teliti. Dalam versi yang dipublikasikan pada Agustus 2026, langkah tersebut menyalin file bernama affine.backup ke dalam container, lalu memulihkan dari ./pg.backup. Keduanya adalah nama yang berbeda. Langkah tersebut juga menghapus direktori ./postgres, sedangkan file compose saat ini menyimpan datanya di ./data/postgres. Per 12 Oktober 2026, halaman tersebut menggunakan affine.backup secara konsisten dan menyatakan bahwa direktori Postgres lama harus dipertahankan sampai pemulihan diverifikasi. Jadi, jebakan tersebut sudah diperbaiki di upstream, tetapi salinan langkah yang disimpan sebelum tanggal itu masih memuatnya. Bagaimanapun, gunakan path yang benar-benar Anda gunakan, bukan path yang tercantum dalam snippet. Berikut urutannya untuk layout dalam panduan ini:

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 -d

Perhatikan penggunaan mv, bukan rm. Memulihkan database tanpa menyimpan salinannya terlebih dahulu dapat mengubah satu perintah yang keliru menjadi kehilangan seluruh data. Memindahkan direktori lama ke lokasi lain tidak membutuhkan biaya apa pun. Pulihkan juga file upload dengan tar xzf backup/storage-2026-08-08.tgz -C data. Jika tidak, setiap dokumen akan menampilkan lampiran yang rusak. Kemudian login dan buka dokumen yang berisi gambar. Itulah pengujiannya. Pemulihan yang belum dibuka di browser hanyalah file, bukan backup.

Menempatkan AFFiNE di belakang proxy yang sudah Anda jalankan

AFFiNE menggunakan WebSocket, dan fitur ini wajib tersedia. Dokumentasinya menjelaskannya secara tegas: WebSocket adalah dasar sistem sinkronisasi dan kolaborasi AFFiNE. Proxy yang tidak melakukan upgrade koneksi tersebut akan menghasilkan workspace yang berhenti melakukan sinkronisasi tanpa pesan. Halaman tetap dimuat, login tetap berfungsi, tetapi perubahan yang dibuat di satu browser tidak pernah sampai ke browser lain. Buka tab Network di developer tools browser Anda, lalu filter ke WS. Koneksi yang berulang kali terbuka lalu tertutup menunjukkan bahwa proxy tidak meneruskan upgrade.

Jika Anda sudah menjalankan Traefik untuk container lain, AFFiNE dapat ditambahkan sebagai service biasa. Hapus blok ports: dari service affine, lalu tambahkan:

    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'

Di bagian bawah file, sejajar dengan services:, tambahkan:

networks:
  proxy:
    external: true

Nama certificate resolver harus sama dengan yang ditentukan dalam konfigurasi Traefik, dan loadbalancer.server.port adalah port container 3010, bukan port host. Traefik mem-proxy koneksi WebSocket tanpa konfigurasi tambahan, jadi tidak ada yang perlu ditambahkan lagi. Jika stack Anda yang lain sudah berada di belakang Authentik untuk single sign-on, middleware forward auth pada router ini dapat membatasi akses browser ke AFFiNE. Namun, biarkan middleware tersebut nonaktif sampai Anda menguji aplikasi desktop, karena aplikasi desktop tidak memiliki sesi browser dan akan gagal melakukan sinkronisasi. Cara menjalankan beberapa aplikasi di belakang satu instance Traefik dibahas dalam satu Traefik di depan beberapa aplikasi.

Pada nginx, Anda harus meminta upgrade secara eksplisit:

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 secara default bernilai 1 MB di nginx. Tanpa baris tersebut, setiap upload yang lebih besar daripada foto kecil akan gagal dengan status 413, dan tidak ada apa pun yang muncul dalam log AFFiNE karena request tersebut tidak pernah sampai ke aplikasi. Caddy memerlukan satu baris, reverse_proxy http://127.0.0.1:3010, dan menangani sertifikat serta upgrade WebSocket secara otomatis.

Hal yang tidak disertakan dalam build self-hosted

Pahami hal ini dengan jujur sebelum Anda memindahkan sebuah tim.

Kolaborasi real-time tersedia. Fitur inilah yang menjadi dasar seluruh saran terkait sizing, karena dokumentasi AFFiNE sendiri mengaitkan penggunaan memori dengan sistem sinkronisasi dan penggabungan dokumen. Pengeditan offline adalah alasan banyak orang menginginkan tool local-first. Aplikasi desktop dapat menambahkan server self-hosted Anda ke daftar workspace dan melakukan login ke server tersebut. Uji perilaku offline yang benar-benar dibutuhkan oleh tim sebelum Anda memutuskan: edit dokumen di aplikasi desktop saat jaringan nonaktif, sambungkan kembali jaringan, lalu periksa hasilnya pada perangkat kedua. Daftar fitur bukan bukti, termasuk daftar ini.

Pencarian full-text di sisi server dinonaktifkan dalam file compose yang disertakan. Pada file tersebut, AFFINE_INDEXER_ENABLED=false ditetapkan di server dan pada migration job. Untuk mengaktifkannya, tambahkan container Manticore Search. Ini menjadi service kelima dan membutuhkan memori tambahan. Pada server dengan RAM 2 GB, perubahan ini dapat membuat penggunaan sumber daya melewati batas. Pencarian di dalam client tetap berfungsi pada workspace yang sedang Anda buka.

Ada 2 batasan yang perlu diketahui sebelum Anda mengundang pengguna. Sebuah workspace self-hosted dapat memiliki paling banyak 10 seat. Jika jumlahnya melebihi batas tersebut, Anda memerlukan lisensi Team dari AFFiNE. Dokumentasi menjelaskan bahwa blob storage tanpa batas dan ukuran blob tanpa batas untuk instance self-hosted direncanakan, tetapi belum sepenuhnya diimplementasikan saat diperiksa pada Oktober 2026. Keduanya tidak penting untuk rumah tangga atau tim kecil. Namun, keduanya penting jika Anda berencana memindahkan 40 orang.

Pembaruan

Baca catatan rilis terlebih dahulu, terutama untuk kenaikan versi minor seperti 0.26 ke 0.27, karena perubahan yang tidak kompatibel diperkenalkan pada tahap ini. Cadangkan database dan direktori penyimpanan sebelum melakukan perubahan apa pun, karena tugas migrasi akan mengubah skema saat aplikasi dijalankan berikutnya dan perubahan tersebut tidak dapat dibatalkan. Selanjutnya, ubah digest yang dipatok, jalankan docker compose pull lalu docker compose up -d, dan pantau docker compose logs -f affine_migration hingga selesai tanpa error. docker image prune akan menghapus layer lama setelah itu. Catatan historis bagi pengguna instalasi yang sangat lama: mulai versi 0.23.0, nama image berubah dari affine-graphql menjadi affine, sehingga file compose yang lebih lama dari versi tersebut perlu diperbarui pada baris image sebelum proses pull dapat menemukan image yang sesuai. Mulai versi 0.27.4, template compose resmi memindahkan path Postgres, upload, dan konfigurasi serta mengubah koneksi database default. Karena itu, bandingkan file baru dengan file Anda, bukan menimpanya pada instalasi yang masih berfungsi.

FAQ

Mengapa container AFFiNE tidak pernah berjalan?

Service affine mendeklarasikan condition: service_completed_successfully pada job affine_migration. Jika migrasi selesai dengan status apa pun selain 0, server tidak pernah dijalankan dan antarmuka web sama sekali tidak muncul. Jalankan docker compose logs affine_migration untuk melihat langkah yang berhenti. Pastikan file Compose yang diedit secara manual masih menggunakan pgvector/pgvector:pg16. Postgres standar tidak menyertakan ekstensi pgvector yang masih dideklarasikan oleh skema AFFiNE, meskipun v0.27.4 tidak lagi mendefinisikan empat model embedding yang ada di v0.27.3.

Berapa banyak RAM yang diperlukan AFFiNE yang di-host sendiri?

Halaman persyaratan AFFiNE meminta setidaknya 4 core CPU dan 2 GB RAM. Kebutuhan ini meningkat menjadi 4 GB ketika dokumen melebihi 10,000 kata. Halaman tersebut juga mencatat bahwa penggabungan dokumen dengan 10,000 modifikasi dapat mencapai penggunaan 1 GB. Pada server dengan RAM 2 GB, lonjakan itulah yang menyebabkan masalah, bukan beban saat idle. Kernel out-of-memory killer memilih proses untuk dihentikan, kemungkinan besar server AFFiNE karena merupakan proses terbesar. Kemudian restart: unless-stopped menjalankannya kembali, sehingga pengguna melihat pemuatan ulang halaman, bukan pesan error. Konfirmasikan hal ini dengan docker inspect affine_server --format '{{.State.OOMKilled}}' dan sudo dmesg -T | grep -i 'out of memory'. Setelah itu, tambahkan file swap 2 GB sebagai penyangga terhadap lonjakan singkat. Tingkatkan RAM menjadi 4 GB jika proses masih dihentikan.

Di mana AFFiNE menyimpan data saya, dan apa yang harus dicadangkan?

Tiga path di bawah direktori Compose menyimpan semuanya: ./data/postgres untuk database, ./data/storage untuk file yang diunggah, serta ./config untuk config.json dan private.key yang dihasilkan. Cadangkan database dengan docker compose exec -T postgres pg_dump --format c --username affine affine > affine.dump, bukan dengan menyalin file, karena Postgres yang sedang berjalan tidak dapat disalin dengan aman. Dump tersebut juga menyimpan pengaturan yang disimpan di panel admin, karena AFFiNE menyimpannya di database. Buat arsip Tar dari ./data/storage untuk file yang diunggah. Simpan seluruh direktori config, file Compose, dan .env, karena file-file tersebut bukan bagian dari database.

Apakah kolaborasi real-time berfungsi pada AFFiNE yang di-host sendiri?

Ya, dan tidak ada fitur yang perlu diaktifkan. Satu-satunya persyaratan adalah reverse proxy, karena sinkronisasi berjalan melalui koneksi WebSocket. Pada nginx, ini berarti proxy_http_version 1.1 beserta header Upgrade dan Connection: upgrade. Traefik dan Caddy meneruskan koneksi tersebut tanpa konfigurasi tambahan. Jika proxy tidak melakukan upgrade koneksi, workspace akan dimuat dan login berjalan normal, tetapi edit yang dibuat di satu browser tidak pernah muncul di browser lain.

Dapatkah saya menjalankan AFFiNE dengan image Postgres standar?

Gunakan pgvector/pgvector:pg16, yaitu Postgres 16 dengan ekstensi pgvector yang telah dikompilasi. AFFiNE v0.27.4 masih mendeklarasikan extensions = [pgvector(map: "vector")] di schema.prisma, tetapi tidak lagi mendefinisikan empat model dengan kolom embedding vector(1024) yang ada di v0.27.3. Postgres standar tidak menyertakan ekstensi yang dideklarasikan tersebut. Jika AFFiNE diarahkan ke server Postgres eksternal, instal pgvector di server tersebut dan buat ekstensi pada database target sebelum menjalankan migrasi.

Apakah artikel ini bermanfaat?