Self-host Appwrite on a VPS

Arct Cloud provides the unmanaged Linux VPS for this deployment. Appwrite is not preinstalled or managed by Arct Cloud. You are responsible for application configuration, data, functions, email delivery, security, backups, scaling, and updates.

Choose a Plan

Appwrite’s official installation requirements specify at least 2 CPU cores, 4 GB RAM, 2 GB swap, Docker Compose v2, and a current Docker Engine.

Profile	vCPU	RAM	NVMe storage	Guidance
cvm.micro	2	4 GB	40 GB	Meets the official CPU and RAM minimum; suitable for evaluation and light development after adding 2 GB swap
cvm.small	4	8 GB	75 GB	Practical Arct starting point with more headroom for workers, builds, functions, databases, and image downloads

Appwrite does not publish a universal disk minimum. It runs many containers and stores database records, uploads, function code, site builds, certificates, and logs. Monitor memory and disk usage, then increase resources or use an external storage backend as the workload grows. These are practical starting points, not performance guarantees.

Before You Begin

Prepare the following:

A fresh Ubuntu 24.04 server
A dedicated hostname such as appwrite.example.com
An A record pointing the hostname to the VPS’s public IPv4 address
An email address for TLS certificate notifications
Encrypted off-server storage for configuration, database, and volume backups
An authenticated SMTP provider if users need verification or password recovery email

This guide uses Appwrite’s current stable 1.9.6 release and the installer’s default MongoDB backend. Check the Appwrite releases before installation and replace the version only after reviewing its release notes.

Install Appwrite

Deploy and Connect

Deploy an Ubuntu server, then connect over SSH.

Prepare DNS and the Firewall

Confirm the hostname resolves to this server:

getent ahostsv4 appwrite.example.com

Allow SSH before enabling UFW, then expose only the public web ports:

sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable
sudo ufw status

Port 20080 is used only by Appwrite’s installation wizard. The command below binds it to server loopback, so do not open it in UFW or an upstream firewall.

Install Docker Engine and Compose

Install Docker from Docker’s official Ubuntu repository:

sudo apt update
sudo apt install -y ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg \
  -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

sudo tee /etc/apt/sources.list.d/docker.sources >/dev/null <<EOF
Types: deb
URIs: https://download.docker.com/linux/ubuntu
Suites: $(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}")
Components: stable
Architectures: $(dpkg --print-architecture)
Signed-By: /etc/apt/keyrings/docker.asc
EOF

sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io \
  docker-buildx-plugin docker-compose-plugin
sudo systemctl enable --now docker
sudo docker run --rm hello-world
sudo docker compose version

Verify Memory and Add Swap

Check that the server has at least 4 GB RAM and 2 GB swap:

free -h
swapon --show

On a fresh server with no swap, create the 2 GB swap file required by Appwrite:

sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
grep -qF '/swapfile none swap sw 0 0' /etc/fstab \
  || echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab
swapon --show

Run the swap creation commands only when swapon --show is empty and /swapfile does not already exist.

Start the Installer Privately

Create the parent directory, then run Appwrite’s official installer with two deliberate safeguards: an exact image tag and a loopback-only wizard port.

sudo install -d -m 0750 -o "$USER" -g "$USER" /opt/appwrite
cd /opt

sudo 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:1.9.6

Leave this SSH session open while the installer waits for the web wizard.

The installer controls Docker through /var/run/docker.sock, which is equivalent to root access on the host. Use only Appwrite’s official image with a reviewed release tag.

Complete the Private Setup Wizard

From a second terminal on your local computer, open an SSH tunnel:

ssh -N -L 20080:127.0.0.1:20080 ubuntu@YOUR_SERVER_IP

Open http://127.0.0.1:20080 and complete the wizard:

Enter appwrite.example.com as the hostname.
Keep MongoDB selected unless you have planned a MariaDB deployment and backup strategy.
Configure automatic HTTPS and its notification email.
Generate the application encryption key and save it outside the VPS.
Create the root console account with a unique password.
Review the settings, then start the installation.

The setup wizard remains private for the entire first-account flow. Stop the tunnel with Ctrl+C only after the installer finishes and the root account exists.

