VPS Tutorials
Appwrite on a VPS: Docker, HTTPS, permissions and recovery
Deploy Appwrite with Ubuntu, Docker Compose and Caddy while keeping release-specific installers separate. Plan resources, secure projects and functions, avoid proxy port loops, configure SMTP, and back up the real database, persistent files and encryption keys before upgrades.

Appwrite combines authentication, databases, file storage, functions, messaging and APIs in a self-hosted backend. It can suit a personal application or an internal product, provided you also manage access, email, persistent storage and upgrades. A rented VPS still involves trust in its provider and administrators.
The deployment examples use Ubuntu 24.04, Docker Compose and Caddy. Version matters: the older 1.7-series examples below are not a current installation recipe. Appwrite's official installation page and latest release, checked November 16, 2026, specify 2.7.2 and a setup wizard. Use one version's complete configuration and upgrade path, rather than mixing generations.
The current documented minimum is 2 CPU cores, 4 GB RAM and 2 GB swap, with Docker Compose v2. A 1-core/2-GB machine does not meet that minimum. A 2-core/4-GB/40-GB SSD budget is an initial planning example, not a production guarantee.
| Resource | Lab planning example | Small production planning example |
|---|---|---|
| CPU | 2 vCPU | 4 vCPU or more |
| RAM | 4 GB | Around 8 GB, then measure |
| Disk | Around 30 GB SSD, subject to actual images/data | Around 80 GB SSD or more |
| Host | Ubuntu 22.04/24.04 with supported Docker | Ubuntu 24.04 LTS |
| Domain | appwrite.example.com | Dedicated application and email domains |
Check free -h, df -h and docker stats if other databases, monitoring or AI workloads share the VPS. Appwrite has several workers and queues; leave room for image pulls, uploads and function runtimes. VPS sizing helps plan that budget.
sudo apt update
sudo apt install -y ca-certificates curl git
curl -fsSL https://get.docker.com | sudo sh
sudo usermod -aG docker "$USER"
newgrp docker
sudo mkdir -p /opt/appwrite
sudo chown -R "$USER":"$USER" /opt/appwrite
cd /opt/appwrite
The convenience script runs with root privileges; review the source or use Docker's supported package installation for a managed production host. Docker-group membership also grants powerful access to the host. Keep the project and data outside temporary directories.
sudo systemctl enable --now docker
docker version
docker compose version
The historical repository example is retained for context. Do not run its literal 1.7.x checkout as a verified tag: a shallow clone may not contain the desired ref, and the source tree is not necessarily a supported production deployment template.
cd /opt/appwrite
git clone --depth=1 https://github.com/appwrite/appwrite.git source
cd source
git checkout 1.7.x
cp .env.example .env
For a new 2.7.2 installation, the official installer uses a setup wizard. On the VPS, keep its temporary port private:
cd /opt/appwrite
docker run -it --rm \
--publish 127.0.0.1:20080:20080 \
--volume /var/run/docker.sock:/var/run/docker.sock \
--volume "$PWD/appwrite:/usr/src/code/appwrite:rw" \
--entrypoint install appwrite/appwrite:2.7.2
From your workstation, forward port 20080 with SSH and open http://localhost:20080. The installer accesses Docker's socket and can create containers: use a trusted release on a host you administer. Select the final hostname, HTTPS behind the proxy, and your intended database backend. The current wizard defaults to PostgreSQL and also offers MariaDB/MongoDB; the older examples here describe MariaDB and are not instructions to change an existing backend.
Review the generated .env. This legacy variable example identifies important secrets and host settings; use the names actually supported by the chosen release:
_APP_ENV=production
_APP_OPENSSL_KEY_V1=replace-with-a-long-random-secret
_APP_DOMAIN=appwrite.example.com
_APP_DOMAIN_TARGET=appwrite.example.com
_APP_DB_HOST=mariadb
_APP_DB_USER=appwrite
_APP_DB_PASS=replace-with-a-database-password
_APP_DB_SCHEMA=appwrite
_APP_REDIS_HOST=redis
[email protected]
_APP_SYSTEM_EMAIL_NAME=Appwrite
openssl rand -hex 32 generates random material, but each setting may require a particular format. Preserve the encryption key, use unique database credentials, and keep secrets out of Git. Do not publish database, Redis, worker or internal API ports.
Run Compose in the generated project's directory, not automatically the historical source directory:
docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=100 appwrite
- Confirm
mariadbis ready when using the MariaDB deployment. - Confirm Appwrite can reach
rediswhere that topology uses Redis. - Check
appwriteand workers for recurring crashes. - Check disk/RAM after downloads and initialization.
Brief initialization activity is not a reason to ignore repeated restarts. Inspect errors and test an API call. The older tunnel below forwards the server's port 80; adapt its destination to your actual private gateway port:
ssh -L 8080:127.0.0.1:80 root@SERVER_IP
For the private 8080 gateway described next, use ssh -L 8080:127.0.0.1:8080 user@SERVER_IP. Keep the console private until its access controls and HTTPS are verified.
Point valid A/AAAA records at the VPS. Remove an unusable AAAA record rather than leaving certificate requests to fail intermittently.
sudo apt install -y caddy
sudo nano /etc/caddy/Caddyfile
Caddy and Appwrite's gateway cannot both own host port 80. Configure the generated gateway's HTTP publication as 127.0.0.1:8080:80, keep 8080 private and let Caddy own public 80/443. The following legacy example uses upstream port 80; replace that upstream with 127.0.0.1:8080 before using it, otherwise it can point back into Caddy:
appwrite.example.com {
encode gzip zstd
reverse_proxy 127.0.0.1:80
header {
Strict-Transport-Security "max-age=31536000; includeSubDomains"
X-Content-Type-Options "nosniff"
X-Frame-Options "SAMEORIGIN"
}
}
The required corrected line is reverse_proxy 127.0.0.1:8080. Preserve host/WebSocket behavior and match the Appwrite domain/HTTPS settings. Apply HSTS, especially includeSubDomains, only when the affected domains support HTTPS.
sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy
sudo journalctl -u caddy -n 80 --no-pager
If an existing gateway already owns 80/443, integrate there. Bind the application gateway to 127.0.0.1 and consult Caddy proxy troubleshooting rather than starting a competing listener.
After https://appwrite.example.com works over verified HTTPS:
- Create the administrator, project and correct Web/Android/iOS/server SDK platforms.
- Register explicit allowed hosts and callback URLs; avoid a broad
*where the setting permits it. - Grant API keys only required scopes, separating development and production.
- Use strong administrator authentication and supported MFA, with deliberate team roles.
- Give functions scoped credentials rather than long-lived master keys.
- Configure SMTP and a sender domain with SPF, DKIM and DMARC.
- Restrict the cloud firewall to necessary management and public HTTPS/HTTP ports; keep internal services private.
For maintenance, use a private network or SSH tunnel instead of exposing 3306/6379. See database exposure checks. Test project permissions with a normal client, not just an administrator key that bypasses ordinary checks.
Recoverability needs a coherent database copy, all persistent uploads/function data and the key in .env. The following is an older MariaDB/path example, not a complete backup of arbitrary named volumes:
cd /opt/appwrite/source
mkdir -p /opt/appwrite/backup
docker compose exec -T mariadb mysqldump -uappwrite -p"$APPWRITE_DB_PASS" appwrite | gzip > /opt/appwrite/backup/appwrite-$(date +%F).sql.gz
tar -czf /opt/appwrite/backup/appwrite-data-$(date +%F).tgz .env docker-compose.yml volumes/
Before adapting it, identify the selected backend and effective mounts with Compose/inspect. APPWRITE_DB_PASS in this shell example is not automatically loaded from Appwrite's differently named configuration. Use the supported dump client and protected credentials, check the dump's exit status with pipefail, and stop writes during a physical volume copy. A nonexistent volumes/ directory does not contain Docker-managed named volumes.
Save every required persistent volume separately, the generated Compose/configuration, encryption key and release identifiers. Encrypt offsite copies and protect access. Restore into a clean, matching-version test instance; verify login, file downloads, database queries and function execution. Follow the restore-drill principles. A snapshot without a tested, consistent application backup is insufficient.
The older commands below illustrate recording configuration and recreating containers. Their literal 1.7.x ref is not a verified upgrade target:
docker compose config > /opt/appwrite/backup/compose-$(date +%F).yaml
git fetch --tags
git checkout 1.7.x
docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=200
Do not follow latest unattended. Pin a supported release, test its documented database migration and required intermediate upgrades, then schedule maintenance. A database migrated forward may not work with an older image; rollback may require restoring the matching pre-upgrade data and keys. Compose config output can contain secrets, so protect the saved file.
sudo journalctl -u caddy -n 100 --no-pager
docker compose ps
docker compose logs --tail=200 appwrite
ss -lntp | grep -E ':80|:443'
Also inspect the chosen private 8080 listener. Confirm Caddy reaches the gateway rather than itself, and that the gateway reaches healthy API/worker services.
Inspect browser API host, certificate, WebSocket and callback errors, then database/Redis/worker health. For large uploads, check application limits and any explicit proxy/CDN/cloud upload limits. Caddy does not universally impose a fixed body-size limit; inspect your actual configuration.
docker compose ps
docker stats --no-stream
docker inspect appwrite --format '{{.State.OOMKilled}} {{.State.ExitCode}}'
sudo dmesg -T | grep -i -E 'oom|killed process'
The inspect command needs the real container name. Check OOM records, queues and mounts before deleting anything; remove only confirmed disposable images/logs, preserve volumes, verify swap and increase capacity where necessary. Blindly reducing worker memory can worsen queue failures.
- Domain, HTTPS, API and WebSocket work for the selected release.
- Administrator authentication, platforms, callbacks and client permissions are verified.
- Internal database, Redis and worker ports are not public.
.env, encryption keys, database, uploads and function data are backed up.- A separate instance has passed a restore drill.
- Release identifiers, migration steps and a data-aware rollback are recorded.
Appwrite becomes a maintainable backend when the full deployment, permissions and recovery process work together. Start with a test project before sending real users to the console or API.