Codakey
Play
← Back to appwrite

How to Deploy & Use appwrite

Appwrite Deployment and Usage Guide

This guide provides comprehensive instructions for deploying and using Appwrite, a powerful open-source backend-as-a-service platform.

1. Prerequisites

Before you begin, ensure you have the following installed on your system:

  • Docker: Appwrite runs in a containerized environment. Install Docker Desktop (for Windows/macOS) or Docker Engine (for Linux).
  • Internet Connection: Required for downloading Docker images and dependencies.

2. Installation

Appwrite can be installed by running a single Docker command.

Self-Hosting with Docker

Choose the command appropriate for your operating system:

Unix/Linux/macOS

docker run -it --rm \
    --volume /var/run/docker.sock:/var/run/docker.sock \
    --volume "$(pwd)"/appwrite:/usr/src/code/appwrite:rw \
    --entrypoint="install" \
    appwrite/appwrite:1.8.0

Windows (CMD)

docker run -it --rm ^
    --volume //var/run/docker.sock:/var/run/docker.sock ^
    --volume "%cd%"/appwrite:/usr/src/code/appwrite:rw ^
    --entrypoint="install" ^
    appwrite/appwrite:1.8.0

Windows (PowerShell)

docker run -it --rm `
    --volume /var/run/docker.sock:/var/run/docker.sock `
    --volume ${pwd}/appwrite:/usr/src/code/appwrite:rw `
    --entrypoint="install" `
    appwrite/appwrite:1.8.0

After running the command, follow the on-screen prompts to complete the installation. Once finished, navigate to http://localhost in your web browser to access the Appwrite console. On non-Linux hosts, it may take a few minutes for the server to fully start.

Upgrade from an Older Version

If you are upgrading an existing Appwrite server, use the Appwrite migration tool after completing the setup. Refer to the Appwrite Installation Docs for detailed migration instructions.

3. Configuration

Appwrite's configuration is primarily managed through environment variables within its Docker setup.

Environment Variables

For advanced production and custom installations, you can configure Appwrite using environment variables. These variables control various aspects of the Appwrite services.

You can find a comprehensive list of available environment variables and their descriptions in the Appwrite environment variables documentation.

Manual Setup with Docker Compose

Alternatively, you can manually set up your environment using Appwrite's public Docker Compose and .env files:

Download these files and modify the .env file to suit your specific configuration needs (e.g., database credentials, mail server settings, etc.) before starting the Docker containers.

4. Build & Run

Appwrite is distributed as Docker images, so there isn't a traditional "build" step for the end-user. The installation command handles pulling the necessary images and setting up the environment.

Running Locally (Development and Production)

The installation command provided in Section 2 automatically sets up and runs Appwrite locally using Docker Compose.

To manage your Appwrite instance after the initial installation:

  • Start Appwrite: Navigate to the directory where your appwrite folder (created during installation) resides and run: 
    docker-compose up -d
  • Stop Appwrite: 
    docker-compose down
  • Restart Appwrite: 
    docker-compose restart

5. Deployment

Appwrite is designed for containerized deployment. Beyond local Docker Compose, it can be deployed on various container orchestration platforms.

Recommended Deployment Platforms:

  • Kubernetes: For scalable and resilient production environments. Appwrite can be deployed to Kubernetes clusters using Helm charts or custom manifests.
  • Docker Swarm: A native clustering solution for Docker containers, suitable for simpler multi-host deployments.
  • Rancher: A complete software stack for managing Kubernetes clusters.
  • Cloud Providers (Managed Kubernetes Services):
    • Amazon EKS
    • Google Kubernetes Engine (GKE)
    • Azure Kubernetes Service (AKS)
    • DigitalOcean Kubernetes

Deployment Considerations:

  • Persistent Storage: Ensure your deployment uses persistent volumes for Appwrite's data (databases, storage files) to prevent data loss on container restarts or failures. The default installation maps a local volume (./appwrite) for this purpose.
  • Networking: Configure appropriate ingress controllers, load balancers, and network policies to expose Appwrite services securely.
  • Security: Implement SSL/TLS for all communication, manage API keys securely, and configure firewall rules.
  • Monitoring & Logging: Integrate with your preferred monitoring and logging solutions to observe Appwrite's health and performance.

One-Click Setups

Appwrite also offers one-click deployment options for certain platforms. Refer to the Appwrite documentation for available one-click deployment guides.

6. Troubleshooting

Here are some common issues and their solutions when working with Appwrite:

  • Appwrite console not accessible at http://localhost:

    • Check Docker status: Ensure Docker is running.
    • Wait for services: After installation, especially on non-Linux hosts, services might take a few minutes to start.
    • Port conflicts: Another application might be using port 80 or 443. Check your system's port usage.
    • Firewall: Ensure your firewall isn't blocking access to ports 80 or 443.
    • Docker logs: Check the logs of the Appwrite containers for errors: 
      docker-compose logs

  • AppwriteException errors in SDKs:

    • Missing required parameters: Ensure you are providing all necessary arguments to SDK methods. For example, userId, email, and password are required for account.create().
    • Incorrect API endpoint: Verify that your SDK client is initialized with the correct Appwrite endpoint.
    • Invalid API Key/Permissions: If using server-side SDKs, ensure your API key has the necessary permissions.
    • Network issues: Check connectivity between your application and the Appwrite server.

  • File upload issues (Storage service):

    • Bucket ID: Ensure you are providing a valid bucketId when calling storage.listFiles() or storage.createFile().
    • File size limits: Check Appwrite's server configuration for file size limits.
    • Permissions: Verify that the user or API key has write permissions to the specified bucket.

  • Performance issues:

    • Resource allocation: Ensure your Docker environment (or deployment platform) has sufficient CPU, memory, and disk I/O allocated to Appwrite containers.
    • Database performance: Optimize your database queries and consider indexing frequently accessed fields.
    • Caching: Utilize caching mechanisms where appropriate in your application.

For further assistance, consult the official Appwrite documentation or join the Appwrite Discord community.

← Project overviewView alternatives to appwrite →