Installation Guide

Step-by-step instructions to deploy self-hosted AppFlowy

Prerequisites Check

Before starting the installation, ensure you have:

Server Requirements

A Linux server meeting the system requirements

Domain Name

A registered domain pointing to your server’s IP address

Docker Installed

Docker Engine 24.0+ and Docker Compose 2.20+

SSH Access

Root or sudo access to your server

Installation Methods

Docker Compose

Docker Compose Installation

This is the recommended method for most deployments.

Step 1: Install Docker and Docker Compose

1. Update system packages

   sudo apt update && sudo apt upgrade -y
   
2. Install Docker

   curl -fsSL https://get.docker.com -o get-docker.sh
   sudo sh get-docker.sh
   sudo usermod -aG docker $USER
   

   Log out and back in for group changes to take effect.

3. Verify Docker installation

   docker --version
   docker compose version
   

   You should see Docker version 24.0+ and Docker Compose version 2.20+.

Step 2: Download AppFlowy Cloud

1. Clone the repository

   git clone https://github.com/AppFlowy-IO/AppFlowy-Cloud.git
   cd AppFlowy-Cloud
   
2. Checkout the latest stable release

   git checkout $(git describe --tags --abbrev=0)
   

Step 3: Configure Environment Variables

1. Copy the example environment file

   cp .env.example .env
   
2. Edit the environment file

   nano .env
   

   Update the following critical variables:

   # Domain configuration
   APPFLOWY_CLOUD_BASE_URL=https://appflowy.yourdomain.com
   APPFLOWY_CLOUD_WS_BASE_URL=wss://appflowy.yourdomain.com
   
   # Database configuration
   POSTGRES_HOST=postgres
   POSTGRES_PORT=5432
   POSTGRES_DB=appflowy
   POSTGRES_USER=appflowy
   POSTGRES_PASSWORD=change_this_secure_password
   
   # Redis configuration
   REDIS_HOST=redis
   REDIS_PORT=6379
   
   # GoTrue authentication
   GOTRUE_JWT_SECRET=change_this_to_random_64_char_string
   GOTRUE_SITE_URL=https://appflowy.yourdomain.com
   
   # S3 storage (MinIO)
   S3_ENDPOINT=http://minio:9000
   S3_ACCESS_KEY_ID=minioadmin
   S3_SECRET_ACCESS_KEY=change_this_secure_password
   S3_BUCKET=appflowy-storage
   S3_REGION=us-east-1
   
3. Generate secure secrets

   Generate random secrets for JWT and database passwords:

   # Generate JWT secret (64 characters)
   openssl rand -hex 32
   
   # Generate database password
   openssl rand -base64 32
   

Step 4: Initialize the Database

1. Start PostgreSQL container

   docker compose up -d postgres
   
2. Wait for PostgreSQL to be ready

   docker compose logs -f postgres
   

   Wait until you see “database system is ready to accept connections”.

3. Run database migrations

   docker compose run --rm appflowy-server migrate
   

Step 5: Start All Services

1. Start all containers

   docker compose up -d
   

   This will start:

   • AppFlowy application server
   • PostgreSQL database
   • Redis cache
   • MinIO object storage
   • GoTrue authentication service
   • Nginx reverse proxy
2. Verify all services are running

   docker compose ps
   

   All services should show status as “Up”.

3. Check service logs

   docker compose logs -f
   

   Monitor for any errors during startup.

Step 6: Configure Nginx and SSL

1. Install Certbot for Let's Encrypt

   sudo apt install certbot python3-certbot-nginx -y
   
2. Obtain SSL certificate

   sudo certbot --nginx -d appflowy.yourdomain.com
   

   Follow the prompts to complete SSL setup.

3. Configure auto-renewal

   sudo certbot renew --dry-run
   

Step 7: Create Admin User

1. Create the first admin user

   docker compose exec appflowy-server ./create-admin \
     --email [e-mail] \
     --password your_secure_password
   
