Self-Hosting AFFiNE on Docker VPS: Building a Next-Generation, Hyper-Fast Knowledge Graph and Mind Map Platform

Introduction: The Evolution of Knowledge Management

In the modern corporate ecosystem, information is one of the most valuable enterprise assets. However, traditional knowledge management tools often force organizations to choose between two rigid paradigms: structured, linear document systems (like standard wikis) or unstructured, visual brainstorming canvases (like traditional mind mapping tools). This fragmentation stifles innovation, disrupts workflows, and creates information silos across teams.

Enter AFFiNE.pro—a next-generation, open-source knowledge management platform designed to bridge this gap seamlessly. Representing the pinnacle of modern workspace design, AFFiNE integrates documentation, whiteboarding, and graphical mind-mapping into a unified, privacy-first environment. By self-hosting AFFiNE on a Docker VPS, enterprises can unlock a hyper-fast, highly scalable collaborative workspace while maintaining absolute data sovereignty. This comprehensive guide provides a technical blueprint for deploying AFFiNE in your own secure infrastructure.

Why Choose AFFiNE over Notion, Miro, or Obsidian?

While proprietary cloud platforms dominate the market, they introduce significant corporate risks, including vendor lock-in, recurring subscription costs, and unpredictable data privacy compliance. AFFiNE stands out as a formidable alternative due to several architectural advantages:

The "Edgeless" Mode: Unlike Notion, which is primarily linear, or Miro, which is purely spatial, AFFiNE allows users to transform a structured text document into a free-form visual whiteboard with a single click. This feature enables teams to transition instantly from analytical drafting to creative brainstorming.
Local-First & Cloud-Agnostic Architecture: AFFiNE prioritizes local data processing, resulting in near-zero latency and a hyper-fast user experience. Changes are synchronized effortlessly without slowing down productivity.
Absolute Privacy and Control: For organizations handling proprietary code, financial strategies, or sensitive client data, reliance on third-party cloud servers poses strict regulatory challenges. Self-hosting eliminates this external vulnerability completely.

Prerequisites for Deployment

Before initiating the installation process, ensure your infrastructure meets the following baseline technical specifications:

Virtual Private Server (VPS): A minimum of 2 vCPUs, 4GB RAM, and 40GB SSD storage. For optimal speed and performance across distributed teams, we highly recommend NVMe-backed storage.
Operating System: A clean installation of a stable Linux distribution, preferably Ubuntu 22.04 LTS or Debian 12.
Domain Name: A fully qualified domain name (FQDN) configured with A/AAAA records pointing to your VPS public IP address (e.g., affine.yourcompany.com).
Software Stack: Docker Engine (version 20.10 or higher) and Docker Compose v2 installed on the host system.

Step-by-Step Architecture Deployment Guide

Step 1: System Preparation and Firewall Configuration

First, access your VPS via SSH and update the core system packages to guarantee stability and patch any active security vulnerabilities:

sudo apt update && sudo apt upgrade -y

Next, ensure that essential network ports are open for HTTP (80), HTTPS (443), and standard SSH management (typically 22):

sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable

Step 2: Structuring the Application Directory

Maintain an organized directory structure to simplify future data backups and container upgrades. Create a dedicated space for AFFiNE within the /opt directory:

sudo mkdir -p /opt/affine/config /opt/affine/data
cd /opt/affine

Step 3: Crafting the Docker Compose Configuration

AFFiNE utilizes a microservices architecture that requires a persistent database (PostgreSQL) and a storage solution (S3-compatible or local block storage) alongside the main application server. Create a file named docker-compose.yml using your preferred text editor:

sudo nano docker-compose.yml

Populate the file with the following production-ready configuration structure:

Note: Always replace default database passwords and secret keys with strong, randomly generated credentials prior to launching containers in a production environment.

version: '3.8'

services:
  postgres:
    image: postgres:15-alpine
    container_name: affine_postgres
    restart: always
    environment:
      POSTGRES_USER: affine_admin
      POSTGRES_PASSWORD: StrongProductionPassword_ChangeMe
      POSTGRES_DB: affine_db
    volumes:
      - ./data/postgres:/var/lib/postgresql/data

  affine:
    image: ghcr.io/toeverything/affine-graphql:stable
    container_name: affine_server
    restart: always
    depends_on:
      - postgres
    environment:
      - NODE_ENV=production
      - AFFINE_SERVER_HOST=0.0.0.0
      - AFFINE_SERVER_PORT=3010
      - DATABASE_URL=postgresql://affine_admin:StrongProductionPassword_ChangeMe@postgres:5432/affine_db
      - AFFINE_SERVER_EXTERNAL_URL=[https://affine.yourcompany.com](https://affine.yourcompany.com)
    volumes:
      - ./data/storage:/root/.affine/storage
      - ./config:/root/.affine/config
    ports:
      - "3010:3010"

Step 4: Launching the Microservices

With the docker-compose.yml file configured, deploy the ecosystem in detached mode, which allows the containers to run continuously in the background:

sudo docker compose up -d

Verify that all service components are functioning optimally by checking the active containers:

sudo docker compose ps

Configuring Reverse Proxy and SSL Encryption

To ensure encrypted, enterprise-grade access for remote team members, implement a reverse proxy using Nginx and acquire a free SSL certificate from Let's Encrypt via Certbot.

1. Install Nginx and Certbot

sudo apt install nginx certbot python3-certbot-nginx -y

2. Provision a Nginx Server Block

Create a specialized configuration file to route secure traffic into your running Docker container:

sudo nano /etc/nginx/sites-available/affine

Insert the following configuration blocking structure:

server {
    listen 80;
    server_name affine.yourcompany.com;

    location / {
        proxy_pass [http://127.0.0.1:3010](http://127.0.0.1:3010);
        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;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $$http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

3. Enable Configuration and Acquire SSL

Activate the configuration by linking it to the active sites directory, restart Nginx, and use Certbot to automate SSL certificate acquisition:

sudo ln -s /etc/nginx/sites-available/affine /etc/nginx/sites-enabled/
sudo systemctl restart nginx
sudo certbot --nginx -d affine.yourcompany.com

Certbot will automatically modify your Nginx block to enforce HTTPS encryption, securing all communication between your team's browsers and your self-hosted knowledge base.

Optimization Strategies for Enterprise Scaling

To guarantee that your newly self-hosted AFFiNE platform functions at a hyper-fast speed even as your internal database grows, apply the following optimization best practices:

Database Indexing & Vacuuming: Schedule automated weekly PostgreSQL routine maintenance tasks to clean out dead rows and optimize query execution plans across large knowledge graphs.
Automated Backups: Implement cron jobs to execute automated nightly snapshots of both your ./data/postgres and ./data/storage directories, securely pushing these assets to an off-site, isolated backup server.
Server-Side Caching: Adjust your Nginx reverse proxy configuration to cache static frontend assets locally, reducing system resource utilization and drastically decreasing page initial load times.

Conclusion

By self-hosting AFFiNE on a Docker VPS, your organization gains a modern, agile, and completely private knowledge management ecosystem. Free from the constraints of rigid cloud subscriptions and data isolation concerns, your business can collaboratively map out complex processes, manage interconnected assets, and fuel innovation securely. Follow this architecture blueprint to empower your operational teams with an open-source workspace built for the future of business intelligence.