# 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:

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

2. Configure environment variables:

```bash
cp deploy.env .env
```

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

```env
# 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:

```bash
docker-compose up -d
```

6. Confirm that your services are running:

```bash
docker ps -a
```

7. To enable SSL, you can use certbot:

```bash
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:

```yaml
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:

```bash
docker-compose down
docker-compose up -d
```

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

```bash
crontab -e
```
Add this line to run the renewal every month on the 1st day at 2:00 AM:

```bash
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](check-and-renew-certs.sh) and [renew-certs.sh](renew-certs.sh) in the `AppFlowy-Cloud` directory.

## Additional considerations

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

```bash
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:

```bash
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:

```bash
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:

```bash
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
```