2. Verify admin user creation

   Check the logs for confirmation:

   docker compose logs appflowy-server | grep -i admin
   

Step 8: Access AppFlowy

1. Open your browser

   Navigate to https://appflowy.yourdomain.com

2. Log in with admin credentials

   Use the email and password you created in Step 7.

3. Complete initial setup

   Follow the on-screen prompts to configure your workspace.

Kubernetes

Kubernetes Installation

For production-grade deployments with high availability.

Prerequisites

Kubernetes Cluster

A running Kubernetes cluster (v1.24+) with kubectl configured

Helm

Helm 3.10+ package manager installed

Ingress Controller

Nginx Ingress Controller or similar

Persistent Storage

StorageClass configured for persistent volumes

Installation Steps

1. Add the AppFlowy Helm repository

   helm repo add appflowy https://appflowy-io.github.io/helm-charts
   helm repo update
   
2. Create a namespace

   kubectl create namespace appflowy
   
3. Create a values file

   Create values.yaml with your configuration:

   global:
     domain: appflowy.yourdomain.com
     
   postgresql:
     enabled: true
     auth:
       database: appflowy
       username: appflowy
       password: change_this_secure_password
     primary:
       persistence:
         size: 50Gi
         
   redis:
     enabled: true
     auth:
       enabled: false
       
   minio:
     enabled: true
     persistence:
       size: 100Gi
     auth:
       rootUser: minioadmin
       rootPassword: change_this_secure_password
       
   ingress:
     enabled: true
     className: nginx
     annotations:
       cert-manager.io/cluster-issuer: letsencrypt-prod
     tls:
       - secretName: appflowy-tls
         hosts:
           - appflowy.yourdomain.com
   
4. Install AppFlowy

   helm install appflowy appflowy/appflowy \
     --namespace appflowy \
     --values values.yaml
   
5. Monitor the deployment

   kubectl get pods -n appflowy -w
   

   Wait for all pods to reach “Running” status.

6. Verify the deployment

   kubectl get ingress -n appflowy
   

   Confirm the ingress is configured correctly.

Post-Installation Tasks

Configure Backups

Set up automated database and storage backups. See Security Guide.

Enable Monitoring

Configure monitoring and alerting for your deployment.

Review Security

Follow the Security Guide to harden your deployment.

Invite Users

Create user accounts and invite your team members.

Troubleshooting

Services fail to start

Check the logs for specific errors:

docker compose logs [service-name]

Common issues:

• Port conflicts: Ensure ports 80, 443 are available
• Insufficient memory: Check available RAM
• Database connection failures: Verify database credentials

Cannot access the web interface

1. Verify all containers are running: docker compose ps
2. Check nginx logs: docker compose logs nginx
3. Verify DNS resolution: nslookup appflowy.yourdomain.com
4. Check firewall rules: Ensure ports 80/443 are open

Database migration fails

1. Check PostgreSQL is running: docker compose ps postgres
2. Verify database credentials in .env
3. Check migration logs: docker compose logs appflowy-server
4. Try running migrations manually:

docker compose exec postgres psql -U appflowy -d appflowy

SSL certificate issues

1. Verify domain DNS is pointing to your server
2. Check Certbot logs: sudo journalctl -u certbot
3. Try manual certificate renewal:

sudo certbot renew --force-renewal

Upgrading AppFlowy

1. Backup your data

   Always create a backup before upgrading:

   docker compose exec postgres pg_dump -U appflowy appflowy > backup.sql
   
2. Pull the latest version

   cd AppFlowy-Cloud
   git fetch --tags
   git checkout $(git describe --tags --abbrev=0)
   
3. Pull new Docker images

   docker compose pull
   
4. Restart services

   docker compose down
   docker compose up -d
   
5. Run migrations

   docker compose run --rm appflowy-server migrate
   

Always test upgrades in a staging environment before applying to production.

Next Steps

Configuration Guide

Fine-tune your AppFlowy deployment

Security Hardening

Secure your installation