Документация / Деплой

Деплой проекта: от репозитория до своего домена

Подключаете репозиторий — платформа собирает Docker-образ, запускает контейнер и даёт адрес имя.relaxdev.ru с HTTPS. Каждый push в ветку выкатывает новую версию сам.

Ниже по шагам: первый деплой, что поправить в коде, переменные, откат, логи, частые ошибки и домен.

Как это работает

  1. 1

    Push в ветку проекта

    Git-провайдер присылает вебхук — его платформа добавляет в репозиторий сама при создании проекта.
  2. 2

    Сборка на раннере

    Каждая сборка идёт в отдельном контейнере. Одновременно — до 5 сборок, сборки одного проекта — по очереди.
  3. 3

    Docker-образ

    Платформа генерирует Dockerfile по стеку или берёт ваш, если тип сборки — Docker.
  4. 4

    Запуск контейнера

    Новая версия получает трафик на порт 8080, адрес и сертификат остаются прежними.

Первый деплой по шагам

  1. 1

    Подключите Git-аккаунт

    В профиле: GitHub, GitLab, GitFlic или Gitverse. Приватные репозитории поддерживаются.
  2. 2

    Нажмите «Добавить проект» и выберите репозиторий

    Ветка по умолчанию — main или master, её можно сменить в настройках в любой момент.
  3. 3

    Укажите папку, если это монорепо

    Выберите подпапку в окне выбора папок, например apps/web. Остальной репозиторий в сборку не попадёт.
  4. 4

    Оставьте «Автоопределение стека»

    Платформа сама поймёт по файлам репозитория, как собрать приложение. Свой Dockerfile — тип сборки «Docker».
  5. 5

    Добавьте переменные

    Вставьте содержимое .env целиком во вкладку «Переменные» — ключи и значения разберутся сами. Базу данных можно подключить позже, по шагам.
  6. 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 — менять ничего не нужно.

package.json
{
  "scripts": {
    "build": "next build",
    "start": "next start"
  }
}

Node.js — Express, Fastify, NestJS

javascript
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

python
# 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

go
port := os.Getenv("PORT")
if port == "" {
    port = "8080"
}
log.Fatal(http.ListenAndServe(":"+port, mux))

Приложение — один постоянный процесс

Это не serverless: соединения с базой, кэш в памяти и фоновые таймеры живут, пока работает контейнер. Настройки под Vercel вроде max: 1 в пуле базы не нужны.

Сборщики и стеки

Тип сборки определяется при создании проекта по файлам репозитория. Поменять его можно в настройках — изменение применится на следующем деплое.

СтекКак собирается
Next.js, Nuxt, TanStack StartSSR-приложение: сборка и запуск Node-сервера
Vite, React, AngularФронтенд: сборка через npm run build
Node.js, NestJS, ExpressПо package.json: команды build и start
PythonFastAPI, Flask, Django, aiohttp — по requirements.txt или pyproject.toml
GoПо go.mod: статический бинарник в маленьком образе
PHP, LaravelПо composer.json, корень сайта — папка public
JavaMaven или 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 в финальной стадии — иначе приложение останется в режиме разработки.

dockerfile
# Сборка
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"]
dockerfile
# 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. 1

    Откройте вкладку «Переменные» проекта

    Добавляйте по одной или вставьте .env целиком — можно и загрузить сам файл. Кавычки снимаются, совпадающие ключи обновляются.
  2. 2

    Сохраните и нажмите «Редеплой»

    Серверным переменным хватит перезапуска. NEXT_PUBLIC_* вшиваются в код браузера при сборке — для них нажмите «Пересобрать».
.env
# Вставляется во вкладку «Переменные» целиком
API_URL=https://api.example.com
TELEGRAM_BOT_TOKEN="123456:ABC..."
NEXT_PUBLIC_SITE_NAME=Мой магазин

Переезд с Vercel

bash
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. 1

    Проверьте ветку

    Push должен быть в ветку, выбранную в проекте, а автодеплой — включён.
  2. 2

    Проверьте вебхук в репозитории

    В настройках репозитория, раздел вебхуков: адрес https://relaxdev.ru/api/webhook/github (у других провайдеров в конце gitlab, gitverse или gitflic), последние доставки без ошибок.
  3. 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. 1

    Откройте вкладку «Окружения»

    Выберите ветку и нажмите «Создать».
  2. 2

    Откройте адрес превью

    Через 1–3 минуты — проект-git-ветка.preview.relaxdev.ru, закрыт от поисковиков. Продакшн работает на прежнем образе.
  3. 3

    Выберите базу превью

    По умолчанию — та же, что у продакшна. Для веток с миграциями выберите «Только схема»: отдельная база со структурой продакшна без данных.

Превью живёт 72 часа, отсчёт обновляется при каждой пересборке. До 5 превью на проект. Подробно о переменных превью и слиянии веток — в документации.

Свой домен

  1. 1

    Пропишите записи у регистратора

    A-записи @ и www — на IP из вкладки «Домены» проекта (для www можно CNAME на основной домен). Других A и AAAA у имени быть не должно. В Cloudflare — режим «DNS only».
  2. 2

    Проверьте DNS

    На dnschecker.org у A во всех регионах должен быть только этот адрес. У проекта на своей VM или своём сервере он свой — его тоже покажет вкладка «Домены».
  3. 3

    Добавьте домен во вкладке «Домены»

    Панель сама проверит DNS и не добавит домен, пока записи не на нас.
  4. 4

    Дождитесь сертификата

    Let’s Encrypt выпускается автоматически, обычно за минуту, и продлевается сам.

Там же — выбор главного имени (с www или без), перенаправление доменов, поддомены, wildcard и кириллические домены: подробнее о доменах.

Деплой с ИИ-агентом и MCP

Подготовить репозиторий

Дайте агенту (Claude Code, Cursor, Codex) ссылку на инструкцию — он поправит порт, Dockerfile и код под переменные:

text
Подготовь проект к деплою на RelaxDev по инструкции
https://relaxdev.ru/.well-known/skills/relaxdev-deploy/SKILL.md
и перечисли, что мне нужно настроить в панели.

Деплоить и читать логи через MCP

Коннектор https://relaxnet.pro/api/mcp подключается в Claude, Claude Code и Codex. Аккаунт и проекты — те же, что на relaxdev.ru. Ассистент запускает деплой, ждёт результат, читает логи сборки и приложения, меняет переменные и настройки сборки, работает с базами.

bash
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
text
Задеплой проект 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 в профиле.