Rotate Default Service Secrets

Appwrite’s database security guidance requires changing the database credentials before production. The 1.9.6 wizard sets the application encryption key, but its generated configuration retains known defaults for _APP_DB_PASS, _APP_DB_ROOT_PASS, and _APP_EXECUTOR_SECRET. Rotate all three immediately after setup and before creating projects or accepting production data.The following MongoDB-specific maintenance flow creates a root-only recovery set, transfers new values without printing them or placing them in host-side command arguments, changes the database credentials, atomically updates .env, and recreates every service with matching values:

(
  set -euo pipefail
  cd /opt/appwrite
  sudo chmod 0600 .env

  pre_rotate_dir="/root/appwrite-pre-rotation-$(date -u +%Y%m%dT%H%M%SZ)"
  sudo install -d -m 0700 "$pre_rotate_dir"
  sudo cp -p .env docker-compose.yml "$pre_rotate_dir/"

  rotation_dir="$(sudo mktemp -d /root/appwrite-rotation.XXXXXX)"
  candidate_env="$(sudo mktemp /opt/appwrite/.env.rotate.XXXXXX)"
  rotation_finished=false
  report_rotation_state() {
    if [ "$rotation_finished" = false ]; then
      printf 'Rotation stopped. Keep recovery data in %s, %s, and %s if present.\n' \
        "$pre_rotate_dir" "$rotation_dir" "$candidate_env" >&2
    fi
  }
  trap report_rotation_state EXIT

  sudo sh -c '
    set -eu
    umask 077
    openssl rand -hex 32 >"$1/db-pass"
    openssl rand -hex 32 >"$1/db-root-pass"
    openssl rand -hex 32 >"$1/executor-secret"
  ' sh "$rotation_dir"

  sudo bash -s -- "$rotation_dir" "$candidate_env" <<'BUILD_ENV'
set -euo pipefail
secret_dir="$1"
candidate="$2"
env_file="/opt/appwrite/.env"

db_pass="$(<"$secret_dir/db-pass")"
db_root_pass="$(<"$secret_dir/db-root-pass")"
executor_secret="$(<"$secret_dir/executor-secret")"
seen_db=0
seen_root=0
seen_executor=0

while IFS= read -r line || [[ -n "$line" ]]; do
  case "$line" in
    _APP_DB_PASS=*)
      printf '_APP_DB_PASS="%s"\n' "$db_pass"
      ((seen_db += 1))
      ;;
    _APP_DB_ROOT_PASS=*)
      printf '_APP_DB_ROOT_PASS="%s"\n' "$db_root_pass"
      ((seen_root += 1))
      ;;
    _APP_EXECUTOR_SECRET=*)
      printf '_APP_EXECUTOR_SECRET="%s"\n' "$executor_secret"
      ((seen_executor += 1))
      ;;
    *) printf '%s\n' "$line" ;;
  esac
done <"$env_file" >"$candidate"

if (( seen_db != 1 || seen_root != 1 || seen_executor != 1 )); then
  echo 'Expected each Appwrite secret exactly once; rotation was not started.' >&2
  exit 1
fi

chown root:root "$candidate"
chmod 0600 "$candidate"
BUILD_ENV

  sudo docker compose stop
  sudo docker compose up -d --wait mongodb
  sudo docker compose exec -T mongodb sh -c \
    'exec mongodump --username=root --password="$MONGO_INITDB_ROOT_PASSWORD" --authenticationDatabase=admin --archive' \
    | sudo tee "$pre_rotate_dir/mongodb.archive" >/dev/null
  sudo docker compose cp \
    "$rotation_dir/db-pass" mongodb:/tmp/appwrite-new-db-pass
  sudo docker compose cp \
    "$rotation_dir/db-root-pass" mongodb:/tmp/appwrite-new-db-root-pass

  sudo docker compose exec -T mongodb bash -se <<'ROTATE_MONGO'
set -euo pipefail
export NEW_DB_PASS="$(cat /tmp/appwrite-new-db-pass)"
export NEW_ROOT_PASS="$(cat /tmp/appwrite-new-db-root-pass)"

