Документация / Деплой
Деплой проекта: от репозитория до своего домена
Подключаете репозиторий — платформа собирает Docker-образ, запускает контейнер и даёт адрес имя.relaxdev.ru с HTTPS. Каждый push в ветку выкатывает новую версию сам.
Ниже по шагам: первый деплой, что поправить в коде, переменные, откат, логи, частые ошибки и домен.
Как это работает
- 1
Push в ветку проекта
Git-провайдер присылает вебхук — его платформа добавляет в репозиторий сама при создании проекта. - 2
Сборка на раннере
Каждая сборка идёт в отдельном контейнере. Одновременно — до 5 сборок, сборки одного проекта — по очереди. - 3
Docker-образ
Платформа генерирует Dockerfile по стеку или берёт ваш, если тип сборки — Docker. - 4
Запуск контейнера
Новая версия получает трафик на порт 8080, адрес и сертификат остаются прежними.
Первый деплой по шагам
- 1
Подключите Git-аккаунт
В профиле: GitHub, GitLab, GitFlic или Gitverse. Приватные репозитории поддерживаются. - 2
Нажмите «Добавить проект» и выберите репозиторий
Ветка по умолчанию — main или master, её можно сменить в настройках в любой момент. - 3
Укажите папку, если это монорепо
Выберите подпапку в окне выбора папок, напримерapps/web. Остальной репозиторий в сборку не попадёт. - 4
Оставьте «Автоопределение стека»
Платформа сама поймёт по файлам репозитория, как собрать приложение. Свой Dockerfile — тип сборки «Docker». - 5
Добавьте переменные
Вставьте содержимое.envцеликом во вкладку «Переменные» — ключи и значения разберутся сами. Базу данных можно подключить позже, по шагам. - 6
Нажмите «Деплой»
Через пару минут проект откроется по адресуимя-проекта.relaxdev.ruс HTTPS. Ход сборки виден в логе.
Подготовка приложения
Главное правило — порт 8080 из переменной PORT и адрес 0.0.0.0. Трафик приходит в контейнер только на 8080. Платформа передаёт его в PORT, а рантаймам, которые PORT не читают, — в SERVER_PORT, UVICORN_PORT, FLASK_RUN_PORT, SANIC_PORT. Слушаете другой порт или localhost — домен вернёт 502.
Next.js
next start сам читает PORT — менять ничего не нужно.
{
"scripts": {
"build": "next build",
"start": "next start"
}
}Node.js — Express, Fastify, NestJS
import express from "express";
const app = express();
app.get("/health", (req, res) => res.send("ok"));
const port = Number(process.env.PORT) || 8080;
app.listen(port, "0.0.0.0", () => console.log(`listening on ${port}`));Python — FastAPI, Flask, Django
# main.py — FastAPI
import os
import uvicorn
from fastapi import FastAPI
app = FastAPI()
@app.get("/health")
def health():
return {"ok": True}
if __name__ == "__main__":
uvicorn.run(app, host="0.0.0.0", port=int(os.environ.get("PORT", "8080")))Go
port := os.Getenv("PORT")
if port == "" {
port = "8080"
}
log.Fatal(http.ListenAndServe(":"+port, mux))Приложение — один постоянный процесс
Это не serverless: соединения с базой, кэш в памяти и фоновые таймеры живут, пока работает контейнер. Настройки под Vercel вроде max: 1 в пуле базы не нужны.
Сборщики и стеки
Тип сборки определяется при создании проекта по файлам репозитория. Поменять его можно в настройках — изменение применится на следующем деплое.
| Стек | Как собирается |
|---|---|
| Next.js, Nuxt, TanStack Start | SSR-приложение: сборка и запуск Node-сервера |
| Vite, React, Angular | Фронтенд: сборка через npm run build |
| Node.js, NestJS, Express | По package.json: команды build и start |
| Python | FastAPI, Flask, Django, aiohttp — по requirements.txt или pyproject.toml |
| Go | По go.mod: статический бинарник в маленьком образе |
| PHP, Laravel | По composer.json, корень сайта — папка public |
| Java | Maven или Gradle: по pom.xml или build.gradle |
| HTML | Статический сайт без сборки |
| Telegram Bot | Свой сборщик: сеть до api.telegram.org подключается сама |
| Docker | Ваш Dockerfile — для всего остального |
Если в проекте есть Prisma, при сборке выполняется prisma generate. Нужна база уже на этапе сборки (статические страницы из базы, prisma db push) — включите «Сборку с доступом к БД».
Свой Dockerfile
Dockerfile из репозитория применяется, только когда тип сборки — Docker. На время установки зависимостей платформа ставит NODE_ENV=development, чтобы поставились devDependencies. Делайте multi-stage сборку и задавайте NODE_ENV=production в финальной стадии — иначе приложение останется в режиме разработки.
# Сборка
FROM node:22-alpine AS build
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build
# Запуск
FROM node:22-alpine
WORKDIR /app
ENV NODE_ENV=production
ENV PORT=8080
COPY --from=build /app/package*.json ./
RUN npm ci --omit=dev
COPY --from=build /app/dist ./dist
EXPOSE 8080
CMD ["node", "dist/server.js"]# Python
FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
EXPOSE 8080
CMD ["sh", "-c", "uvicorn main:app --host 0.0.0.0 --port ${PORT:-8080}"]Переменные окружения
- 1
Откройте вкладку «Переменные» проекта
Добавляйте по одной или вставьте .env целиком — можно и загрузить сам файл. Кавычки снимаются, совпадающие ключи обновляются. - 2
Сохраните и нажмите «Редеплой»
Серверным переменным хватит перезапуска.NEXT_PUBLIC_*вшиваются в код браузера при сборке — для них нажмите «Пересобрать».
# Вставляется во вкладку «Переменные» целиком
API_URL=https://api.example.com
TELEGRAM_BOT_TOKEN="123456:ABC..."
NEXT_PUBLIC_SITE_NAME=Мой магазинПереезд с Vercel
npx vercel link
npx vercel env pull .env.vercel --environment=production
# содержимое .env.vercel вставьте во вкладку «Переменные»Служебные VERCEL_* и TURBO_* пропускаются. Значения с пометкой Sensitive Vercel не выгружает — их нужно вписать вручную.
Заглушки при сборке
Платформа находит в исходниках обращения вида process.env.ИМЯ и подставляет переменным, которых нет в проекте, строку auto-generated-stub-for-build — так проект соберётся в любом случае. Но заглушка остаётся и в работающем приложении: значение по умолчанию через || не сработает, а числа станут NaN. Не подменяются только NODE_ENV и PORT.
- Какие переменные получили заглушку, видно в начале лога сборки и в баннере «Переменные без значения» на странице проекта.
- Нужен фолбэк — читайте через квадратные скобки:
process.env['API_URL'] || 'дефолт'. Такую запись платформа не трогает. ДляNEXT_PUBLIC_*это не подходит: Next.js вшивает в браузер только запись через точку.
Служебные переменные
| Переменная | Зачем |
|---|---|
PORT | Ставит платформа: 8080. Читайте порт из неё. |
TG_OPTION=1 | Сеть с IPv6 для веб-проекта, который сам ходит в api.telegram.org. Боту типа «Telegram Bot» не нужна. |
WEB_PORT | Открывает наружу HTTP Telegram-бота (вебхук, мини-приложение). Значение — порт, который слушает бот. |
RELAXDEV_PROXY_URL | Исходящие запросы через прокси платформы — когда внешний API обрывает передачу с наших адресов. Адрес — «Переменные» → «Webhook / Proxy». |
Подробнее о прокси и вебхуках — в документации.
Автодеплой по push
- Push в ветку проекта — сборка и выкат новой версии. В истории деплоев видно автора и коммит.
- Push в другую ветку — превью-окружение на отдельном адресе, если превью включены в настройках проекта.
- Автодеплой выключен — новая версия выкатывается кнопкой «Редеплой».
Push есть, а сборки нет
- 1
Проверьте ветку
Push должен быть в ветку, выбранную в проекте, а автодеплой — включён. - 2
Проверьте вебхук в репозитории
В настройках репозитория, раздел вебхуков: адресhttps://relaxdev.ru/api/webhook/github(у других провайдеров в концеgitlab,gitverseилиgitflic), последние доставки без ошибок. - 3
Обновите подключение Git
Нет вебхука — у аккаунта не хватило прав на настройки репозитория или истёк токен. Переподключите Git в профиле или напишите в поддержку.
Деплой из GitLab, GitFlic и Gitverse работает так же. Репозиторий можно перенести на GitFlic или Gitverse из настроек проекта и переключить источник деплоя — подробнее.
Редеплой, пересборка и откат
| Действие | Что происходит | Когда нужно |
|---|---|---|
| Редеплой | Есть новые коммиты — сборка заново; нет — перезапуск текущей сборки с новыми переменными | После изменения переменных или подключения базы |
| Пересобрать | Полная сборка из ветки | Изменились NEXT_PUBLIC_*, сменился тип сборки |
| Коммит или ветка | Стрелка рядом с «Редеплой»: вставьте SHA, ссылку на коммит или имя ветки | Выкатить конкретную версию |
| Без кэша Docker | Галочка в той же панели: все слои пересобираются | Зависимости обновились, а слои остались старыми |
| Откатить | В истории деплоев: тот же образ запускается без сборки, за секунды | Новая версия сломалась |
| Перезапустить без сборки | Кнопка рядом с «Редеплой»; там же — остановить и запустить | Приложение зависло |
Логи и частые ошибки
- Лог сборки — в истории деплоев. После неудачной сборки в панели появляется подсказка: что сломалось и как исправить. Частые ошибки распознаются сразу, редкие разбирает нейросеть — до минуты.
- Логи приложения — всё, что приложение пишет в stdout и stderr; на платформе хранятся 7 дней.
- Мониторинг — графики CPU, памяти и сети. Если приложение исчерпает память, контейнер перезапустится сам.
| Симптом | Причина и решение |
|---|---|
| 502 Bad Gateway | Приложение слушает не 8080 или localhost. Читайте PORT, слушайте 0.0.0.0. |
| Can't reach database server при сборке | Страницы строятся из базы на этапе сборки — включите «Сборку с доступом к БД». |
| Ошибки TypeScript в логе | Сборка проверяет типы, как next build у вас. Исправьте ошибки или проверьте локально командой npx tsc --noEmit. |
| COPY failed: file not found | В Dockerfile путь не совпадает с папкой проекта. Проверьте выбранную папку (rootDir) и пути в COPY. |
Значение auto-generated-stub-for-build, NaN | Переменной нет в проекте — добавьте её во вкладке «Переменные». |
| Telegram-бот: адрес проекта отдаёт 404 | Бот работает на long polling. Чтобы открыть HTTP наружу, задайте WEB_PORT. |
| Внешний API обрывается по таймауту | Пустите запросы через прокси: RELAXDEV_PROXY_URL. |
Превью веток
- 1
Откройте вкладку «Окружения»
Выберите ветку и нажмите «Создать». - 2
Откройте адрес превью
Через 1–3 минуты —проект-git-ветка.preview.relaxdev.ru, закрыт от поисковиков. Продакшн работает на прежнем образе. - 3
Выберите базу превью
По умолчанию — та же, что у продакшна. Для веток с миграциями выберите «Только схема»: отдельная база со структурой продакшна без данных.
Превью живёт 72 часа, отсчёт обновляется при каждой пересборке. До 5 превью на проект. Подробно о переменных превью и слиянии веток — в документации.
Свой домен
- 1
Пропишите записи у регистратора
A-записи@иwww— на IP из вкладки «Домены» проекта (дляwwwможно CNAME на основной домен). Других A и AAAA у имени быть не должно. В Cloudflare — режим «DNS only». - 2
Проверьте DNS
На dnschecker.org у A во всех регионах должен быть только этот адрес. У проекта на своей VM или своём сервере он свой — его тоже покажет вкладка «Домены». - 3
Добавьте домен во вкладке «Домены»
Панель сама проверит DNS и не добавит домен, пока записи не на нас. - 4
Дождитесь сертификата
Let’s Encrypt выпускается автоматически, обычно за минуту, и продлевается сам.
Там же — выбор главного имени (с www или без), перенаправление доменов, поддомены, wildcard и кириллические домены: подробнее о доменах.
Деплой с ИИ-агентом и MCP
Подготовить репозиторий
Дайте агенту (Claude Code, Cursor, Codex) ссылку на инструкцию — он поправит порт, Dockerfile и код под переменные:
Подготовь проект к деплою на RelaxDev по инструкции
https://relaxdev.ru/.well-known/skills/relaxdev-deploy/SKILL.md
и перечисли, что мне нужно настроить в панели.Деплоить и читать логи через MCP
Коннектор https://relaxnet.pro/api/mcp подключается в Claude, Claude Code и Codex. Аккаунт и проекты — те же, что на relaxdev.ru. Ассистент запускает деплой, ждёт результат, читает логи сборки и приложения, меняет переменные и настройки сборки, работает с базами.
claude mcp add --transport http relaxnet https://relaxnet.pro/api/mcp
codex mcp add relaxnet --url https://relaxnet.pro/api/mcp && codex mcp login relaxnetЗадеплой проект shop и дождись результата. Если сборка упадёт — разбери лог и предложи исправление.
Покажи последние 200 строк логов проекта shop с ошибками.
Добавь проекту shop переменную API_URL=https://api.example.com и перезапусти его.Подробно — базы через MCP и Claude и MCP: подключение по шагам.
Частые вопросы
Сколько длится сборка?+
Обычно 1–5 минут: зависит от размера зависимостей и стека. Повторные сборки быстрее — слои Docker берутся из кэша. Если раннеры заняты, сборка ждёт в очереди и стартует, как только освободится место.
Домен отдаёт 502 Bad Gateway+
Приложение не слушает порт 8080. Читайте порт из переменной PORT и слушайте 0.0.0.0, а не localhost. Результат проверки порта сборщик пишет в лог сборки.
Поменял переменную, а приложение видит старое значение+
Нажмите «Редеплой». Серверные переменные подхватятся при перезапуске, а NEXT_PUBLIC_* вшиваются в код браузера при сборке — для них нужно «Пересобрать».
Правки в Dockerfile не применяются+
Dockerfile из репозитория используется, только когда тип сборки — Docker. При любом другом типе платформа генерирует Dockerfile сама. Проверьте тип сборки в настройках проекта.
Как откатиться на прошлую версию?+
В истории деплоев нажмите «Откатить» у нужной успешной сборки. Платформа запустит тот же образ без пересборки — это занимает секунды.
Можно деплоить без GitHub?+
Да. GitRelax — свой Git платформы: вкладка «GitRelax» в новом проекте создаёт репозиторий на git.relaxdev.ru, и каждый git push собирается сам (подробно — /docs/git). GitLab, GitFlic и Gitverse тоже работают с автодеплоем по push. Статический сайт можно загрузить как HTML-проект, а Telegram-бота — собрать в Bot Lab без репозитория.
Push есть, а сборка не запустилась+
Проверьте, что push был в ветку проекта и автодеплой включён. В настройках репозитория должен быть вебхук https://relaxdev.ru/api/webhook/github (или gitlab, gitverse, gitflic) без ошибок доставки. Нет вебхука — обновите подключение Git в профиле.