Self-Hosted AppFlowy Cloud Setup Guide

This guide will help you set up your own instance of AppFlowy Cloud.

Prerequisites

• Docker and Docker Compose
• PostgreSQL 14 or higher
• Redis
• Minimum 2GB RAM
• Git

Quick Start

1. Clone the Appflowy-Cloud repository:

git clone https://github.com/AppFlowy-IO/AppFlowy-Cloud.git
cd AppFlowy-Cloud

2. Configure environment variables:

cp deploy.env .env

Edit the following variables in the .env file to reflect your setup:

# Fully qualified domain name for the deployment.
FQDN=
# Change this to https if you wish to enable TLS.
SCHEME=

# PostgreSQL Settings
POSTGRES_PASSWORD=

# Postgres credential for supabase_auth_admin
SUPABASE_PASSWORD=

# Minio Host
AWS_SECRET=

## Base Url for the admin frontend. If you use the default Nginx conf provided here, this value should be /console.
## If you want to keep the previous behaviour where admin frontend is served at the root, don't set this env variable,
## or set it to empty string.
ADMIN_FRONTEND_PATH_PREFIX=

# authentication key, change this and keep the key safe and secret
# self defined key, you can use any string
GOTRUE_JWT_SECRET=

# If you want to use AWS SES or your own mail server, set the following variables:
GOTRUE_MAILER_AUTOCONFIRM=false
GOTRUE_SMTP_HOST=email-smtp.us-east-1.amazonaws.com
GOTRUE_SMTP_PORT=465
GOTRUE_SMTP_USER=
GOTRUE_SMTP_PASS=
GOTRUE_SMTP_ADMIN_EMAIL=

# This user will be created when GoTrue starts successfully
# You can use this user to login to the admin panel
GOTRUE_ADMIN_EMAIL=
GOTRUE_ADMIN_PASSWORD=

# AppFlowy Cloud Mailer Configuration (same credentials as GOTRUE_SMTP_*)
APPFLOWY_MAILER_SMTP_HOST=email-smtp.us-east-1.amazonaws.com
APPFLOWY_MAILER_SMTP_PORT=465
APPFLOWY_MAILER_SMTP_USERNAME=
APPFLOWY_MAILER_SMTP_EMAIL=
APPFLOWY_MAILER_SMTP_PASSWORD=

# PgAdmin
# Optional module to manage the postgres database
# You can access the pgadmin at http://your-host/pgadmin
# Refer to the APPFLOWY_DATABASE_URL for password when connecting to the database
PGADMIN_DEFAULT_EMAIL=
PGADMIN_DEFAULT_PASSWORD=

# Portainer (username: admin)
PORTAINER_PASSWORD=

# AppFlowy AI
AI_OPENAI_API_KEY=

3. Edit GoTrue Dockerfile (Not needed on latest version)

Modify the base Dockerfile from the Appflowy-Cloud repo to the one in this repo that installs bash, so the healthcheck can run.

4. Edit nginx.conf (Not needed on latest version)

Modify the base nginx.conf to the version in this repo to resolve a potential websocket DNS resolution issue.

5. Start the services:

docker-compose up -d

6. Confirm that your services are running:

docker ps -a

7. To enable SSL, you can use certbot:

sudo apt update
sudo apt install certbot
sudo certbot certonly --standalone -d yourdomain.com

This will create SSL certificates in /etc/letsencrypt/live/yourdomain.com

8. Update your docker-compose.yml file to use these certificates by mounting the certificate and private key locations:

services:
  nginx:
    restart: always
    image: nginx
    ports:
      - ${NGINX_PORT:-80}:80
      - ${NGINX_TLS_PORT:-443}:443
    volumes:
      - ./nginx/nginx.conf:/etc/nginx/nginx.conf
      - /etc/letsencrypt/live/yourdomain.com/fullchain.pem:/etc/nginx/ssl/certificate.crt:ro
      - /etc/letsencrypt/live/yourdomain.com/privkey.pem:/etc/nginx/ssl/private_key.key:ro

9. Restart your services:

docker-compose down
docker-compose up -d

10. Set up auto renewal for the certificates with cron job:

crontab -e

Add this line to run the renewal every month on the 1st day at 2:00 AM:

0 2 1 * * /home/moeny/AppFlowy-Cloud/check-and-renew-certs.sh >> /var/log/cert-renewal.log 2>&1

You will need to add check-and-renew-certs.sh and renew-certs.sh in the AppFlowy-Cloud directory.

Additional considerations

1. If you are getting redis-1 | WARNING Memory overcommit must be enabled!, run:

echo "vm.overcommit_memory = 1" | sudo tee -a /etc/sysctl.conf
sudo sysctl -p

You can verify the current value of the setting by running:

cat /proc/sys/vm/overcommit_memory

It should return 1 if the setting was applied successfully.

2. Also, note that the MinIO version in the docker-compose.yml may need to be updated to reflect the latest version. This is more relevant if you've been running Appflowy for a while and want to update your installation. Make sure to backup any MinIO data you may have before upgrading, although the upgrade should preserve existing data since it's using a named volume (minio_data).

To backup MinIO, use Docker volumes:

docker compose stop minio
docker run --rm -v appflowy-cloud_minio_data:/data -v $(pwd):/backup alpine tar czf /backup/minio-backup.tar.gz /data

If you need to restore:

docker compose stop minio
docker run --rm -v appflowy-cloud_minio_data:/data -v $(pwd):/backup alpine sh -c "cd /data && tar xzf /backup/minio-backup.tar.gz --strip 1"
docker compose start minio