Self-host AFFiNE

Self-hosted AFFiNE lets you run the AFFiNE server stack on infrastructure you control. Use this guide when you need control over data location, domain configuration, backups, user administration, and infrastructure policy while using AFFiNE as an open-source workspace for docs, whiteboards, knowledge management, and collaboration.

If you want the fastest managed experience, try AFFiNE online or download AFFiNE from the Download Page. If you want to operate AFFiNE on your own server, start with the steps below.

Recommended path

1. Review Requirements to plan CPU, memory, storage, Postgres, Redis, and optional monitoring.
2. Install with Docker Compose, which is the recommended deployment method.
3. Complete After Installation to create the first admin account and connect desktop clients.
4. Configure Domain and HTTPS before inviting users or sharing public links.
5. Set up Backup and Restore before production use or upgrades.
6. Read Upgrade before changing AFFiNE versions.

What you operate in a self-hosted deployment

Component	Purpose	Where to learn more
AFFiNE server	Runs the web application, API, sync, and collaboration services.	Docker Compose
Postgres	Stores AFFiNE application data and is the primary database to back up.	Postgres
Redis	Provides cache, background task, and sync infrastructure.	Redis
Blob storage	Stores uploaded images, files, and other workspace blobs.	Storage
Configuration	Stores custom server settings and operational configuration.	Configuration
Reverse proxy and HTTPS	Publishes your instance under a stable, secure domain.	Domain and HTTPS

Choose self-hosting when

• You need to decide where workspace data and uploaded files are stored.
• You already operate servers, Docker, reverse proxies, backups, and monitoring.
• You need a private AFFiNE deployment under your own domain and policies.
• You want direct control over Postgres, Redis, storage, email, OAuth, and user management.

If you do not want to maintain Postgres, Redis, backups, upgrades, HTTPS, and server health yourself, a managed AFFiNE workspace is usually the simpler option.

Production readiness checklist

Before using a self-hosted AFFiNE instance with real users, make sure you have:

• Set persistent DB_DATA_LOCATION, UPLOAD_LOCATION, and CONFIG_LOCATION values before the first start.
• Set a strong DB_PASSWORD before initializing Postgres.
• Created the first admin account from <your-affine-domain>/admin.
• Configured a domain, HTTPS, and the server external URL.
• Backed up Postgres, blob storage, and exported modified configuration.
• Tested restore procedures, not just backup creation.
• Planned upgrades around release notes and a maintenance window.

Common questions

What is the recommended way to self-host AFFiNE?

Docker Compose is the recommended way to self-host AFFiNE because it runs the AFFiNE server, migration job, Postgres, Redis, volumes, and configuration together in a repeatable setup.

What are the minimum resources for self-hosted AFFiNE?

For basic usage, plan for at least 4 CPU cores, 2 GB RAM, and enough storage for the server, Postgres data, uploaded blobs, and configuration. Use more memory and storage for large documents, many collaborators, or heavy uploads.

What should I back up before upgrading?

Back up the Postgres database, uploaded blobs when using filesystem storage, and modified configuration exported from the Admin Panel. Always verify that you can restore from the backup before relying on it.