mongosh --quiet \
  --username "$MONGO_INITDB_ROOT_USERNAME" \
  --password "$MONGO_INITDB_ROOT_PASSWORD" \
  --authenticationDatabase admin \
  --eval '
    const admin = db.getSiblingDB("admin");
    admin.changeUserPassword(
      process.env.MONGO_INITDB_USERNAME,
      process.env.NEW_DB_PASS
    );
    admin.changeUserPassword(
      process.env.MONGO_INITDB_ROOT_USERNAME,
      process.env.NEW_ROOT_PASS
    );
  '

rm -f /tmp/appwrite-new-db-pass /tmp/appwrite-new-db-root-pass
ROTATE_MONGO

  sudo mv -- "$candidate_env" /opt/appwrite/.env
  sudo docker compose up -d --force-recreate --wait
  sudo docker compose exec -T mongodb bash -se <<'VERIFY_MONGO'
mongosh --quiet \
  --username "$MONGO_INITDB_USERNAME" \
  --password "$MONGO_INITDB_PASSWORD" \
  --authenticationDatabase admin \
  --eval 'if (db.getSiblingDB(process.env.MONGO_INITDB_DATABASE).runCommand({ ping: 1 }).ok !== 1) { quit(1); }' \
  >/dev/null
VERIFY_MONGO

  sudo docker compose exec -T appwrite sh -ec '
    printf "header = \"Authorization: Bearer %s\"\n" \
      "$_APP_EXECUTOR_SECRET" \
      | curl --config - --fail --silent --show-error \
          "${_APP_EXECUTOR_HOST}/health" >/dev/null
  '
  sudo docker exec appwrite doctor
  sudo docker compose ps

  sudo bash <<'CHECK_SECRETS'
set -euo pipefail
declare -A secret=()

while IFS='=' read -r key raw; do
  case "$key" in
    _APP_OPENSSL_KEY_V1|_APP_DB_PASS|_APP_DB_ROOT_PASS|_APP_EXECUTOR_SECRET)
      raw="${raw#\"}"
      raw="${raw%\"}"
      secret["$key"]="$raw"
      ;;
  esac
done </opt/appwrite/.env

bad=0
for key in \
  _APP_OPENSSL_KEY_V1 \
  _APP_DB_PASS \
  _APP_DB_ROOT_PASS \
  _APP_EXECUTOR_SECRET
