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

> Explore AFFiNE deployment options: self-host with Docker Compose, deploy on Kubernetes via Helm, or use the AFFiNE Cloud SaaS. Get your instance running easily.

- Repository: [Toeverything/AFFiNE](https://github.com/toeverything/AFFiNE)
- Tags: how-to-guide
- Published: 2026-03-05

---

**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`](https://github.com/toeverything/AFFiNE/blob/main/.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`](https://github.com/toeverything/AFFiNE/blob/main/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

```bash

# 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`](https://github.com/toeverything/AFFiNE/blob/main/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

```bash

# 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](https://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`](https://github.com/toeverything/AFFiNE/blob/main/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`](https://github.com/toeverything/AFFiNE/blob/main/values.yaml) and configure automated snapshot policies.

### Database Migrations

The `affine_migration` job runs [`scripts/self-host-predeploy.js`](https://github.com/toeverything/AFFiNE/blob/main/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`](https://github.com/toeverything/AFFiNE/blob/main/.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.