Prerequisites Check
Before starting the installation, ensure you have:
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
Kubernetes
Docker Compose Installation
This is the recommended method for most deployments.Step 1: Install Docker and Docker Compose
Update system packages
sudo apt update && sudo apt upgrade -y
Install Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo usermod -aG docker $USER
Verify Docker installation
docker --version
docker compose version
Step 2: Download AppFlowy Cloud
Clone the repository
git clone https://github.com/AppFlowy-IO/AppFlowy-Cloud.git
cd AppFlowy-Cloud
Checkout the latest stable release
git checkout $(git describe --tags --abbrev=0)
Copy the example environment file
Edit the environment file
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
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
Start PostgreSQL container
docker compose up -d postgres
Wait for PostgreSQL to be ready
docker compose logs -f postgres
Run database migrations
docker compose run --rm appflowy-server migrate
Step 5: Start All Services
Start all containers
This will start:
- AppFlowy application server
- PostgreSQL database
- Redis cache
- MinIO object storage
- GoTrue authentication service
- Nginx reverse proxy
Verify all services are running
All services should show status as “Up”. Check service logs
Monitor for any errors during startup. Install Certbot for Let's Encrypt
sudo apt install certbot python3-certbot-nginx -y
Obtain SSL certificate
sudo certbot --nginx -d appflowy.yourdomain.com
Configure auto-renewal
sudo certbot renew --dry-run
Step 7: Create Admin User
Create the first admin user
docker compose exec appflowy-server ./create-admin \
--email [email protected] \
--password your_secure_password
Verify admin user creation
Check the logs for confirmation:docker compose logs appflowy-server | grep -i admin
Step 8: Access AppFlowy
Open your browser
Navigate to https://appflowy.yourdomain.com
Log in with admin credentials
Use the email and password you created in Step 7.
Complete initial setup
Follow the on-screen prompts to configure your workspace.
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
Add the AppFlowy Helm repository
helm repo add appflowy https://appflowy-io.github.io/helm-charts
helm repo update
Create a namespace
kubectl create namespace appflowy
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
Install AppFlowy
helm install appflowy appflowy/appflowy \
--namespace appflowy \
--values values.yaml
Monitor the deployment
kubectl get pods -n appflowy -w
Verify the deployment
kubectl get ingress -n appflowy
Post-Installation Tasks
Configure Backups
Set up automated database and storage backups. See Security Guide. Enable Monitoring
Configure monitoring and alerting for your deployment.
Invite Users
Create user accounts and invite your team members.
Troubleshooting
Check the logs for specific errors:docker compose logs [service-name]
- Port conflicts: Ensure ports 80, 443 are available
- Insufficient memory: Check available RAM
- Database connection failures: Verify database credentials
Cannot access the web interface
- Verify all containers are running:
docker compose ps
- Check nginx logs:
docker compose logs nginx
- Verify DNS resolution:
nslookup appflowy.yourdomain.com
- Check firewall rules: Ensure ports 80/443 are open
- Check PostgreSQL is running:
docker compose ps postgres
- Verify database credentials in
.env
- Check migration logs:
docker compose logs appflowy-server
- Try running migrations manually:
docker compose exec postgres psql -U appflowy -d appflowy
- Verify domain DNS is pointing to your server
- Check Certbot logs:
sudo journalctl -u certbot
- Try manual certificate renewal:
sudo certbot renew --force-renewal
Upgrading AppFlowy
Backup your data
Always create a backup before upgrading:docker compose exec postgres pg_dump -U appflowy appflowy > backup.sql
Pull the latest version
cd AppFlowy-Cloud
git fetch --tags
git checkout $(git describe --tags --abbrev=0)
Restart services
docker compose down
docker compose up -d
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
