Appwrite Administration & Architecture Guide

Executive Summary

Appwrite is a self-hosted Backend-as-a-Service (BaaS) platform built on PHP 8.3+ with Swoole 6.x for high-concurrency async I/O. It provides authentication, databases (three engines: TablesDB, DocumentsDB, VectorsDB), file storage, serverless functions, static/SSR site hosting, messaging, and real-time WebSocket subscriptions. The platform ships as a Docker Compose stack with Traefik reverse proxy, supporting MariaDB, MongoDB, or PostgreSQL as the underlying database backend. Version 1.9.1 (source commit 0aab3e9, 2026-04-17) is the current stable release.

The codebase spans 2,763 files across two primary namespaces: src/Appwrite/ (platform logic) and app/ (configuration, controllers, initialization). Background processing uses a queue-driven worker architecture handling audits, certificates, deletions, function executions, mail delivery, migrations, statistics, and webhooks.

Important

This guide covers the self-hosted Community Edition. Appwrite Cloud may differ in configuration, scaling, and available features.

1. Architecture Overview

1.1 High-Level Component Map

Internet
  │
  ▼
Traefik (reverse proxy, auto-SSL)
  │
  ├── /v1/*    → Appwrite API (Swoole HTTP server, port 80)
  ├── /console → Console SPA
  └── Realtime → WebSocket server
  │
  ├── Redis (cache, pub/sub, queue broker)
  ├── Database (MariaDB | MongoDB | PostgreSQL)
  ├── Executor (Open Runtimes, function/site builds)
  └── Workers (10 queue consumers)
       ├── Audits        ├── Functions
       ├── Certificates  ├── Mails
       ├── Deletes       ├── Migrations
       ├── Executions    ├── StatsResources
       ├── StatsUsage    └── Webhooks

1.2 Request Lifecycle

1. Traefik terminates TLS and routes to the Swoole HTTP server.
2. The general router (app/controllers/general.php) resolves the project from the hostname or X-Appwrite-Project header.
3. Shared middleware (app/controllers/shared/api/) handles authentication (session, JWT, API key), rate limiting, and abuse detection.
4. Module-specific service classes (src/Appwrite/Platform/Modules/*/Services/) define route handlers via the utopia-php/platform framework.
5. Events are published to Redis queues for async processing by workers.
6. Realtime pushes changes to subscribed WebSocket clients.

1.3 Namespace Map

1.4 Database Architecture

Appwrite 1.8+ introduced three database engine types:

All three engines are backed by the same underlying database backend (MariaDB, MongoDB, or PostgreSQL) via the utopia-php/database abstraction layer. The engine type is set at database creation time and determines the available API surface.

Note

TablesDB is the recommended engine for new projects. The Databases (DocumentsDB) service is deprecated in SDKs from version 1.8 onward but continues to work for existing data.

Shared tables mode — configured via _APP_DATABASE_SHARED_TABLES — allows multiple projects to share the same underlying database tables with tenant isolation via sequence-based partitioning.

1.5 Transaction Support

All three database engines support ACID transactions:

2. System Requirements

2.1 Runtime Dependencies

2.2 Key Composer Dependencies

2.3 Infrastructure Requirements

3. Configuration Reference

3.1 Environment Variables

Appwrite is configured entirely via environment variables in the .env file. The full variable list is loaded from app/config/variables.php during initialization (app/init/configs.php).

Caution

Environment variable names are prefixed with _APP_. Changing database-related variables on an existing installation requires careful migration. See issue #11902 regarding _APP_DB_HOST redefinition during upgrades.

Core variables:

Database variables:

Executor variables:

Queue variables:

SMTP variables:

Logging & telemetry:

3.2 Configuration Files

All configuration is loaded at startup via app/init/configs.php:

3.3 Hard-Coded Limits

These constants are defined in app/init/constants.php and cannot be changed via environment variables:

3.4 Compute Specifications

4. Deployment & Scaling

4.1 Docker Compose Stack

The production deployment uses Docker Compose with the following services:

4.2 Web Installer

Appwrite includes a web-based installer (src/Appwrite/Platform/Installer/Server.php) that runs a Swoole HTTP server on port 20080 during initial setup or upgrades.

# Fresh install
php src/Appwrite/Platform/Installer/Server.php --docker

# Upgrade (auto-detects existing config)
php src/Appwrite/Platform/Installer/Server.php --docker --upgrade

# Clean up installer artifacts
composer installer:clean

The installer auto-detects upgrade mode by checking for existing docker-compose.yml and .env files. It also detects the current database backend (MariaDB, MongoDB, or PostgreSQL) from the compose file or environment variables.

