Installation

Choose Your Platform

AFFiNE is available across multiple platforms to fit your workflow. Choose the option that works best for you:

Web App

Use AFFiNE directly in your browser

Desktop

Install native apps for Windows, macOS, and Linux

Self-Hosted

Deploy your own instance with Docker

Web App

The fastest way to start using AFFiNE is through the web application. No installation required.

Access the Web App

Navigate to app.affine.pro in your browser

Create an account for cloud sync, or click Continue without account to use locally

Start Creating

Your workspace is ready! Start creating documents immediately

Browser Requirements: AFFiNE works best on modern browsers (Chrome 90+, Firefox 88+, Safari 14+, Edge 90+)

Web App Features

No installation — Start immediately in your browser
Auto-updates — Always running the latest version
Cross-device — Access from any device with a browser
Cloud sync — Automatic backup and sync (requires account)

Desktop Apps

For the best performance and offline capabilities, install the native desktop application.

Windows

Download the Installer

Visit affine.pro/download and download the Windows installer (.exe)

Run the Installer

Double-click the downloaded file and follow the installation wizard

Launch AFFiNE

Find AFFiNE in your Start Menu and launch the application

Windows 10/11
Alternative: Portable

The Windows installer is compatible with Windows 10 (version 1809+) and Windows 11.System Requirements:

Windows 10 (build 1809+) or Windows 11
4 GB RAM minimum (8 GB recommended)
500 MB free disk space

For a portable installation without admin rights:

Download the .zip version from GitHub Releases
Extract to your preferred location
Run AFFiNE.exe directly

macOS

Download the DMG

Visit affine.pro/download and download the macOS installer (.dmg)

Install the App

Open the .dmg file and drag AFFiNE to your Applications folder

Launch AFFiNE

Open AFFiNE from Applications or Spotlight

Apple Silicon & Intel: AFFiNE provides universal binaries that work on both Apple Silicon (M1/M2/M3) and Intel Macs.

macOS 11+
First Launch Security

AFFiNE supports macOS 11 (Big Sur) and later versions.System Requirements:

macOS 11 or later
4 GB RAM minimum (8 GB recommended)
500 MB free disk space

Linux

AppImage
Debian/Ubuntu (.deb)
Arch Linux (AUR)

Download AppImage

wget https://github.com/toeverything/AFFiNE/releases/latest/download/affine-stable-linux-x64.AppImage

Make Executable

chmod +x affine-stable-linux-x64.AppImage

Run AFFiNE

./affine-stable-linux-x64.AppImage

Download .deb Package

wget https://github.com/toeverything/AFFiNE/releases/latest/download/affine_stable_amd64.deb

Install Package

sudo dpkg -i affine_stable_amd64.deb
sudo apt-get install -f  # Install dependencies if needed

Launch AFFiNE

affine

Install using your preferred AUR helper:

yay -S affine-bin
# or
paru -S affine-bin

Linux System Requirements: Ubuntu 18.04+, Debian 10+, Fedora 32+, or equivalent. X11 or Wayland display server.

Desktop Features

Offline-first — Full functionality without internet
Better performance — Native app optimization
System integration — File associations and system tray
Local storage — Your data stays on your machine by default
Auto-updates — Automatic updates to the latest version

Self-Hosted Docker

Deploy your own AFFiNE instance with full control over your data and infrastructure.

Quick Start with Docker Compose

Install Prerequisites

Ensure Docker and Docker Compose are installed:

docker --version
docker-compose --version

Minimum versions: Docker 20.10+ and Docker Compose 2.0+

Download Configuration Files

Create a directory for AFFiNE and download the compose file:

mkdir affine-selfhost && cd affine-selfhost
wget https://raw.githubusercontent.com/toeverything/AFFiNE/canary/.docker/selfhost/compose.yml
wget https://raw.githubusercontent.com/toeverything/AFFiNE/canary/.docker/selfhost/.env.example -O .env

Configure Environment Variables

Edit the .env file with your preferred settings:

nano .env

Key variables to configure:

