Як розгорнути Supabase на VPS через Docker
Запустіть офіційний Supabase Docker stack на власному сервері: замініть демонстраційні секрети, розберіться з 11 сервісами, RAM, backup і оновленнями.
Що ви розгортаєте
Self-hosting Supabase означає запуск офіційного Docker Compose stack на власному сервері: Postgres, REST API перед ним, сервіс автентифікації, файлове сховище, realtime websockets і панель Studio. Ви клонуєте один репозиторій, редагуєте один файл .env і запускаєте 11 контейнерів, які разом працюють як керований вами проєкт Supabase.
Встановлення займає небагато часу. Проблеми зазвичай спричиняє файл .env. Він містить демонстраційні секрети, опубліковані в репозиторії, а stack, запущений із цими значеннями за замовчуванням, доступний будь-кому, хто їх знайде. У цьому посібнику описано секрети, які потрібно замінити, призначення кожного сервісу, обсяг пам’яті, якого stack потребує на практиці, а також оновлення без видалення бази даних.
Якщо Compose для вас новий, спочатку прочитайте Основи Docker Compose на VPS. Усе нижче передбачає, що docker compose version уже виводить версію.
Що насправді входить до stack
Supabase — це не одна програма. Файл Compose запускає набір окремих сервісів в одній мережі. Розуміння ролі кожного сервісу допомагає налагоджувати stack замість того, щоб бачити лише довгий список назв контейнерів.
db— це PostgreSQL із завантаженими розширеннями Supabase. Усі інші сервіси взаємодіють із ним. Якщо цей контейнер працює некоректно, інші сервіси також не працюватимуть.api-gw— це API gateway. Починаючи з релізу August 2026, він працює на Envoy. До цього використовувався сервіс під назвоюkong, а Kong і надалі доступний як необов’язкове перевизначення. Сервіс слухає порт 8000 і спрямовує/rest/v1/,/auth/v1/та/storage/v1/до відповідних бекендів. Це єдиний контейнер, який слід відкривати назовні.rest— це PostgREST. Він читає схему Postgres і надає її як REST API. Тому нова таблиця автоматично стає новою кінцевою точкою без написання коду.auth— це GoTrue. Він видає JSON web tokens (JWT), які ідентифікують ваших користувачів.storageіimgproxyобробляють завантаження файлів і змінюють розмір зображень.realtimeпередає зміни бази даних через websockets.studioіmeta— це dashboard і admin API, який він використовує.functions— це edge runtime на основі Deno, аsupavisor— пулер підключень до Postgres.
Logs і analytics (Logflare та vector) вилучили з типового файла Compose у June 2026. Тепер це доступні за вибором override-файли, які вмикаються за допомогою sh run.sh config add logs. Вони використовують той самий принцип накладання Compose-файлів, що й описаний у розділі запуск одного stack із кількох Compose-файлів.
Саме тому наведені нижче показники використання ресурсів мають такі значення. Ви запускаєте не лише базу даних. Ви запускаєте базу даних і ще десять допоміжних сервісів.
Плануйте 8 GB RAM
У липні 2026 року після чистого встановлення стек споживав приблизно 2.5–3 GB resident memory без ваших даних і мережевого трафіку. У цьому вимірюванні analytics service і процес Studio Node.js були двома найбільшими окремими споживачами ресурсів. Analytics більше не входить до складу стеку за замовчуванням, тому він споживає пам’ять лише після ввімкнення logs override. Сервер із 2 GB RAM запустить контейнери, а потім kernel out of memory killer завершить один із них. Ознакою цього є контейнер, який постійно перезапускається з exit code 137. Власна документація Supabase для self-hosting, перевірена в жовтні 2026 року, вказує 4 GB RAM, 2 CPU cores і 40 GB SSD як мінімальні вимоги, а 8 GB, 4 cores і 80 GB — як рекомендовані.
Для всього, від чого ви залежите, виділіть 8 GB RAM і 4 vCPU. 4 GB достатньо для одиночного середовища розробки, якщо ви погоджуєтеся з тим, що одночасно важкий запит і сесія Studio працюватимуть повільно. Диск також має значення, оскільки Postgres, storage volume і, якщо ви ввімкнете logs, дані журналів зберігаються в каталозі проєкту. Почніть із 40 GB і стежте за використанням. Підраховувати кількість сервісів до вибору тарифу — корисна звичка для будь-яких self-hosted систем, оскільки PhotoPrism та Immich також мають реальні мінімальні вимоги до RAM: сторінка швидкого запуску Immich, перевірена в жовтні 2026 року, вимагає щонайменше 6 GB RAM і 2 CPU cores. Якщо наразі це більше сервера, ніж потрібно вашому проєкту, порівняйте цей варіант із тим, що насправді входить до безкоштовного cloud plan Supabase, оскільки невеликий застосунок, який споживає менше 500 MB і не простоює протягом тижня, може працювати там безкоштовно.
Встановлення: клонуйте офіційний репозиторій
Підтримуваний спосіб передбачає копіювання каталогу docker з основного репозиторію до власного каталогу проєкту. Такий поділ важливий, оскільки під час подальшого виконання git pull ваш .env не буде перезаписано.
git clone --depth 1 https://github.com/supabase/supabase
mkdir supabase-project
cp -rf supabase/docker/* supabase-project
cp supabase/docker/.env.example supabase-project/.env
cd supabase-project
docker compose pulldocker compose pull завантажує кілька гігабайтів образів. Виконання має завершитися зі статусом Pulled для кожного сервісу. Помилка manifest unknown означає, що закріплений тег образу видалили у вихідному репозиторії. Щоб виправити це, завантажте новішу копію репозиторію, а не редагуйте теги вручну.
Секрети, які потрібно змінити перед першим запуском
Зробіть це до запуску stack, а не після нього. Деякі з цих значень записуються в дані під час першого запуску, тому подальша їхня зміна потребує скидання бази даних.
У репозиторії є генератор, який правильно створює всі значення, зокрема два API keys, які потрібно підписати новим JWT secret.
sh utils/generate-keys.sh --update-envЦей скрипт записує нові значення для JWT_SECRET, ANON_KEY, SERVICE_ROLE_KEY, SECRET_KEY_BASE, REALTIME_DB_ENC_KEY, VAULT_ENC_KEY, PG_META_CRYPTO_KEY, токенів Logflare, ключів протоколу S3 і MINIO_ROOT_PASSWORD у .env. Станом на October 2026 він також записує випадкові значення для POSTGRES_PASSWORD і DASHBOARD_PASSWORD. Для роботи йому потрібен openssl, який є в будь-якому стандартному образі Ubuntu. Оскільки тепер скрипт також змінює пароль бази даних, запускайте його з --update-env лише до першого запуску. Ніколи не запускайте його для stack, у якому вже є дані.
Два значення в .env все одно варто перевірити вручну:
POSTGRES_PASSWORD. Скрипт заповнює його випадковим hex-значенням, що безпечно. Якщо замінюєте його власним значенням, використовуйте лише літери й цифри. Пунктуація тут ламає рядки підключення, які кілька сервісів формують об’єднанням рядків. У результаті виникає помилка автентифікації, а не помилка синтаксичного аналізу, тому пошук проблеми часто ведеться не там.DASHBOARD_USERNAMEіDASHBOARD_PASSWORD. Це облікові дані базової автентифікації для Studio. Скрипт встановлює випадковий пароль, але залишає ім’я користувача за замовчуванням:supabase. Стандартний пароль буквально дорівнюєthis_password_is_insecure_and_should_be_updated. Якщо ви пропустили запуск скрипту, змініть його зараз.
Потрібно розуміти, чому ANON_KEY і SERVICE_ROLE_KEY не можна вигадувати. Обидва значення є JWT, підписаними за допомогою JWT_SECRET. Gateway приймає лише точні ключі з .env, а сервіси за ним перевіряють підпис за допомогою JWT_SECRET. Тому невідповідний ключ відхиляється з HTTP 401. Стандартний Envoy gateway повертає 401 Unauthorized. Поточне перевизначення Kong також повертає {"message":"Unauthorized"}; воно використовує Kong 3.9. Інсталяції, створені до March 2026, використовували Kong 2.8, який повертає {"message":"Invalid authentication credentials"}. Це найпоширеніша помилка під час self-hosting: оператор змінює JWT_SECRET, але залишає демонстраційні ключі. Завжди генеруйте всі три значення разом.
Ставтеся до SERVICE_ROLE_KEY як до root password. Він повністю обходить row level security. Цей секрет має зберігатися в server side code і більше ніде.
Встановіть SITE_URL як адресу вашого застосунку, а API_EXTERNAL_URL — як публічну адресу API із /auth/v1 в кінці, наприклад https://supabase.example.com/auth/v1. Встановіть SUPABASE_PUBLIC_URL як ту саму публічну адресу без шляху. Auth формує посилання для підтвердження email і OAuth callback на основі цих значень. Якщо залишити їхні стандартні значення localhost, усі ваші користувачі переходять на власний комп’ютер.
Після цього перевірте налаштовані значення:
sh run.sh secretsЗапустіть його та переконайтеся, що він працює належним чином
sh run.sh start
docker compose psrun.sh start обгортає docker compose up -d --wait, тому команда не повертає керування, доки не пройдуть перевірки стану. Для кожного сервісу має відображатися running (healthy) або running. Перший запуск триває від двох до чотирьох хвилин, оскільки Postgres спочатку виконує скрипти ініціалізації, і лише після цього до нього можуть підключатися інші компоненти.
Якщо контейнер перезапускається, перегляньте його журнали за назвою сервісу:
docker compose logs db
docker compose logs authStudio буде доступний на порту 8000 і запросить ім’я користувача та пароль для dashboard, які ви вказали.
Не виставляйте порт 8000 у публічний інтернет
Gateway на 8000 використовує звичайний HTTP. Кожен API key і кожен пароль користувача передається мережею у відкритому вигляді, а облікові дані Studio використовують basic authentication, тобто кодування base64, а не шифрування.
Розмістіть reverse proxy перед ним і завершуйте TLS (transport layer security) на проксі. Прив’яжіть gateway до loopback-адреси, щоб жоден інший вузол не міг отримати до нього доступ. У docker-compose.yml рядок порту під сервісом api-gw потрібно замінити на 127.0.0.1:${API_GW_HTTP_PORT:-${KONG_HTTP_PORT:-8000}}:8000/tcp, після чого проксі пересилатиме запити на цей порт. В інсталяціях, виконаних до переходу на Envoy у August 2026, такий самий рядок порту розташований під сервісом із назвою kong. Опис налаштування сертифікатів наведено в Traefik перед кількома Compose-застосунками. Цей самий проксі зрештою обслуговує все інше на сервері — від цього stack до чогось настільки несерйозного, як бібліотека Jellyfin, перебудована під відеомагазин 90-х, — і кожному з них потрібне ім’я хоста, а не ще один відкритий порт. Якщо dashboard призначений лише для вас, не використовуйте проксі. Натомість підключайтеся до loopback-порту через SSH tunnel — так само, як це робить self-hosted open-kritt, щоб повністю залишити свій інтерфейс сканування поза публічним інтернетом.
Також закрийте решту портів у firewall, оскільки Docker публікує порти, створюючи власні правила iptables, яких стандартна конфігурація ufw не бачить. Цю проблему пояснено в матеріалі чому Docker-контейнери ігнорують правила ufw.
Робіть резервну копію бази даних, а не каталогу
Дані Postgres зберігаються в bind mount за адресою ./volumes/db/data. Копіювання цього каталогу під час роботи контейнера створює неповну копію, оскільки Postgres буферизує операції запису, а файли на диску узгоджені лише під час checkpoint. Відновлення зазвичай працює, але іноді непомітно втрачає останні транзакції. Це найгірший можливий варіант відмови для резервної копії.
Замість цього створюйте dump. pg_dumpall запускається всередині контейнера та створює узгоджений знімок:
docker exec -t supabase-db pg_dumpall -U postgres > supabase-$(date +%F).sqlПерш ніж покладатися на файл, переконайтеся, що він не порожній. Потім регулярно передавайте ці dump-файли на інший сервер. Саме для цього призначені зашифровані резервні копії на віддаленому майданчику за допомогою restic. Запланований dump, який непомітно завершується з помилкою, нічим не відрізняється від повної відсутності резервної копії. Тому налаштуйте cron або systemd job так, щоб після завершення з ненульовим кодом він надсилав сповіщення на телефон. Одночасно створюйте резервну копію .env. Втрата JWT_SECRET зробить недійсним кожен виданий token, а кожен збережений зашифрований секрет стане недоступним для читання.
Завантажені файли зберігаються в ./volumes/storage. Це звичайні файли, тому для них достатньо звичайного копіювання.
Оновлення без втрати даних
Supabase фіксує версії образів у docker-compose.yml, тому нічого не змінюється, доки ви самі не внесете зміни. Фіксувати версії варто в будь-якому стеку, який ви збираєте вручну. Саме тому self-hosted relay RustDesk фіксує версії двох серверних образів, а не використовує змінний тег: оновлення має виконуватися тоді, коли ви самі його запланували й маєте на це час. Щоразу спочатку створюйте dump.
docker compose pull
sh run.sh recreaterecreate зупиняє стек і запускає його знову з новими образами. Дані зберігаються, оскільки вони розміщені в bind mounts на хості, а не всередині контейнерів. Перед переходом на нову major-версію прочитайте CHANGELOG.md у репозиторії, оскільки оновлення major-версії Postgres є окремим кроком, якого recreate не виконує. Починаючи з June 2026, типовою є Postgres 17. Наявну інсталяцію на Postgres 15 можна перенести на неї за допомогою sudo bash utils/upgrade-pg17.sh. Ця команда використовує pg_upgrade для міграції даних на місці та запитує підтвердження на кожному major-кроці. Усі контейнери мають працювати, а вільного місця на диску має бути щонайменше вдвічі більше за розмір вашої бази даних плюс 5 GB. Supabase і надалі рекомендує створити окрему резервну копію перед початком.
Щоб застосувати зміни безпосередньо до Compose-файлу, виконайте sh update.sh з каталогу проєкту або спочатку виконайте sh update.sh --dry-run, щоб переглянути заплановані зміни. Команда об’єднує upstream-файли з вашими змінами й не перезаписує наявні значення у .env (лише додає нові ключі). Перед записом вона зберігає архів конфігурації в backups/, але не базу даних. Для інсталяції без файлу .supabase-version потрібні --from і release, з якого її було запущено. Це особливо важливо для release August 2026, у якому сервіс kong замінено на api-gw і потрібно оновити docker-compose.yml. Ручний спосіб також працює: знову клонуйте upstream-репозиторій і скопіюйте його каталог docker у свій проєкт, не перезаписавши .env.
Повне скидання, яке видаляє все, включно з базою даних, і повертає .env до типових значень (попередню версію збережено як .env.old), виконується окремим скриптом і потребує підтвердження:
sh reset.shFAQ
Чому мої API-запити повертають повідомлення "Invalid authentication credentials"?
Це точне повідомлення надходить від Kong 2.8 — шлюзу у стеку в інсталяціях, виконаних до березня 2026 року. Стандартний шлюз Envoy і поточне перевизначення Kong, у якому працює Kong 3.9, повідомляють про ту саму проблему як звичайний 401 Unauthorized. У будь-якому разі надісланий вами ключ не відповідає ANON_KEY або SERVICE_ROLE_KEY у .env, або ці ключі не були підписані за допомогою JWT_SECRET, який зараз міститься в .env. Якщо стек ще не містить даних, повторно згенеруйте всі три значення разом за допомогою sh utils/generate-keys.sh --update-env. Якщо стек уже працює, запустіть скрипт без цього прапорця та відповідайте no, щоб він лише вивів нові значення. Вручну скопіюйте JWT_SECRET, ANON_KEY і SERVICE_ROLE_KEY у .env, а POSTGRES_PASSWORD залиште без змін. Потім виконайте sh run.sh recreate, щоб сервіси прочитали нові значення.
Чи можна запускати self-hosted Supabase на VPS із 2 GB оперативної пам’яті?
Ненадійно. Станом на жовтень 2026 року у власній документації Supabase для self-hosting мінімальним обсягом вказано 4 GB RAM. Станом на липень 2026 року стек у режимі простою використовував майже 3 GB у вимірюванні, яке включало сервіси журналювання, що тепер підключаються лише за вибором. На сервері з 2 GB OOM killer завершує роботу контейнерів, і в docker compose ps з’являється код завершення 137. Для production використовуйте 8 GB, а 4 GB вважайте мінімумом для індивідуальної розробки.
Чи містить self-hosted Supabase edge functions?
Так. Compose-файл містить runtime для функцій на основі Deno і обслуговує все, що ви розмістите в ./volumes/functions. До нього не входить глобальна мережа розгортання hosted-платформи, тому ваші функції працюють на одному сервері та в одному розташуванні.
Як підключитися безпосередньо до бази даних Postgres?
Для інтерактивної оболонки безпосередньо на сервері використовуйте docker exec -it supabase-db psql -U postgres. Для зовнішнього клієнта підключайтеся через Supavisor на порту 5432 з користувачем postgres.<POOLER_TENANT_ID> і вашим POSTGRES_PASSWORD. Не відкривайте цей порт для інтернету. Підключайтеся до нього через VPN або SSH-тунель.
Чому посилання в моїх листах із підтвердженням auth ведуть на localhost?
У .env залишилися стандартні значення SITE_URL і API_EXTERNAL_URL. Сервіс auth формує кожне посилання для підтвердження та скидання пароля на основі цих двох значень, тому він надсилає адресу, яку йому вказано. Установіть для обох параметрів фактичну публічну URL-адресу та повторно створіть стек.