Deploy AFFiNE with Dokploy

Dokploy is an open-source server management platform that simplifies deploying Docker Compose applications on your VPS. It handles reverse proxy configuration, SSL certificates, and deployment management — making it practical to self-host AFFiNE as your collaborative knowledge workspace.

This guide walks you through deploying AFFiNE with PostgreSQL for data storage, Redis for real-time collaboration, and automatic HTTPS. AFFiNE combines documents, whiteboards, and databases into a unified workspace.

Prerequisites

• A VPS with at least 2 vCPUs, 4 GB RAM, and 20 GB storage
• Dokploy installed and running on your server (installation docs)
• A domain name (e.g., affine.yourdomain.com) with DNS A record pointing to your server's IP

Docker Compose Configuration

Create a new Compose project in Dokploy and paste the following configuration:

version: "3.8"

services:
  affine:
    image: ghcr.io/toeverything/affine-graphql:stable
    restart: unless-stopped
    ports:
      - "3010:3010"
    environment:
      - NODE_OPTIONS=--import=./scripts/register.js
      - AFFINE_CONFIG_PATH=/root/.affine/config
      - REDIS_SERVER_HOST=affine-redis
      - REDIS_SERVER_PORT=6379
      - DATABASE_URL=postgresql://affine:${DB_PASSWORD}@affine-db:5432/affine
      - NODE_ENV=production
      - AFFINE_SERVER_HOST=${AFFINE_DOMAIN}
      - AFFINE_SERVER_PORT=3010
      - AFFINE_SERVER_HTTPS=true
    volumes:
      - ../files/affine-config:/root/.affine/config
      - ../files/affine-storage:/root/.affine/storage
    depends_on:
      affine-db:
        condition: service_healthy
      affine-redis:
        condition: service_healthy
    healthcheck:
      test: ["CMD-SHELL", "curl -f http://localhost:3010/ || exit 1"]
      interval: 30s
      timeout: 10s
      retries: 5
      start_period: 60s

  affine-db:
    image: postgres:16-alpine
    restart: unless-stopped
    environment:
      - POSTGRES_DB=affine
      - POSTGRES_USER=affine
      - POSTGRES_PASSWORD=${DB_PASSWORD}
    volumes:
      - ../files/affine-db-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U affine"]
      interval: 10s
      timeout: 5s
      retries: 5

  affine-redis:
    image: redis:7-alpine
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5

Note: AFFiNE is actively developing its self-hosted offering. Check the AFFiNE GitHub repository for the latest Docker deployment instructions, as the image and configuration may evolve between releases.

Environment Variables

Set these in Dokploy's Environment tab for your compose project:

Variable	Purpose	Example
AFFINE_DOMAIN	Your AFFiNE domain name	affine.yourdomain.com
DB_PASSWORD	PostgreSQL database password	a-strong-random-password

In Dokploy, environment variables are set via the Environment editor in the project settings. Do not create a .env file manually — Dokploy manages this for you.

Volumes & Data Persistence

This setup uses Dokploy's ../files convention for bind-mounted volumes:

• ../files/affine-config — AFFiNE server configuration files
• ../files/affine-storage — User uploads, attachments, and blob storage
• ../files/affine-db-data — PostgreSQL database files (workspaces, pages, user accounts)

The ../files path is relative to the compose file inside Dokploy's project directory. This ensures your data persists across redeployments. Avoid using absolute paths because Dokploy may clean them during redeployment.

If you need S3 backup support, consider using named Docker volumes instead. Named volumes can be backed up with Dokploy's built-in backup features. AFFiNE also supports S3-compatible storage for blob storage.

Domain & SSL Setup

1. In your Dokploy project, navigate to the Domains tab
2. Click Add Domain and enter your domain (e.g., affine.yourdomain.com)
3. Set the container port to 3010
4. Enable HTTPS — Dokploy automatically provisions a Let's Encrypt SSL certificate
5. Save and wait for the certificate to be issued (usually under a minute)

Dokploy's built-in Traefik reverse proxy handles TLS termination and routes traffic to your AFFiNE container. HTTPS is required for real-time collaboration features using WebSocket connections.

Verifying the Deployment

1. In Dokploy, go to your project's Deployments tab and click Deploy
2. Watch the build logs — all three containers (affine, affine-db, affine-redis) should start
3. Check the Logs tab for the affine service. Look for the server ready message
4. Open https://affine.yourdomain.com in your browser — you should see the AFFiNE login page
5. Create your account and start building your workspace

Troubleshooting

AFFiNE takes a long time to start The first startup includes database migrations which can take 30–60 seconds. The health check has a 60-second start period to account for this. Check the affine container logs for migration progress.

Real-time collaboration not working WebSocket connections require HTTPS and proper proxy configuration. Ensure HTTPS is enabled in Dokploy and the domain is set correctly. Check that AFFINE_SERVER_HTTPS=true is set.

Database connection errors Verify DB_PASSWORD matches between the AFFiNE and PostgreSQL services. Ensure the affine-db container is healthy before the main service starts.

SSL certificate not issuing Ensure your domain's DNS A record points to your server's IP and has propagated. Dokploy uses Let's Encrypt HTTP-01 challenges, so port 80 must be accessible. Check Traefik logs in Dokploy for certificate-related errors.

---

Learn more about AFFiNE in our complete overview.

Need a VPS? Hostinger VPS starts at $4.99/mo — perfect for running AFFiNE.

---

For more on Docker Compose deployments in Dokploy, see the Dokploy Docker Compose documentation.

App data sourced from selfh.st open-source directory.