How can I safely upgrade and rollback an Appwrite self‑hosted instance using Docker?

Upgrading a self-hosted Appwrite instance requires a structured approach to ensure data integrity and service availability. Because Appwrite runs in a containerized environment, the process primarily involves interacting with the Appwrite installation image via Docker.

Prerequisites

• Docker: Ensure Docker is installed on your host machine.
• Backups: Before initiating any upgrade, perform a full backup of your volumes and .env file to ensure you can recover your data if the process fails.
• Environment Variables: Have your current .env file accessible in the installation directory.

Upgrade Procedure

Appwrite provides a specific upgrade entrypoint to handle version transitions. Follow these steps:

1. Identify Target Version: Determine the version tag you wish to upgrade to (e.g., 2.1.0).
2. Execute Upgrade Command: Run the following command from your terminal (Unix example):
   docker run -it --rm \
--volume /var/run/docker.sock:/var/run/docker.sock \
--volume "$(pwd)"/appwrite:/usr/src/code/appwrite:rw \
--entrypoint="upgrade" \
appwrite/appwrite:2.1.0
3. Handle API Mismatches: If the upgrade fails with a "Docker API version mismatch" error (e.g., client version is too new for the host engine), add the DOCKER_API_VERSION environment variable to the command:
   --env DOCKER_API_VERSION=1.42 (Replace 1.42 with the maximum supported version indicated in your specific error message).

Verification

Once the command completes, verify the deployment using these checks:

• Console Access: Navigate to http://localhost (or your server IP) to confirm the Appwrite console loads.
• Health Checks: Use docker ps to ensure all Appwrite containers are running and healthy.
• API Responsiveness: Attempt to perform a basic operation via the API or SDK to confirm backend services are communicating.

Rollback Procedure

If the upgrade fails or causes instability, follow these steps to restore the previous state:

1. Revert Image Tag: Change the image version back to the previously stable tag in your docker-compose.yml or deployment script.
2. Restore Configuration: Re-apply the backup of the .env file created before the upgrade.
3. Restart Containers: Run docker-compose down followed by docker-compose up -d to restart the environment with the previous version.
4. Restore Data: If database migrations occurred during the upgrade, you may need to restore your volume backups to return to the previous data state.