Appw CLI

CLI tool to automate Appwrite backup and restore operations using Docker commands.

Features

• 🔄 Full Backup & Restore: Complete backup of MariaDB database and all Docker volumes
• 📦 Partial Restore: Restore only specific components (database, functions, uploads, or builds)
• ✅ Integrity Verification: Verify backup files before attempting restore
• ⏸️ Automatic Container Management: Optional stop/restart of Appwrite containers
• 🏷️ Custom Prefixes: Support for custom container name prefixes
• 📅 Timestamped Backups: Automatic timestamping to prevent overwrites
• 🔐 OpenSSL Key Management: Automatic backup and validation of encryption keys

Prerequisites

• Docker: Must be installed and running
• Node.js: Version 16.0.0 or higher
• Appwrite: Self-hosted instance with Docker containers

Installation

From npm (when published)

npm install -g appw-cli

From source

git clone <repository-url>
cd appw-cli
npm install
npm run build
npm link

Usage

Backup Command

Create a complete backup of your Appwrite instance:

appw backup

By default, the backup command will:

• Stop all Appwrite containers before backing up volumes
• Create backups of the database and all volumes
• Restart all containers after completion

Options

• -p, --prefix <prefix>: Container name prefix (default: appwrite)
• -o, --output <directory>: Output directory for backups (default: ./backups)
• -d, --database-only: Backup only the database (skips volumes and container restart)

Examples

# Full backup (stops containers, backs up everything, restarts containers)
appw backup

# Backup with custom prefix
appw backup --prefix myappwrite

# Database-only backup (containers keep running, no volumes backed up)
appw backup --database-only

# Backup to specific directory
appw backup --output /var/backups/appwrite

What gets backed up

1. MariaDB Database (dump.sql) - All databases, collections, documents, users, and configurations
2. Functions Volume (functions.tar) - All cloud function data
3. Uploads Volume (uploads.tar) - All uploaded files
4. Builds Volume (builds.tar) - All build artifacts
5. Configuration (config.json) - Backup metadata and _APP_OPENSSL_KEY_V1

Restore Command

Restore your Appwrite instance from a backup:

appw restore ./backups/backup-2025-11-25-143022

By default, the restore command will:

• Stop all Appwrite containers before restoring volumes
• Restore the database and all volumes
• Restart all containers after completion

Options

• -p, --prefix <prefix>: Container name prefix (default: appwrite)
• --only-database: Restore only the database (containers keep running)
• --only-functions: Restore only the functions volume
• --only-uploads: Restore only the uploads volume
• --only-builds: Restore only the builds volume

Examples

# Full restore (stops containers, restores everything, restarts containers)
appw restore ./backups/backup-2025-11-25-143022

# Restore only the database (containers keep running)
appw restore ./backups/backup-2025-11-25-143022 --only-database

# Restore only uploads and functions
appw restore ./backups/backup-2025-11-25-143022 --only-uploads --only-functions

# Restore to different Appwrite instance
appw restore ./backups/backup-2025-11-25-143022 --prefix myappwrite

Verify Command

Verify the integrity of a backup before restoring:

appw verify ./backups/backup-2025-11-25-143022

What gets verified

• ✅ Backup directory structure
• ✅ Presence of all required files
• ✅ Configuration file validity
• ✅ File sizes (warns if empty or suspiciously small)
• ✅ TAR archive integrity
• ✅ SQL dump format validation
• ✅ OpenSSL key presence

Examples

# Verify a backup
appw verify ./backups/backup-2025-11-25-143022

# Verify before restore
appw verify ./backups/backup-2025-11-25-143022 && \
appw restore ./backups/backup-2025-11-25-143022

Backup Structure

Each backup creates a timestamped directory:

backups/
└── backup-2025-11-25-143022/
    ├── dump.sql          # MariaDB database dump
    ├── functions.tar     # Functions volume backup
    ├── uploads.tar       # Uploads volume backup
    ├── builds.tar        # Builds volume backup
    └── config.json       # Backup configuration

config.json Example

{
  "timestamp": "2025-11-25-143022",
  "opensslKey": "your-openssl-key-here",
  "prefix": "appwrite",
  "version": "1.6.0"
}

Note: The version field stores the Appwrite version extracted from the Docker image (e.g., appwrite/appwrite:1.6.0). If the version cannot be determined, it will be set to "unknown".

Container Naming

The CLI expects Appwrite containers to follow this naming pattern:

• Main container: {prefix} (e.g., appwrite)
• MariaDB container: {prefix}-mariadb (e.g., appwrite-mariadb)
• Other containers: {prefix}-* (e.g., appwrite-redis, `appwrite-worker-*)

If your containers use a different prefix, specify it with --prefix:

appw backup --prefix myapp

Best Practices

1. Full Backups for Production

For production environments, always use full backups (default behavior):

appw backup

This ensures data consistency by stopping containers during volume backups.

2. Verify Backups

Always verify backups after creation:

appw backup
appw verify ./backups/backup-2025-11-25-143022

3. Test Restores

Periodically test your restore process in a non-production environment.

4. Store Backups Safely

• Keep backups in multiple locations
• Store backups on different servers/cloud storage
• Consider encrypting backup files

5. Automated Backups

Use cron for scheduled backups:

# Daily full backup at 2 AM
0 2 * * * /usr/local/bin/appw backup --output /var/backups/appwrite

# Hourly database-only backup (faster, no downtime)
0 * * * * /usr/local/bin/appw backup --database-only --output /var/backups/appwrite-hourly

6. Backup Retention

Implement a retention policy to manage disk space:

# Keep only last 7 days of backups
find /var/backups/appwrite -type d -name "backup-*" -mtime +7 -exec rm -rf {} \;

Troubleshooting

Permission Denied

If you get permission errors when running Docker commands:

# Add your user to the docker group
sudo usermod -aG docker $USER

# Or run with sudo
sudo appw backup

Container Not Found

If the CLI cannot find your containers:

# List all containers to find your prefix
docker ps -a

# Use the correct prefix
appw backup --prefix your-actual-prefix

OpenSSL Key Warning

If you see a warning about missing _APP_OPENSSL_KEY_V1:

1. Check your Appwrite .env file for the key
2. Manually add it to config.json if needed
3. Ensure it's set correctly before restoring

Large Backup Files

For large Appwrite instances:

• Ensure sufficient disk space
• Consider backing up to external storage
• Use --only-* flags for partial restores if needed

Migration Between Servers

To migrate Appwrite from one server to another:

1. On source server:

   appw backup

2. Transfer backup:

   scp -r ./backups/backup-2025-11-25-143022 user@destination:/path/

3. On destination server:

   # Ensure Appwrite is installed and containers exist
   appw restore ./backup-2025-11-25-143022

4. Verify _APP_OPENSSL_KEY_V1:

   • The key is automatically backed up in config.json
   • Ensure it matches in your destination server's .env file

Environment Variables

The CLI reads the following from Docker containers:

• MYSQL_USER - MariaDB username (defaults to root)
• MYSQL_PASSWORD - MariaDB password
• _APP_OPENSSL_KEY_V1 - Appwrite encryption key (backed up in config.json)

Development

Build from source

npm install
npm run build

Run in development mode

npm run dev

Link locally

npm link

License

MIT

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

Support

For issues and questions:

• Check the troubleshooting section
• Review Appwrite's official backup documentation
• Open an issue on GitHub

Disclaimer

This tool is not officially affiliated with Appwrite. Always test backups and restores in a non-production environment first. The authors are not responsible for any data loss.