Installer steps: env-vars → config-files → docker-compose → docker-containers → account-setup → migration → ssl-certificate.

Lock file: /tmp/appwrite-install-lock.json Config file: /tmp/appwrite-installer-config.json Completion marker: /tmp/appwrite-installer-complete

Warning

The installer binds to 0.0.0.0:20080 by default. Ensure this port is not publicly exposed in production. The installer enforces Content Security Policy headers and CSRF protection.

4.3 Storage Paths

4.4 Scaling Considerations

• Horizontal worker scaling: Increase the number of worker containers per type. Each worker independently consumes from the Redis queue.
• Database connection pooling: Appwrite uses utopia-php/pools for connection pooling. Pool sizes are configured via connection DSNs.
• Redis sharding: Cache adapters support sharding across multiple Redis instances via Utopia\Cache\Adapter\Sharding.
• Shared tables: Enable _APP_DATABASE_SHARED_TABLES for multi-tenant deployments to reduce database count.
• Database reconnect: Automatic reconnect with exponential backoff — DATABASE_RECONNECT_SLEEP = 2s, DATABASE_RECONNECT_MAX_ATTEMPTS = 10.
• Cache reconnect: CACHE_RECONNECT_MAX_RETRIES = 2, CACHE_RECONNECT_RETRY_DELAY = 1000ms.

5. Operations

5.1 Worker Architecture

All background processing flows through Redis-backed queues consumed by dedicated worker processes:

Tip

The Audits worker uses a batch aggregation pattern: it accumulates audit entries for BATCH_AGGREGATION_INTERVAL (60 seconds) before flushing to the database in bulk. The batch size is controlled by _APP_QUEUE_PREFETCH_COUNT.

5.2 Deletion Subsystem

The Deletes worker handles 30+ resource deletion types (all defined as DELETE_TYPE_* constants). Key deletion flows:

• Project deletion: Cascades through databases, collections, functions, sites, storage, teams, users, webhooks, and all related resources.
• User deletion: Removes sessions, tokens, memberships, and targets.
• Database/collection deletion: Removes all documents/rows, attributes, indexes, and storage.
• Maintenance deletions: Audit logs, abuse records, usage data, expired sessions, expired transactions, CSV exports, realtime connections.

Batch queries use a minimal select set for performance: ['$sequence', '$id', '$collection', '$permissions', '$updatedAt'].

5.3 Event System

Events are published through the Appwrite\Event namespace using Redis queues:

Each event class supports queue name override via environment variables (e.g., _APP_AUDITS_QUEUE_NAME).

5.4 Scheduled Tasks

Appwrite supports cron-scheduled operations for:

• Function executions: Schedule delayed or periodic function invocations via the scheduledAt parameter. Uses dragonmantank/cron-expression for parsing.
• Message delivery: Scheduled messaging via the schedules collection.

Schedule resource types: execution, function, message.

5.5 Health Monitoring

The Health service (Appwrite\Platform\Modules\Health) provides checks for:

5.6 Migration Framework

The migration system (src/Appwrite/Migration/Migration.php) manages schema upgrades across Appwrite versions:

Migrations iterate over all project documents in batches of 100, applying schema changes collection by collection.

Caution

