> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/AppFlowy-IO/AppFlowy/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation Guide

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

## Prerequisites Check

Before starting the installation, ensure you have:

<CardGroup cols={2}>
  <Card title="Server Requirements" icon="server">
    A Linux server meeting the [system requirements](/self-hosting/overview#system-requirements)
  </Card>

  <Card title="Domain Name" icon="globe">
    A registered domain pointing to your server's IP address
  </Card>

  <Card title="Docker Installed" icon="docker">
    Docker Engine 24.0+ and Docker Compose 2.20+
  </Card>

  <Card title="SSH Access" icon="terminal">
    Root or sudo access to your server
  </Card>
</CardGroup>

## Installation Methods

<Tabs>
  <Tab title="Docker Compose">
    ## Docker Compose Installation

    This is the recommended method for most deployments.

    ### Step 1: Install Docker and Docker Compose

    <Steps>
      <Step title="Update system packages">
        ```bash theme={null}
        sudo apt update && sudo apt upgrade -y
        ```
      </Step>

      <Step title="Install Docker">
        ```bash theme={null}
        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.
      </Step>

      <Step title="Verify Docker installation">
        ```bash theme={null}
        docker --version
        docker compose version
        ```

        You should see Docker version 24.0+ and Docker Compose version 2.20+.
      </Step>
    </Steps>

    ### Step 2: Download AppFlowy Cloud

    <Steps>
      <Step title="Clone the repository">
        ```bash theme={null}
        git clone https://github.com/AppFlowy-IO/AppFlowy-Cloud.git
        cd AppFlowy-Cloud
        ```
      </Step>

      <Step title="Checkout the latest stable release">
        ```bash theme={null}
        git checkout $(git describe --tags --abbrev=0)
        ```
      </Step>
    </Steps>

    ### Step 3: Configure Environment Variables

    <Steps>
      <Step title="Copy the example environment file">
        ```bash theme={null}
        cp .env.example .env
        ```
      </Step>

      <Step title="Edit the environment file">
        ```bash theme={null}
        nano .env
        ```

        Update the following critical variables:

        ```bash theme={null}
        # 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
        ```
      </Step>

      <Step title="Generate secure secrets">
        Generate random secrets for JWT and database passwords:

        ```bash theme={null}
        # Generate JWT secret (64 characters)
        openssl rand -hex 32

        # Generate database password
        openssl rand -base64 32
        ```
      </Step>
    </Steps>

    ### Step 4: Initialize the Database

    <Steps>
      <Step title="Start PostgreSQL container">
        ```bash theme={null}
        docker compose up -d postgres
        ```
      </Step>

      <Step title="Wait for PostgreSQL to be ready">
        ```bash theme={null}
        docker compose logs -f postgres
        ```

        Wait until you see "database system is ready to accept connections".
      </Step>

      <Step title="Run database migrations">
        ```bash theme={null}
        docker compose run --rm appflowy-server migrate
        ```
      </Step>
    </Steps>

    ### Step 5: Start All Services

    <Steps>
      <Step title="Start all containers">
        ```bash theme={null}
        docker compose up -d
        ```

        This will start:

        * AppFlowy application server
        * PostgreSQL database
        * Redis cache
        * MinIO object storage
        * GoTrue authentication service
        * Nginx reverse proxy
      </Step>

      <Step title="Verify all services are running">
        ```bash theme={null}
        docker compose ps
        ```

        All services should show status as "Up".
      </Step>

      <Step title="Check service logs">
        ```bash theme={null}
        docker compose logs -f
        ```

        Monitor for any errors during startup.
      </Step>
    </Steps>

    ### Step 6: Configure Nginx and SSL

    <Steps>
      <Step title="Install Certbot for Let's Encrypt">
        ```bash theme={null}
        sudo apt install certbot python3-certbot-nginx -y
        ```
      </Step>

      <Step title="Obtain SSL certificate">
        ```bash theme={null}
        sudo certbot --nginx -d appflowy.yourdomain.com
        ```

        Follow the prompts to complete SSL setup.
      </Step>

      <Step title="Configure auto-renewal">
        ```bash theme={null}
        sudo certbot renew --dry-run
        ```
      </Step>
    </Steps>

    ### Step 7: Create Admin User

    <Steps>
      <Step title="Create the first admin user">
        ```bash theme={null}
        docker compose exec appflowy-server ./create-admin \
          --email admin@yourdomain.com \
          --password your_secure_password
        ```
      </Step>

      <Step title="Verify admin user creation">
        Check the logs for confirmation:

        ```bash theme={null}
        docker compose logs appflowy-server | grep -i admin
        ```
      </Step>
    </Steps>

    ### Step 8: Access AppFlowy

    <Steps>
      <Step title="Open your browser">
        Navigate to `https://appflowy.yourdomain.com`
      </Step>

      <Step title="Log in with admin credentials">
        Use the email and password you created in Step 7.
      </Step>

      <Step title="Complete initial setup">
        Follow the on-screen prompts to configure your workspace.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Kubernetes">
    ## Kubernetes Installation

    For production-grade deployments with high availability.

    ### Prerequisites

    <CardGroup cols={2}>
      <Card title="Kubernetes Cluster" icon="dharmachakra">
        A running Kubernetes cluster (v1.24+) with kubectl configured
      </Card>

      <Card title="Helm" icon="anchor">
        Helm 3.10+ package manager installed
      </Card>

      <Card title="Ingress Controller" icon="network-wired">
        Nginx Ingress Controller or similar
      </Card>

      <Card title="Persistent Storage" icon="database">
        StorageClass configured for persistent volumes
      </Card>
    </CardGroup>

    ### Installation Steps

    <Steps>
      <Step title="Add the AppFlowy Helm repository">
        ```bash theme={null}
        helm repo add appflowy https://appflowy-io.github.io/helm-charts
        helm repo update
        ```
      </Step>

      <Step title="Create a namespace">
        ```bash theme={null}
        kubectl create namespace appflowy
        ```
      </Step>

      <Step title="Create a values file">
        Create `values.yaml` with your configuration:

        ```yaml theme={null}
        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
        ```
      </Step>

      <Step title="Install AppFlowy">
        ```bash theme={null}
        helm install appflowy appflowy/appflowy \
          --namespace appflowy \
          --values values.yaml
        ```
      </Step>

      <Step title="Monitor the deployment">
        ```bash theme={null}
        kubectl get pods -n appflowy -w
        ```

        Wait for all pods to reach "Running" status.
      </Step>

      <Step title="Verify the deployment">
        ```bash theme={null}
        kubectl get ingress -n appflowy
        ```

        Confirm the ingress is configured correctly.
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Post-Installation Tasks

<CardGroup cols={2}>
  <Card title="Configure Backups" icon="clock-rotate-left">
    Set up automated database and storage backups. See [Security Guide](/self-hosting/security#backup-recommendations).
  </Card>

  <Card title="Enable Monitoring" icon="chart-line">
    Configure monitoring and alerting for your deployment.
  </Card>

  <Card title="Review Security" icon="shield">
    Follow the [Security Guide](/self-hosting/security) to harden your deployment.
  </Card>

  <Card title="Invite Users" icon="user-plus">
    Create user accounts and invite your team members.
  </Card>
</CardGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Services fail to start">
    Check the logs for specific errors:

    ```bash theme={null}
    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
  </Accordion>

  <Accordion title="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
  </Accordion>

  <Accordion title="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:

    ```bash theme={null}
    docker compose exec postgres psql -U appflowy -d appflowy
    ```
  </Accordion>

  <Accordion title="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:

    ```bash theme={null}
    sudo certbot renew --force-renewal
    ```
  </Accordion>
</AccordionGroup>

## Upgrading AppFlowy

<Steps>
  <Step title="Backup your data">
    Always create a backup before upgrading:

    ```bash theme={null}
    docker compose exec postgres pg_dump -U appflowy appflowy > backup.sql
    ```
  </Step>

  <Step title="Pull the latest version">
    ```bash theme={null}
    cd AppFlowy-Cloud
    git fetch --tags
    git checkout $(git describe --tags --abbrev=0)
    ```
  </Step>

  <Step title="Pull new Docker images">
    ```bash theme={null}
    docker compose pull
    ```
  </Step>

  <Step title="Restart services">
    ```bash theme={null}
    docker compose down
    docker compose up -d
    ```
  </Step>

  <Step title="Run migrations">
    ```bash theme={null}
    docker compose run --rm appflowy-server migrate
    ```
  </Step>
</Steps>

<Warning>
  Always test upgrades in a staging environment before applying to production.
</Warning>

## Next Steps

<CardGroup cols={2}>
  <Card title="Configuration Guide" icon="gear" href="/self-hosting/configuration">
    Fine-tune your AppFlowy deployment
  </Card>

  <Card title="Security Hardening" icon="lock" href="/self-hosting/security">
    Secure your installation
  </Card>
</CardGroup>