AFFiNE Deployment Options: Self-Hosting, Docker, and Cloud Setup Guide

AFFiNE supports three primary deployment modes: self-hosted Docker Compose for local infrastructure, production-grade Helm charts for Kubernetes clusters, and the fully managed AFFiNE Cloud SaaS platform.

The open-source AFFiNE repository (toeverything/AFFiNE) provides production-ready infrastructure templates that let you run the workspace platform anywhere—from a local development machine to a scaled cloud-native environment. This guide covers the technical implementation details, configuration files, and deployment workflows found in the source code.

Self-Hosted Docker Compose Deployment

The quickest way to deploy AFFiNE on-premises uses the official Docker Compose configuration. This setup orchestrates the server, database, cache, and migration services with a single command.

Architecture and Configuration Files

The self-hosting configuration lives in .docker/selfhost/compose.yml. This file defines four essential services:

• affine: The main NestJS server container (ghcr.io/toeverything/affine)
• postgres: PostgreSQL 16 with pgvector extension for relational data and AI embeddings
• redis: In-memory cache for sessions and pub/sub events
• affine_migration: A one-shot job that runs scripts/self-host-predeploy.js to apply database schema changes before the server starts

Configuration is managed through an .env file (template provided at .docker/selfhost/.env.example). Critical variables include DB_USERNAME, DB_PASSWORD, UPLOAD_LOCATION for file storage, and PORT (defaults to 3010).

Quick Start Commands

# Clone the repository and navigate to the self-host directory

git clone https://github.com/toeverything/AFFiNE.git
cd AFFiNE/.docker/selfhost

# Copy and configure environment variables

cp .env.example .env

# Edit .env to set DB_PASSWORD, UPLOAD_LOCATION=/data/affine, etc.

# Deploy the stack

docker compose up -d

The server becomes available at http://localhost:3010. The compose file ensures the migration job completes successfully before starting the main application container.

Kubernetes Deployment with Helm

For high-availability production environments, AFFiNE provides a Helm chart located at .github/helm/affine/. This deployment option supports horizontal scaling, automated TLS, and cloud-native monitoring.

Helm Chart Structure and Values

The values.yaml file controls the deployment topology. Key configuration includes:

• global.deployment.type: Set to selfhosted for private instances (default is affine for cloud deployments)
• global.deployment.platform: Supports gcp, aws, or custom Kubernetes clusters
• database and redis sections: Configure resource limits and persistence settings
• ingress: Define hostnames and TLS certificate management

Deploying to a Cluster

# Clone and enter the Helm chart directory

git clone https://github.com/toeverything/AFFiNE.git
cd AFFiNE/.github/helm/affine

# Install with self-hosted configuration

helm upgrade --install affine . \
  --set global.deployment.type=selfhosted \
  --set global.deployment.platform=gcp \
  --set ingress.enabled=true \
  --set ingress.hosts[0].host=affine.yourdomain.com

The Helm chart deploys the same four core components as Docker Compose but adds Kubernetes-native features like Pod Disruption Budgets, Horizontal Pod Autoscaling, and configurable replica counts for the server deployment.

AFFiNE Cloud (SaaS)

The third deployment option requires no local infrastructure. AFFiNE Cloud runs the same server image behind a managed multi-tenant platform accessible at affine.pro. This option eliminates maintenance overhead but provides less customization than self-hosted alternatives.

Core Components Across All Deployments

Every deployment method—Docker Compose, Helm, or Cloud—relies on the same architectural stack:

Server (@affine/server): A NestJS-based backend exposing REST, GraphQL, and WebSocket APIs. The entry point at packages/backend/server/src/main.ts initializes the application and connects to dependent services.

OctoBase (Rust): A high-performance CRDT-based storage engine that persists block-level data. It runs as a native binary inside the server container, storing data at the ${UPLOAD_LOCATION} path mounted from the host or persistent volume.

PostgreSQL with pgvector: Stores relational data including user accounts, workspace definitions, and vector embeddings. The Docker Compose uses pgvector/pgvector:pg16; Helm charts deploy the same image with configurable resource limits.

Redis: Provides fast session storage and real-time event broadcasting between server instances.

Self-Hosting Best Practices

Data Persistence and Backups

The compose file mounts ${UPLOAD_LOCATION} for OctoBase storage and ${DB_DATA_LOCATION} for PostgreSQL. You must back up these directories regularly because they contain all user workspace data and block content. For Kubernetes deployments, enable persistent volume claims in the Helm values.yaml and configure automated snapshot policies.

Database Migrations

The affine_migration job runs scripts/self-host-predeploy.js to apply schema changes before the server boots. If you upgrade your AFFiNE image tag, always ensure the migration job completes successfully before the new server version starts serving traffic.

Licensing Considerations

The Community Edition (CE) is MIT-licensed and free to self-host without limitations. Enterprise features—including SSO integration and advanced admin controls—require uploading an AFFiNE Enterprise license file through the self-hosted UI (referenced in the i18n strings for "self-hosted license" in the codebase).

Summary

• Docker Compose (.docker/selfhost/compose.yml) provides the fastest path to self-hosting AFFiNE for development or small-scale production.
• Helm charts (.github/helm/affine/) deliver Kubernetes-native scaling and high availability, configurable via global.deployment.type=selfhosted.
• AFFiNE Cloud offers a zero-maintenance SaaS option for teams prioritizing convenience over infrastructure control.
• All self-hosted deployments require persistent volumes for ${UPLOAD_LOCATION} and ${DB_DATA_LOCATION}, plus proper environment configuration via .env files or Helm values.
• The migration job ensures database schema compatibility before the NestJS server starts accepting connections.

Frequently Asked Questions

What are the system requirements for self-hosting AFFiNE?

AFFiNE requires Docker Engine 20.10+ or a Kubernetes 1.24+ cluster. Minimum resources include 2GB RAM for the server container, 1GB for PostgreSQL, and 512MB for Redis. Production deployments should allocate at least 4GB RAM and provision SSD storage for the ${UPLOAD_LOCATION} and database directories to ensure responsive CRDT operations.

How do I back up my self-hosted AFFiNE instance?

Back up two critical paths: the ${UPLOAD_LOCATION} directory containing OctoBase block data and the ${DB_DATA_LOCATION} PostgreSQL data folder. For Docker Compose, run docker compose exec postgres pg_dump for SQL backups and archive the upload volume. Kubernetes users should configure Velero or native volume snapshots for the persistent volumes defined in the Helm release.

Can I migrate from AFFiNE Cloud to a self-hosted instance?

The AFFiNE codebase supports workspace export and import functionality, allowing you to download workspaces from the cloud service and restore them to a self-hosted server. Ensure your self-hosted instance runs the same or newer version as the cloud export to guarantee compatibility with the block schema stored in OctoBase.

Is the self-hosted version of AFFiNE free to use?

Yes. The Community Edition distributed in ghcr.io/toeverything/affine is MIT-licensed and completely free for personal and commercial use. Enterprise features like SSO require a separate license, but core workspace functionality, collaborative editing, and AI features (when configured with your own API keys) remain available without cost.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}