After upgrading to 1.9.0+, a missing emailCanonical attribute may cause errors (#11906). Ensure the migration completes successfully and verify the console database schema before serving traffic.

5.7 Cross-Instance Migration

The Migrations worker supports data transfer between Appwrite instances and external sources:

• Source processing: Reads users (password, phone), teams, databases, documents, storage files from the source.
• Destination processing: Writes imported data to the target instance.
• Temporary API keys are generated for migration operations and cleaned up afterward.
• Resource statistics are tracked per migration for auditing.
• Filenames are sanitized to prevent path traversal during import.

6. Performance

6.1 Database Timeouts

6.2 Query Limits

6.3 Rate Limiting

Default write rate limiting: 60 writes per 60-second period per resource. Abuse detection uses utopia-php/abuse with time-based database-backed limiters.

6.4 Swoole Coroutines

The entire application runs with Swoole coroutines enabled (SWOOLE_HOOK_ALL), providing async I/O for database, Redis, and network operations without blocking the event loop. The CLI entry point (app/cli.php) also enables coroutines for worker processes.

6.5 Metrics & Observability

Appwrite tracks comprehensive usage metrics (defined as METRIC_* constants):

• User activity: DAU, WAU, MAU
• Network: requests, inbound/outbound bytes
• Database: reads, writes, storage per database/collection
• Storage: files, transformations, previews per bucket
• Functions: executions, compute time (MB-seconds), builds
• Sites: requests, inbound/outbound per site
• Messaging: sent/failed counts per type and provider
• Webhooks: sent/failed per webhook
• Realtime: connections, messages sent, inbound/outbound
• Embeddings: requests, tokens, duration, errors per model

7. Security

7.1 Authentication Methods

7.2 Multi-Factor Authentication (MFA)

• TOTP via spomky-labs/otphp (RFC 6238)
• Recovery codes for backup access
• MFA recent duration: 30 minutes (MFA_RECENT_DURATION = 1800)
• Challenge/factor validation through Account/Http/Account/MFA/ route handlers

7.3 API Key Types

7.4 Token Expiration

7.5 JWT Configuration

• Algorithm: HS256 (RESOURCE_TOKEN_ALGORITHM)
• Max age: 10 years (RESOURCE_TOKEN_MAX_AGE = 315,360,000s)
• Leeway: 10 seconds (RESOURCE_TOKEN_LEEWAY)
• JWT library: adhocore/jwt

7.6 Activity Types

All API activity is classified for audit and abuse detection:

7.7 Content Security Policy

The web installer enforces strict CSP:

default-src 'self'; script-src 'self'; style-src 'self';
img-src 'self' data:; font-src 'self' data:; connect-src 'self';
base-uri 'none'; form-action 'self'; frame-ancestors 'none';

7.8 File Security

• Antivirus scanning via ClamAV (appwrite/php-clamav), limited to files ≤ 20 MB
• SVG sanitization via enshrined/svg-sanitize
• Encryption for files ≤ 20 MB at rest
• Compression for files ≤ 20 MB
• Storage read buffer: 20 MB per read operation

7.9 Known Security Issues

• Command injection in function builds via providerRootDirectory/templateRootDirectory parameters was patched (#11929, CLOSED).
• Validator state mutation: PersonalData::isValid mutates internal state, causing side effects in concurrent contexts (#11895, OPEN).

8. Developer Internals

8.1 Platform Module System

Appwrite uses the utopia-php/platform framework to organize functionality into modules. Each module follows this structure:

src/Appwrite/Platform/Modules/{Module}/
  ├── Services/          # Route registration (one class per action)
  ├── Http/              # Request/response handling
  │   └── {Resource}/    # Resource-specific endpoints
  └── Workers/           # Module-specific workers (if any)

Services extend Utopia\Platform\Action and register themselves via Service::TYPE_HTTP. Workers extend Utopia\Platform\Action with queue consumption logic.

8.2 Dependency Injection

The application uses Utopia\DI\Container for dependency injection. Key injected services (configured in app/cli.php and shared API init):

8.3 Open Runtimes Executor

The Executor class (src/Executor/Executor.php) communicates with the Open Runtimes executor service via HTTP:

• Runtime creation: createRuntime() — builds and launches a container for a function deployment.
• Execution: Invokes function code within the runtime container.
• Runtime migration: Versions v3/v4 are automatically migrated to v5 (if ($version === 'v3' || $version === 'v4') { $version = 'v5'; }).
• Authentication: Bearer token via _APP_EXECUTOR_SECRET.
• Addressing: Uses x-opr-addressing-method: anycast-efficient for distributed executor routing.

8.4 GraphQL Support

Appwrite exposes a GraphQL endpoint alongside REST:

• Parser: app/controllers/api/graphql.php handles both application/json and multipart/form-data requests.
• Type system: src/Appwrite/GraphQL/Types/ defines custom scalar and object types.
• Promise adapters: src/Appwrite/GraphQL/Promises/Adapter/ provides async resolution.
• Engine: webonyx/graphql-php 15.31.x.

8.5 Realtime (WebSocket)

• WebSocket server runs as a separate container using utopia-php/websocket.
• Redis pub/sub distributes events to all WebSocket server instances.
• Clients subscribe to channels: databases.{dbId}.collections.{collId}.documents, account, files, teams, functions, etc.
• Known issue: WebSocket reconnection lacks exponential backoff (#11939).
• Metrics tracked: METRIC_REALTIME_CONNECTIONS, METRIC_REALTIME_CONNECTIONS_MESSAGES_SENT.

8.6 OAuth2 Framework

The abstract Appwrite\Auth\OAuth2 class provides the base for all 40+ OAuth2 provider implementations. Each provider implements:

• getLoginURL() — authorization redirect URL
• getTokens() — exchange code for tokens
• refreshTokens() — token refresh
• getUserID(), getUserEmail(), getUserName() — user info extraction

Provider configuration is loaded from app/config/oAuthProviders.php.

8.7 SDK System

Appwrite generates client SDKs from API specifications using appwrite/sdk-generator. Three built-in SDK bundles are included in the repo:

All SDKs export: Client, Query, AppwriteException, Permission, Role, ID.

15+ platform SDKs are maintained separately: Web, Flutter, Android, Apple, Node.js, Python, PHP, Dart, Go, Ruby, .NET, Kotlin, Swift, Deno, Rust.

8.8 Agent Skills

The docs/sdks/agent-skills/ directory contains an npm package (appwrite/agent-skills) following the Agent Skills Open Standard. It provides AI coding agent instructions for 9 languages: TypeScript, Python, PHP, Go, Kotlin, Swift, Ruby, .NET, and Dart. Install with:

npx skills add appwrite/agent-skills

8.9 Sites (Static/SSR Hosting)

The Sites module (Appwrite\Platform\Modules\Sites) supports:

• Framework auto-detection (Astro, Next.js, etc.) via app/config/frameworks.php
• Static and SSR deployments with build pipeline
• Custom start commands for SSR applications
• Template-based deployments from starter projects
• VCS integration for automatic deployments on push

8.10 Messaging Subsystem

Multi-channel notification delivery:

Message routing: internal (system-generated) vs external (user-initiated) via MESSAGE_SEND_TYPE_* constants.

8.11 Proxy & Domain Routing

The Proxy module handles custom domain routing with these rule types:

Domain rule statuses: created → verifying → verified (or unverified on failure).

9. Integration Points

9.1 GitHub VCS Integration

The VCS module (Appwrite\Platform\Modules\VCS) provides GitHub integration:

• Repository browsing: List repositories, branches, contents
• Automatic deployments: Deploy on push via GitHub webhooks
• Framework detection: Detect project type from repository contents
• OAuth callback: VCS/Http/GitHub/Callback/ and VCS/Http/GitHub/Authorize/

9.2 Function Runtimes

Functions execute in isolated containers via Open Runtimes. Runtime environment variables available to functions:

Request headers available in function context:

Note

Geo information headers are not currently set for function executions (#9581).

9.3 Email Templates

Mail types for transactional emails:

Templates are loaded from app/config/locale/templates.php with locale-aware rendering. Known issue: session alert templates are broken for non-English locales (#8659).

9.4 CSV Import/Export

CSV handling uses league/csv 9.14.x. Known issue: CSV export may fail to complete for large datasets (#11853). Temporary import files are stored at APP_STORAGE_IMPORTS (/storage/imports).

10. Troubleshooting

10.1 Known Issues (from GitHub)

10.2 Upgrade Checklist (1.8.x → 1.9.x)

1. Backup database and .env file before upgrading.
2. Run the web installer with --upgrade flag or update Docker images.
3. Verify _APP_DB_HOST is not redefined in .env (#11902).
4. Check that the V24 migration completed — look for emailCanonical attribute in the users collection (#11906).
5. Test OAuth2 flows if configured — redirect URIs may need updating.
6. Monitor scheduled function execution timing for drift (#11931).

10.3 Database Connection Issues

• The CLI entry point retries database connections up to 5 times with 3-second sleep intervals before failing.
• Workers and tasks use DATABASE_RECONNECT_MAX_ATTEMPTS = 10 with DATABASE_RECONNECT_SLEEP = 2s.
• Log output format: [Error] Timestamp: <ISO 8601>, [Error] Type:, [Error] Message:, [Error] File:, [Error] Line:, [Error] Trace:.

11. Quick Reference

11.1 Development Commands

# Run tests
composer test

# Lint code
composer lint

# Format code
composer format

# Static analysis
composer analyze    # or composer check

# Benchmarks
composer bench

# Start dev installer
composer installer:dev

11.2 Key File Paths

11.3 Supported Database Backends

11.4 MongoDB Init Script

The included mongo-init.js reads three environment variables:

Note

Negative-knowledge omissions (AST extraction):

• 0 CLI commands were extracted by AST analysis. Appwrite's CLI is a PHP task runner (app/cli.php) that dispatches to platform action classes, not a traditional command-line tool with registered subcommands. No CLI command reference is included.
• 0 API endpoints were extracted by AST. Routes are registered dynamically via the utopia-php/platform service layer, not as static route definitions parseable by AST. API endpoint tables are not included in this guide.
• 0 actions and 0 filters were extracted. The platform uses dependency injection and middleware patterns rather than WordPress-style hook/filter systems.