Skip to content

AppFlowy Cloud

Metadata

Field Value
Service appflowy
Purpose Self-hosted note-taking and personal/family organization
Criticality Tier 1
Owner Platform owner
Clusters local
Namespace appflowy
Exposure internet
Stateful yes
Backup class database + object storage
RPO / RTO Pending first backup and restore drill
Last reviewed 2026-08-01

1. Service Overview

AppFlowy Cloud is the self-hostable backend for AppFlowy. It provides the REST API, realtime collaboration, authentication, a browser app, an admin console, background jobs, and the shared PostgreSQL, Redis, and MinIO dependencies that back them. Desktop and mobile clients sync against it over HTTPS and WebSocket. AI and search are excluded from the stable-core profile.

Dependencies

Dependency Type Why it matters
Traefik ingress External HTTPS and WebSocket access for clients and browsers
PostgreSQL (pgvector) database Workspace, document, and auth metadata
Redis cache Realtime message bus and caching
MinIO object storage File uploads and document attachments
local-path storage Persistent volumes for the stateful components

2. Architecture Diagram

[AppFlowy clients / browser]
  -> [Traefik: notes.mutana.fr] (TLS)
  -> [appflowy-nginx] (internal router: /ws, /api, /gotrue, /minio-api, /console, /)
        |-> appflowy-cloud   (API + realtime collaboration, :8000)
        |-> gotrue           (authentication, :9999)
        |-> admin-frontend   (/console, :3000)
        |-> appflowy-web     (browser app, :80)
        |-> minio            (S3 API :9000 / console :9001)

[appflowy-cloud] -> [postgres] (pgvector), [redis]
[gotrue]         -> [postgres] (auth schema)
[appflowy-worker] -> [postgres], [redis], [minio]

3. Deployment Specifications

Item Value
Source path appflowy/base and appflowy/overlays/local
Deployment model Kustomize plus Fleet bundle
Workloads 6 Deployments + 3 StatefulSets behind the bundled nginx
Images appflowy_cloud:0.17.1, gotrue:0.17.1, admin_frontend:0.17.1, appflowy_worker:0.17.1, appflowy_web:0.16.2, pgvector/pgvector:0.8.6-pg16, redis:7.4.10-alpine, minio:RELEASE.2025-09-07T16-13-09Z, nginx:stable-alpine
Storage local-path; PostgreSQL 30Gi, MinIO 50Gi, Redis 2Gi
Probes Service-specific HTTP health endpoints; nginx's own status endpoint; pg_isready/redis-cli ping for stateful dependencies
RBAC No Kubernetes API access; token automount disabled on all workloads

4. Configuration Guide

The overlay ships cluster-specific values through ConfigMaps consumed via envFrom: APPFLOWY_BASE_URL=https://notes.mutana.fr, APPFLOWY_WEBSOCKET_BASE_URL=wss://notes.mutana.fr/ws/v2, internal service hostnames, S3 bucket name, and the MinIO presigned-URL endpoint. The bundled nginx ConfigMap (appflowy-nginx-config) preserves upstream's WebSocket timeout, /api/chat SSE settings, /api/import 2 GB body, and the MinIO presigned-URL Host rewrite.

Sign-up policy

Invite-only (GOTRUE_DISABLE_SIGNUP=true, GOTRUE_MAILER_AUTOCONFIRM=true). No SMTP is configured. The first admin account is created from the GOTRUE_ADMIN_* Secret values on first boot, and family accounts are created from the /console admin portal.

Secrets management

  • Secret: appflowy-secrets in namespace appflowy.
  • Required keys: POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB, GOTRUE_ADMIN_EMAIL, GOTRUE_ADMIN_PASSWORD, GOTRUE_JWT_SECRET, APPFLOWY_S3_ACCESS_KEY, APPFLOWY_S3_SECRET_KEY, SMTP_PASSWORD.
  • Source: manually created from an out-of-band env file based on appflowy-secrets.env.example. The env file is gitignored.
  • Consumption: secretKeyRef entries in gotrue, appflowy-cloud, appflowy-worker, and minio. GOTRUE_JWT_SECRET must be identical across gotrue and cloud.
  • Rotation: update PostgreSQL, MinIO, and JWT credentials together during a maintenance window. Changing only the JWT secret invalidates all active sessions; changing one side of a credential pair breaks the affected service.
  • Missing Secret impact: no application workload starts.

GoTrue sends verification and recovery email through implicit SMTPS on port 465. AppFlowy Cloud uses the same account for invitations and notifications. The SMTP password is injected independently into each workload from the shared Secret and is never stored in a ConfigMap.

5. Access Protocols

Path Endpoint Audience Auth TLS terminates at
Internal appflowy-nginx.appflowy.svc.cluster.local:80 Cluster only none none
External https://notes.mutana.fr AppFlowy users and clients AppFlowy GoTrue accounts Traefik

Authelia is intentionally omitted because native sync clients require direct access to the API and WebSocket endpoints, mirroring the Joplin exposure model. Sign-up is disabled; only the admin can create accounts from /console.

6. Operations and Observability

Healthy state requires all Deployments and StatefulSets Ready, Bound PVCs (postgres, minio, redis), populated Service endpoints, a healthy appflowy-cloud /api/health response, and a successful HTTPS response at the public hostname. The appflowy-cloud startup probe tolerates a slow initial boot because the service self-retries database and Redis connections, matching upstream's restart: on-failure behaviour.

7. Backup and Recovery Notes

Back up the PostgreSQL database (pg_dump), the MinIO object store (mc mirror or a volume snapshot of the minio PVC), and preserve appflowy-secrets in the secure out-of-band store. The first backup and restore drill remains required before the RPO/RTO can be recorded.

8. Release and Change Notes

  • Initial version: AppFlowy Cloud 0.17.1 with pgvector 0.8.6-pg16, Redis 7.4.10, and MinIO RELEASE.2025-09-07T16-13-09Z.
  • AI and search are excluded from the stable-core profile after an AI migration failure was observed; test migrations against a backup before enabling them.
  • Rollback: revert the GitOps change while preserving PVCs and the Secret. A downgrade after a database migration may require restoring a pre-upgrade dump.