do
  current="${secret[$key]-}"
  if (( ${#current} < 32 )); then
    printf '%s is missing or shorter than 32 characters.\n' "$key" >&2
    bad=1
  fi
  case "$current" in
    your-secret-key|password|rootsecretpassword)
      printf '%s still uses an Appwrite default.\n' "$key" >&2
      bad=1
      ;;
  esac
done

if [[ "${secret[_APP_DB_PASS]-}" == "${secret[_APP_DB_ROOT_PASS]-}" ||
      "${secret[_APP_DB_PASS]-}" == "${secret[_APP_EXECUTOR_SECRET]-}" ||
      "${secret[_APP_DB_ROOT_PASS]-}" == "${secret[_APP_EXECUTOR_SECRET]-}" ]]; then
  echo 'Appwrite secrets must be distinct.' >&2
  bad=1
fi

(( bad == 0 ))
echo 'Required Appwrite secrets are non-default, sufficiently long, and distinct.'
CHECK_SECRETS

  sudo rm -f -- \
    "$rotation_dir/db-pass" \
    "$rotation_dir/db-root-pass" \
    "$rotation_dir/executor-secret"
  sudo rmdir -- "$rotation_dir"
  rotation_finished=true
  trap - EXIT
  printf 'Pre-rotation recovery set: %s\n' "$pre_rotate_dir"
)

This sequence is only for the MongoDB deployment in this guide. If it stops after changing MongoDB, do not restart the full stack or delete /root/appwrite-rotation.* or /opt/appwrite/.env.rotate.*. Keep the root-only recovery files, determine which credential changes completed, then finish installing the candidate .env or restore on a fresh instance.

Copy .env and the pre-rotation recovery set to encrypted off-server storage. Never regenerate _APP_OPENSSL_KEY_V1 on an existing instance: Appwrite uses it to protect passwords, OAuth secrets, API keys, and other sensitive values.

Verify the Deployment

Confirm the containers are healthy, then make the first HTTPS request. Appwrite can initially present a self-signed certificate; the first request triggers certificate issuance. Use --insecure only for that initial probe, wait for the certificate to be issued in the logs, and require the final check to pass normal TLS validation:

cd /opt/appwrite
sudo docker compose ps
curl --insecure --head https://appwrite.example.com
sudo docker compose logs --tail=50 appwrite traefik mongodb redis
curl --fail --show-error --head https://appwrite.example.com
sudo docker exec appwrite doctor

Sign in with the root account created in the private wizard, create a test project, and verify that its API endpoint uses https://appwrite.example.com/v1.

Production Security and Operations

Only ports 22, 80, and 443 should normally be public. Port 20080 is temporary and loopback-only. Database, Redis, worker, executor, and Docker API ports must remain private. Before storing production data:

Keep _APP_OPENSSL_KEY_V1 unchanged and backed up separately from the database
Require the default-secret rotation and non-printing validation above to pass
Force HTTPS and confirm no application SDK uses the plain HTTP endpoint
Keep console registration restricted to the root user and invite additional developers
Use Appwrite’s console IP or email allowlists when the dashboard needs tighter access
Keep Appwrite’s abuse protection and rate limits enabled
Configure authenticated SMTP and test verification and password-reset delivery
Use least-privilege API keys and review function permissions and runtime limits
Monitor CPU, RAM, swap, disk, container health, and log growth

Docker-published ports can bypass ordinary UFW forwarding rules. The wizard port is safe here because it is explicitly bound to 127.0.0.1; review every future Compose ports change before applying it.

Back Up and Restore

Self-hosted Appwrite does not provide automatic backups. A complete recovery set includes the database, Appwrite storage volumes, .env, docker-compose.yml, the encryption key, and the exact image versions. For the MongoDB deployment used in this guide, the following maintenance-window example records the configuration, stops Appwrite, creates an official logical database dump, and archives every non-database Compose-managed volume:

(
  set -euo pipefail
  cd /opt/appwrite

  stamp="$(date -u +%Y%m%dT%H%M%SZ)"
  backup_dir="/opt/appwrite-backups/${stamp}"
  sudo install -d -m 0700 -o "$USER" -g "$USER" "$backup_dir"

  sudo cp -p .env docker-compose.yml "$backup_dir/"
  sudo chown "$USER:$USER" "$backup_dir/.env" \
    "$backup_dir/docker-compose.yml"
  sudo docker compose config --images >"$backup_dir/images.txt"
  sudo docker compose config --volumes >"$backup_dir/volumes.txt"
  mapfile -t appwrite_volumes < <(
    sudo docker volume ls -q \
      --filter label=com.docker.compose.project=appwrite
  )
  test "${#appwrite_volumes[@]}" -gt 0
  sudo docker pull ubuntu:24.04

  stopped=false
  restart_appwrite() {
    if [ "$stopped" = true ]; then
      sudo docker compose up -d || true
    fi
  }
  trap restart_appwrite EXIT
  trap 'exit 130' INT
  trap 'exit 143' TERM

  stopped=true
  sudo docker compose down

  sudo docker compose up -d --wait mongodb
  sudo docker compose exec -T mongodb sh -c \
    'exec mongodump --username=root --password="$MONGO_INITDB_ROOT_PASSWORD" --authenticationDatabase=admin --archive' \
    >"$backup_dir/mongodb.archive"
  sudo docker compose stop mongodb

  for volume in "${appwrite_volumes[@]}"; do
    case "$volume" in
      *mongodb*|*mariadb*|*postgresql*) continue ;;
    esac
    sudo docker run --rm \
      --volume "${volume}:/data:ro" \
      --volume "${backup_dir}:/backup" \
      ubuntu:24.04 \
      tar -czf "/backup/${volume}.tar.gz" -C /data .
  done

  sudo docker compose up -d
  stopped=false
  trap - EXIT INT TERM

  sudo chown -R "$USER:$USER" "$backup_dir"
  chmod -R go-rwx "$backup_dir"
  printf 'Appwrite backup ready: %s\n' "$backup_dir"
)

