Установка и настройка Appwrite на VPS: развёртывание

1. Що ми налаштовуємо та навіщо

Appwrite — це комплексна платформа, яка абстрагує складність розробки бекенда, надаючи розробникам набір API для вирішення типових задач. У 2026 році, коли вартість хмарних ресурсів в екосистемах Google та AWS продовжує рости, а вимоги до суверенітету даних стають жорсткішими, self-hosted рішення виходять на перший план.

Основна проблема Firebase та аналогічних SaaS-рішень полягає у "vendor lock-in" (прив'язці до постачальника). Якщо ваш додаток раптово стане популярним, рахунки за базу даних NoSQL можуть вирости експоненціально. Перенесення даних з Firebase — це завжди складний та болісний процес. Appwrite вирішує цю проблему, пропонуючи аналогічний функціонал, але на вашому власному залізі.

Основні можливості Appwrite:

• Database: Документоорієнтована база даних з підтримкою складних запитів, фільтрації та управління правами доступу на рівні документа.
• Authentication: Підтримка більше 30 OAuth-провайдерів (Google, GitHub, Apple та ін.), вхід за магічними посиланнями, телефоном та класичними парами логін/пароль.
• Storage: Управління завантаженням файлів з автоматичним стисненням, зміною розміру зображень та антивірусним скануванням.
• Functions: Можливість запускати кастомний код на різних мовах (Node.js, Python, PHP, Ruby, Go, Rust) у відповідь на події в системі або за розкладом.
• Realtime: Миттєва синхронізація даних через WebSockets.

Розгортання Appwrite на VPS дає вам повний контроль над ресурсами. Ви самі вирішуєте, скільки оперативної пам'яті виділити під Redis для кешування або який обсяг дискового простору віддати під медіа-файли користувачів.

2. Який VPS-конфіг потрібен під цю задачу

Appwrite — це мікросервісна архітектура, запакована в Docker-контейнери. У стандартній поставці запускається близько 20–25 контейнерів (MariaDB, Redis, InfluxDB, Telegraf, Traefik, Worker-и та сам API). Це потребує певних ресурсів для стабільної роботи, особливо якщо ви плануєте використовувати Serverless-функції.

Для невеликих проектів, стартапів на стадії MVP або особистих пет-проектів ідеально підійде відповідний VPS з 4 ГБ оперативної пам'яті. Appwrite споживає близько 1.5–2 ГБ RAM в стані спокою, решта необхідна для кешування бази даних та роботи Docker-демона.

Коли варто вибрати Dedicated сервер? Якщо ваш додаток передбачає інтенсивну роботу з зображеннями (обробка тисяч фото на годину) або якщо база даних розростається до сотень гігабайт. В інших випадках сучасний VPS на NVMe дисках забезпечить достатню продуктивність за рахунок високої швидкості введення-виведення (IOPS).

Локація сервера: Вибирайте локацію, максимально близьку до вашої цільової аудиторії. Для Appwrite це критично через використання Realtime API (WebSockets) — чим нижча затримка (RTT), тим "чутливішим" буде інтерфейс вашого додатку.

3. Підготовка сервера

Після придбання сервера та отримання доступу через SSH, насамперед необхідно забезпечити безпеку та актуальність системи. Ми будемо використовувати Ubuntu 24.04 LTS як найбільш збалансований дистрибутив для Docker-середовищ.

Оновлення системи та створення користувача

Не рекомендується працювати під користувачем root. Створимо окремого користувача з привілеями sudo.

# Оновлюємо індекси пакетів та систему
apt update && apt upgrade -y

# Створюємо користувача (замініть 'deploy' на ваше ім'я)
adduser deploy

# Додаємо користувача до групи sudo
usermod -aG sudo deploy

# Перемикаємось на нового користувача
su - deploy

Налаштування брандмауера (UFW)

Appwrite вимагає відкритих портів 80 (HTTP) та 443 (HTTPS) для роботи веб-інтерфейсу та API, а також порт 22 для SSH.

# Дозволяємо SSH (важливо зробити це першим!)
sudo ufw allow ssh

# Дозволяємо веб-трафік
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp

# Вмикаємо брандмауер
sudo ufw enable

Встановлення базових утиліт

Нам знадобляться інструменти для діагностики та роботи з мережею.

sudo apt install -y curl git vim htop software-properties-common apt-transport-https ca-certificates

4. Встановлення Docker та Docker Compose

Appwrite повністю покладається на Docker. У 2026 році ми використовуємо Docker Engine та плагін Docker Compose V2 (команда docker compose без дефіса).

Додавання офіційного репозиторію Docker

# Додаємо GPG ключ Docker
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
sudo chmod a+r /etc/apt/keyrings/docker.gpg

# Налаштовуємо репозиторій
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Встановлюємо Docker
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Перевірка встановлення та налаштування прав

Щоб запускати Docker без sudo, додамо нашого користувача до відповідної групи:

sudo usermod -aG docker ${USER}
# Застосуйте зміни груп без перезавантаження
newgrp docker
# Перевіряємо версію
docker compose version

5. Встановлення Appwrite: покроковий процес

Розробники Appwrite надають зручний скрипт-інсталятор, який в інтерактивному режимі генерує файл docker-compose.yml та .env змінні.

Запуск інсталятора

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:latest

Відповіді на питання інсталятора:

1. Choose your server hostname: Введіть ваш домен (наприклад, api.myapp.com) або IP-адресу сервера. Краще відразу використовувати домен для автоматичної генерації SSL.
2. Choose your HTTP port: Залиште 80.
3. Choose your HTTPS port: Залиште 443.
4. Choose your Secret API Key: Натисніть Enter, щоб згенерувати випадковий ключ (обов'язково збережіть його пізніше з файлу .env).
5. Choose your Appwrite Root Domain: Знову ваш домен.
6. Choose your DNS Records: Тут можна залишити значення за замовчуванням.

Після завершення роботи скрипта в поточній директорії з'явиться папка appwrite. Перейдіть до неї та запустіть контейнери:

cd appwrite
docker compose up -d

Процес першого запуску може зайняти 2–5 хвилин, оскільки Docker має завантажити всі необхідні образи (загальний обсяг близько 1.5 ГБ).

Перевірте статус контейнерів:

docker compose ps

Всі контейнери повинні мати статус Up (healthy).

6. Тонке налаштування: змінні оточення та SMTP

За замовчуванням Appwrite працює, але для повноцінного використання (наприклад, відправки листів для підтвердження реєстрації) потрібно відредагувати файл .env.

Налаштування SMTP (Пошта)

Без цього ваші користувачі не зможуть відновлювати паролі. Відкрийте файл: nano .env і знайдіть секцію пошти. Приклад налаштування для використання зовнішнього сервісу (наприклад, SendGrid, Mailgun або власного SMTP):

_APP_SMTP_HOST=smtp.sendgrid.net
_APP_SMTP_PORT=587
_APP_SMTP_SECURE=tls
_APP_SMTP_USERNAME=apikey
_APP_SMTP_PASSWORD=your_super_secret_key
[email protected]
_APP_EMAIL_NAME=My App Support

Налаштування лімітів завантаження

Якщо ваш додаток працює з важким контентом, збільште ліміти:

_APP_STORAGE_LIMIT=52428800 # Ліміт в байтах (тут 50MB)
_APP_STORAGE_PREVIEW_LIMIT=20971520 # Ліміт для прев'ю

Безпека

Переконайтеся, що змінна _APP_ENV встановлена у значення production. Це вимкне детальні повідомлення про помилки, які можуть допомогти зловмисникам.

_APP_ENV=production

Після внесення змін до .env, необхідно перезапустити контейнери:

docker compose up -d

7. Налаштування домену та SSL/TLS

Appwrite постачається з вбудованим проксі-сервером Traefik, який вміє автоматично отримувати сертифікати Let's Encrypt. Однак для цього мають бути виконані дві умови:

• Ваш домен (A-запис) повинен вказувати на IP-адресу вашого VPS.
• Порти 80 і 443 повинні бути відкриті і не зайняті іншими процесами (наприклад, Nginx або Apache).

Якщо ви хочете використовувати власний Nginx як Reverse Proxy (наприклад, якщо на сервері вже живуть інші сайти), вам потрібно змінити порти Appwrite в .env:

_APP_OPTIONS_FORCE_HTTPS=disabled # Якщо SSL термінується на зовнішньому Nginx
_APP_HTTP_PORT=8080
_APP_HTTPS_PORT=8443

Потім у конфігу Nginx прокиньте трафік:

server {
    listen 80;
    server_name api.myapp.com;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl;
    server_name api.myapp.com;

    ssl_certificate /etc/letsencrypt/live/api.myapp.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/api.myapp.com/privkey.pem;

    location / {
        proxy_pass http://localhost:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

8. Бекапи та обслуговування системи

Self-hosted рішення накладає на вас відповідальність за збереження даних. В Appwrite потрібно бекапити три основні речі:

1. Файл .env (там ключі шифрування, без них дані в БД стануть некорисні).
2. Дамп бази даних MariaDB.
3. Вміст папки storage (завантажені файли).

Простий скрипт бекапу

Створіть файл backup.sh:

#!/bin/bash
BACKUP_DIR="/home/deploy/backups/$(date +%Y-%m-%d)"
mkdir -p $BACKUP_DIR

# Бекап конфіга
cp /home/deploy/appwrite/.env $BACKUP_DIR/

# Бекап бази даних (через docker exec)
docker exec appwrite-mariadb mysqldump -u root --password=$(grep _APP_DB_ROOT_PASS /home/deploy/appwrite/.env | cut -d'=' -f2) appwrite > $BACKUP_DIR/db_dump.sql

# Бекап файлів (архівація)
tar -czf $BACKUP_DIR/storage.tar.gz /home/deploy/appwrite/storage

# Видалення бекапів старше 7 днів
find /home/deploy/backups/ -mtime +7 -exec rm -rf {} \;

0 3    /bin/bash /home/deploy/backup.sh

Оновлення Appwrite

Оновлення виходять часто. Щоб оновитися, виконайте:

# Зайдіть в папку
cd ~/appwrite

# Зробіть бекап! (див. вище)

# Запустіть інсталятор тієї ж версії або latest
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:latest

Скрипт побачить існуючу інсталяцію і запропонує оновити образи, зберігши ваші дані.

9. Troubleshooting + FAQ

Контейнери постійно перезавантажуються (Restarting)

Найчастіше це відбувається через нестачу оперативної пам'яті. Appwrite вимагає мінімум 2 ГБ, але на практиці при 2 ГБ MariaDB може "вилітати" по OOM (Out of Memory). Переконайтеся, що у вас налаштовано Swap-файл, якщо пам'яті впритул.

# Створення swap на 2ГБ
sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

Помилка "Invalid Custom Domain"

Перевірте, що в .env змінна _APP_DOMAIN збігається з тим, що ви вводите в браузері. Також переконайтеся, що DNS записи оновилися (може зайняти до 24 годин, використовуйте dig yourdomain.com для перевірки).

Як скинути пароль адміністратора?

В Appwrite перший зареєстрований користувач автоматично стає адміністратором. Якщо ви втратили доступ, найпростіше створити нового користувача через API або консоль і вручну змінити його роль в базі даних MariaDB, але офіційний шлях — використання CLI Appwrite.

Який VPS-конфіг мінімально підійде?

Для розробки достатньо 1 vCPU і 2 ГБ RAM. Однак для стабільної роботи панелі управління і хоча б декількох паралельних запитів до API, ми настійно рекомендуємо 2 vCPU і 4 ГБ RAM. Це забезпечить плавну роботу Docker-контейнерів і запобіжить затримки при запису в базу даних.

Що вибрати — VPS або Dedicated для цієї задачі?

Для 95% додатків на стадії росту достатньо VPS. Віртуалізація дозволяє легко масштабувати ресурси (додати RAM або CPU) без переїзду. Dedicated сервер варто вибирати тільки якщо вам потрібно зберігати терабайти даних локально або якщо у вас дуже специфічні вимоги до безпеки (ізоляція на рівні заліза).

Не приходять листи для підтвердження пошти

Перевірте логи контейнера worker-mails:

docker compose logs appwrite-worker-mails

Часта проблема — блокування порту 25 або 587 провайдером VPS. Переконайтеся, що вихідний поштовий трафік дозволено в панелі управління провайдера.

10. Висновки та наступні кроки

Ми успішно розгорнули self-hosted альтернативу Firebase на власному сервері. Тепер у вас є повний контроль над даними, відсутність прихованих платежів за кількість запитів і потужний інструмент для розробки мобільних і веб-додатків.

Що робити далі:

• Налаштуйте моніторинг: Підключіть зовнішню систему моніторингу (наприклад, UptimeRobot або Grafana), щоб знати, якщо сервер впаде.
• Оптимізуйте безпеку: Налаштуйте 2FA в панелі управління Appwrite і обмежте доступ до портів бази даних.
• Вивчіть SDK: Почніть інтеграцію з вашим фронтендом, використовуючи офіційні SDK для Flutter, React, Vue або Swift.

Пам'ятайте, що обслуговування власного бекенда вимагає регулярної уваги до оновлень безпеки ОС і самого Appwrite. Раз на місяць перевіряйте наявність нових релізів і робіть контрольні відновлення з бекапів, щоб бути впевненими в їх працездатності.