Self-Hosting Overview

Introduction to self-hosting AFFiNE on your own infrastructure

Self-Hosting AFFiNE

AFFiNE can be self-hosted on your own infrastructure, giving you complete control over your data, privacy, and deployment environment. This guide will help you understand the architecture and get started with your own AFFiNE instance.

Architecture

AFFiNE’s self-hosted deployment consists of several components working together:

1. Application Server

   The main Node.js application server handling API requests, WebSocket connections, and serving the web interface.

2. PostgreSQL Database

   PostgreSQL with pgvector extension for storing user data, workspaces, and vector embeddings for search.

3. Redis Cache

   Redis for session management, caching, and job queues.

4. Storage Layer

   File system or S3-compatible storage for user uploads, avatars, and blobs.

System Requirements

Minimum Requirements

• CPU: 2 cores
• RAM: 4 GB
• Storage: 20 GB (plus space for user data)
• OS: Linux (Ubuntu 20.04+, Debian 11+, or equivalent)

Recommended Requirements

• CPU: 4+ cores
• RAM: 8 GB+
• Storage: SSD with 50 GB+ (plus space for user data)
• OS: Linux (Ubuntu 22.04+ or Debian 12+)

Software Dependencies

• Docker 24.0+ and Docker Compose 2.0+
• OR Node.js 22.x, PostgreSQL 16 with pgvector, Redis 7.0+

Deployment Options

AFFiNE supports multiple deployment methods:

Docker Compose (Recommended)

The easiest way to deploy AFFiNE is using Docker Compose. This method handles all dependencies and configuration automatically.

# Clone the repository
git clone https://github.com/toeverything/affine.git
cd affine/.docker/selfhost

# Configure environment
cp .env.example .env

# Start services
docker compose up -d

Manual Installation

For advanced users who want more control, you can install AFFiNE components manually. This requires setting up:

• PostgreSQL 16 with pgvector extension
• Redis server
• Node.js 22 runtime
• AFFiNE application server

Kubernetes

For production deployments at scale, AFFiNE can be deployed to Kubernetes using Helm charts.

Key Features

Data Privacy & Control

All your data stays on your infrastructure. You have complete control over backups, retention policies, and data access.

Customizable Configuration

Configure authentication providers, storage backends, email settings, AI features, and more through environment variables or JSON configuration files.

Scalable Architecture

The stateless application server design allows horizontal scaling. Redis and PostgreSQL can be clustered for high availability.

S3-Compatible Storage

Use local file system or any S3-compatible storage (AWS S3, MinIO, Cloudflare R2) for user uploads and attachments.

Available Versions

AFFiNE provides three release channels:

Channel	Image Tag	Description	Stability
Stable	ghcr.io/toeverything/affine:stable	Production-ready releases	High
Beta	ghcr.io/toeverything/affine:beta	Pre-release features	Medium
Canary	ghcr.io/toeverything/affine:canary	Latest development builds	Low

Canary builds may contain breaking changes and should not be used in production environments.

Quick Start

To get started with a basic deployment:

1. Download Configuration

   mkdir affine-selfhost && cd affine-selfhost
   wget https://raw.githubusercontent.com/toeverything/affine/main/.docker/selfhost/compose.yml
   wget https://raw.githubusercontent.com/toeverything/affine/main/.docker/selfhost/.env.example -O .env
   
2. Configure Environment

   Edit .env and set required values:

   # Minimum required configuration
   DB_PASSWORD=your_secure_password
   AFFINE_SERVER_HOST=affine.yourdomain.com
   AFFINE_SERVER_HTTPS=true
   
3. Start Services

   docker compose up -d
   
4. Access AFFiNE

   Open your browser and navigate to http://localhost:3010 (or your configured domain).

Next Steps

Deployment Guide

Detailed deployment instructions and configuration

Configuration

Complete configuration reference and options

Security

Security best practices and hardening

Maintenance

Backup, updates, and operational tasks

Getting Help

If you encounter issues:

• Check the GitHub Issues
• Join the Discord Community
• Review the Troubleshooting Guide (coming soon)

Self-hosting AFFiNE requires technical knowledge of Linux, Docker, and database administration. For a managed solution, consider AFFiNE Cloud.