Copy the entire timestamped directory to encrypted storage outside the VPS and test it on a separate server. If you select MariaDB in the installer, use Appwrite’s documented mysqldump procedure instead of the MongoDB command. Restore only into a fresh installation running the matching Appwrite and database versions. For this MongoDB path, restore mongodb.archive into the fresh database, then restore the non-database storage archives with the saved configuration and encryption key. Do not also restore a raw MongoDB data volume: logical database restore and raw database-volume restore are alternative recovery methods. Never restore over a live database or delete the current volumes until the replacement instance has passed login, API, upload, function, and project checks.

Update and Migrate Safely

Appwrite updates can change both its Compose project and data schema. Before every update:

Create and verify a complete off-server backup.
Read every intervening release note.
Record the current image tags and keep the existing VPS available.
Test the same upgrade path on a replacement instance.

Run the official upgrade tool from the parent directory, replacing the example variable with an exact release tag:

cd /opt
APPWRITE_VERSION=REPLACE_WITH_EXACT_RELEASE_TAG

sudo 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="upgrade" \
  "appwrite/appwrite:${APPWRITE_VERSION}"

Leave that command running while it waits for the private upgrade wizard. From a second terminal on your local computer, recreate the SSH tunnel:

ssh -N -L 20080:127.0.0.1:20080 ubuntu@YOUR_SERVER_IP

Open http://127.0.0.1:20080, review the detected deployment and exact target release, then complete the upgrade wizard. Close the tunnel only after the upgrade command finishes. Patch releases do not always require a data migration. Run the migration command only when the release notes require it:

cd /opt/appwrite
sudo docker compose exec appwrite migrate
sudo docker compose ps
sudo docker compose logs --tail=100 appwrite

When crossing minor versions, Appwrite requires upgrading through each minor version’s latest patch. Do not start an older Appwrite image against data that a newer migration has changed. If an update fails, restore the complete pre-update recovery set on a fresh matching-version server instead of attempting an in-place downgrade.

Troubleshooting

The installation wizard does not open

Keep the installer terminal running, confirm sudo ss -lntp | grep ':20080' shows a loopback listener, and reconnect the SSH tunnel. Do not change the mapping to 0.0.0.0:20080 as a shortcut.

HTTPS certificate issuance fails

Confirm the A record points to this VPS, remove an incorrect AAAA record, and verify ports 80 and 443 are reachable. Review the Traefik and Appwrite logs for ACME or hostname errors.

Containers restart or the server becomes unresponsive

Run free -h, swapon --show, df -h, and sudo docker stats. Appwrite’s many workers and build images can exceed the minimum profile; add memory or storage before increasing worker concurrency.

Users do not receive verification or reset email

Configure an authenticated SMTP provider, normally on submission port 587, then test delivery and inspect the worker logs. Do not rely on unauthenticated local mail delivery.

An update or migration fails

Stop retrying against production data. Inspect the first migration error and the exact release notes, then recover on a separate server from the pre-update database, volumes, configuration, and encryption key.

Official Resources

Appwrite Installation

Official requirements, Docker installer, setup wizard, and manual Compose files.

Production Checklist

Security, scaling, email, monitoring, backups, and update guidance.

Appwrite on GitHub

Source code, releases, security policy, and issue tracker.

Appwrite is developed by Appwrite. Arct Cloud is an independent infrastructure provider and is not affiliated with, sponsored by, or endorsed by Appwrite.

Getting Started

Virtual Machines

Migrations

Billing & Payments

Account

Self-host Appwrite on a VPS

Choose a Plan

Before You Begin

Install Appwrite

Production Security and Operations

Back Up and Restore

Update and Migrate Safely

Troubleshooting

Official Resources

Appwrite Installation

Production Checklist

Appwrite on GitHub

​Choose a Plan

​Before You Begin

​Install Appwrite

​Production Security and Operations

​Back Up and Restore

​Update and Migrate Safely

​Troubleshooting

​Official Resources

Appwrite Installation

Production Checklist

Appwrite on GitHub

Choose a Plan

Before You Begin

Install Appwrite

Production Security and Operations

Back Up and Restore

Update and Migrate Safely

Troubleshooting

Official Resources