# Select version: stable, beta, or canary
AFFINE_REVISION=stable

# Port to expose (default: 3010)
PORT=3010

# Database credentials
DB_USERNAME=affine
DB_PASSWORD=your-secure-password-here
DB_DATABASE=affine

# Data persistence locations
DB_DATA_LOCATION=~/.affine/self-host/postgres/pgdata
UPLOAD_LOCATION=~/.affine/self-host/storage
CONFIG_LOCATION=~/.affine/self-host/config

Important: Set a strong password for DB_PASSWORD in production!

Start AFFiNE

Launch all services with Docker Compose:

docker-compose up -d

This will start:

AFFiNE server
PostgreSQL database (with pgvector)
Redis for caching
Migration job

Access Your Instance

Open your browser and navigate to:

http://localhost:3010

Or use your server’s IP address if deploying remotely.

Docker Compose Configuration

The complete compose.yml configuration from the AFFiNE repository:

name: affine
services:
  affine:
    image: ghcr.io/toeverything/affine:${AFFINE_REVISION:-stable}
    container_name: affine_server
    ports:
      - '${PORT:-3010}:3010'
    depends_on:
      redis:
        condition: service_healthy
      postgres:
        condition: service_healthy
      affine_migration:
        condition: service_completed_successfully
    volumes:
      - ${UPLOAD_LOCATION}:/root/.affine/storage
      - ${CONFIG_LOCATION}:/root/.affine/config
    env_file:
      - .env
    environment:
      - REDIS_SERVER_HOST=redis
      - DATABASE_URL=postgresql://${DB_USERNAME}:${DB_PASSWORD}@postgres:5432/${DB_DATABASE:-affine}
    restart: unless-stopped

  postgres:
    image: pgvector/pgvector:pg16
    container_name: affine_postgres
    volumes:
      - ${DB_DATA_LOCATION}:/var/lib/postgresql/data
    environment:
      POSTGRES_USER: ${DB_USERNAME}
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_DB: ${DB_DATABASE:-affine}
    restart: unless-stopped

  redis:
    image: redis
    container_name: affine_redis
    restart: unless-stopped

Environment Variables Reference

Version & Port
External Access
Database
Storage

Variable	Description	Default
`AFFINE_REVISION`	Version to deploy (`stable`, `beta`, `canary`)	`stable`
`PORT`	Port to expose the server	`3010`

Variable	Description	Example
`AFFINE_SERVER_HOST`	Your domain name	`affine.yourdomain.com`
`AFFINE_SERVER_HTTPS`	Enable HTTPS	`true`
`AFFINE_SERVER_EXTERNAL_URL`	Full external URL	`https://affine.yourdomain.com`

Variable	Description	Default
`DB_USERNAME`	PostgreSQL username	`affine`
`DB_PASSWORD`	PostgreSQL password	(empty)
`DB_DATABASE`	Database name	`affine`
`DB_DATA_LOCATION`	Database data directory	`~/.affine/self-host/postgres/pgdata`

Variable	Description	Default
`UPLOAD_LOCATION`	File upload storage	`~/.affine/self-host/storage`
`CONFIG_LOCATION`	Configuration files	`~/.affine/self-host/config`

System Requirements

Minimum (< 10 users):

2 CPU cores
4 GB RAM
20 GB disk space
Docker 20.10+

Recommended (10-50 users):

4 CPU cores
8 GB RAM
100 GB disk space
Docker 20.10+

Production (50+ users):

8+ CPU cores
16+ GB RAM
500+ GB disk space (SSD recommended)
Docker 20.10+
Reverse proxy (nginx/Caddy) for SSL

Advanced Deployment

Using Custom Domain with SSL

To expose AFFiNE on a custom domain with HTTPS:

Update .env file:

AFFINE_SERVER_HTTPS=true
AFFINE_SERVER_HOST=affine.yourdomain.com

Set up reverse proxy (nginx example):

server {
    listen 443 ssl http2;
    server_name affine.yourdomain.com;
    
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;
    
    location / {
        proxy_pass http://localhost:3010;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
}

Restart AFFiNE:
```
docker-compose restart
```

Updating Your Self-Hosted Instance

To update to the latest version:

# Pull the latest images
docker-compose pull

# Restart services
docker-compose up -d

# Clean up old images (optional)
docker image prune -f

Your data persists in the volumes defined in .env, so updates are safe.

Backup and Restore

Backup:

# Stop the services
docker-compose stop

# Backup data directories
tar -czf affine-backup-$(date +%Y%m%d).tar.gz \
  ~/.affine/self-host/postgres \
  ~/.affine/self-host/storage \
  ~/.affine/self-host/config

# Restart services
docker-compose start

Restore:

# Stop services
docker-compose down

# Restore from backup
tar -xzf affine-backup-YYYYMMDD.tar.gz -C ~/

# Start services
docker-compose up -d

Deploy to Cloud Platforms

Deploy on Sealos

One-click deployment on Sealos cloud platform

Deploy on ClawCloud

Quick deployment template for ClawCloud

Troubleshooting

Desktop app won't start

Windows:

Run as administrator
Check Windows Defender/antivirus isn’t blocking it
Ensure .NET Framework 4.7.2+ is installed

macOS:

Check Security & Privacy settings
Try removing quarantine attribute: xattr -cr /Applications/AFFiNE.app

Linux:

Check file permissions: chmod +x AFFiNE.AppImage
Install FUSE for AppImage: sudo apt install libfuse2

Docker containers not starting

Check Docker is running: docker ps
View logs: docker-compose logs affine
Ensure ports are available: sudo netstat -tlnp | grep 3010
Verify environment variables in .env
Check disk space: df -h

Cannot connect to self-hosted instance

Verify services are running: docker-compose ps
Check firewall rules allow port 3010
Test locally: curl http://localhost:3010
Verify AFFINE_SERVER_HOST matches your domain
Check reverse proxy configuration if using one

Data not syncing between devices

Ensure you’re signed in with the same account on all devices
Check internet connection
Verify sync is enabled in Settings > Sync
For self-hosted: ensure AFFINE_SERVER_EXTERNAL_URL is accessible from all devices

Next Steps

Quickstart Guide

Learn how to create your first workspace and document

Self-Hosting Guide

Detailed guide for production deployments

Configuration

Advanced configuration options

Join Discord

Get help from the community

Need more help? Check out the GitHub Issues or join our Discord community for support.

Get Started

Core Features

Desktop & Mobile

Self-Hosting

Contributing

Choose Your Platform

Web App

Desktop

Self-Hosted

Web App

Web App Features

Desktop Apps

Windows

macOS

Linux

Desktop Features

Self-Hosted Docker

Quick Start with Docker Compose

Docker Compose Configuration

Environment Variables Reference

System Requirements

Advanced Deployment

Deploy to Cloud Platforms

Deploy on Sealos

Deploy on ClawCloud

Troubleshooting

Next Steps

Quickstart Guide

Self-Hosting Guide

Configuration

Join Discord

Get Started

Core Features

Desktop & Mobile

Self-Hosting

Contributing

​Choose Your Platform

Web App

Desktop

Self-Hosted

​Web App

​Web App Features

​Desktop Apps

​Windows

​macOS

​Linux

​Desktop Features

​Self-Hosted Docker

​Quick Start with Docker Compose

​Docker Compose Configuration

​Environment Variables Reference

​System Requirements

​Advanced Deployment

​Deploy to Cloud Platforms

Deploy on Sealos

Deploy on ClawCloud

​Troubleshooting

​Next Steps

Quickstart Guide

Self-Hosting Guide

Configuration

Join Discord

Choose Your Platform

Web App

Web App Features

Desktop Apps

Windows

macOS

Linux

Desktop Features

Self-Hosted Docker

Quick Start with Docker Compose

Docker Compose Configuration

Environment Variables Reference

System Requirements

Advanced Deployment

Deploy to Cloud Platforms

Troubleshooting

Next Steps