Что нужно, чтобы деплой через Nixpacks прошёл
Nixpacks — сборщик, который сам определяет стек вашего проекта по файлам в репозитории, устанавливает зависимости и собирает контейнер. Dockerfile при этом не нужен. Это способ сборки по умолчанию.
«Работает локально» и «соберётся на платформе» — не одно и то же. Сборка идёт в чистом окружении, где есть только то, что вы закоммитили в git и объявили в манифесте зависимостей. Ничего из вашей локальной машины туда не попадает: ни глобально установленные пакеты, ни файлы вне репозитория, ни локальный .env.
Ниже — требования, которые нужно выполнить. Детали под конкретный язык — в статьях по стеку в конце.
1. Объявите зависимости в манифесте
Nixpacks определяет стек и ставит зависимости по файлу-манифесту в корне репозитория:
| Стек | Файл |
|---|---|
| Python | requirements.txt, pyproject.toml или Pipfile |
| Node.js | package.json (и package-lock.json / pnpm-lock.yaml / yarn.lock) |
| PHP | composer.json |
Если пакет установлен только у вас на машине, но не записан в манифест — на сборке его не будет. Закоммитьте манифест и файл блокировки версий (lock-файл) в репозиторий.
2. Задайте команду запуска
Сборщику нужно знать, чем запускается ваше приложение. Способ зависит от стека (например, скрипт start в package.json для Node.js или файл Procfile для Python) — точная форма описана в статье по вашему стеку. Без явной команды запуска сборка либо завершится ошибкой, либо запустит не то.
3. Слушайте порт сервиса на адресе 0.0.0.0 (для Web-сервиса)
Два обязательных условия для Web-сервиса:
- Слушайте порт сервиса. Надёжнее всего прочитать его из переменной окружения
PORT— платформа задаёт её сама, равной порту сервиса. Жёстко прописанный в коде тот же номер тоже сработает, но сломается, если вы поменяете порт в настройках. - Привязывайтесь к адресу
0.0.0.0, а не кlocalhost/127.0.0.1.
Если это не выполнено, сборка и деплой пройдут успешно, но домен вернёт ошибку 502: обратный прокси стучится на порт сервиса, а приложение там не слушает. Переменную PORT задавать вручную нельзя — она зарезервирована платформой.
Worker-сервисов это не касается — у них нет порта и домена, они ничего не слушают.
4. Выносите настройки в переменные окружения
Адреса баз данных, токены и ключи задаются через переменные окружения сервиса: на платформе у базы данных свой внутренний хост, а секреты в репозитории рискуют утечь. Как задать и прочитать — «Переменные окружения и секреты».
5. Храните данные в базе данных
Файловая система контейнера эфемерна: при каждом развёртывании она создаётся заново. Файл базы SQLite, загруженные пользователями файлы, локальные логи — всё это исчезнет после следующего деплоя. Постоянные данные держите в базе данных проекта. Подробнее — «Данные не сохраняются в контейнере».
Если сборку не удаётся уложить в эти правила
Nixpacks покрывает большинство стандартных проектов. Если вашему приложению нужен полный контроль над сборкой (нестандартные системные пакеты, особый порядок шагов), добавьте в репозиторий Dockerfile и выберите способ сборки Dockerfile. Тогда правила 1–2 не действуют — вы описываете установку и запуск сами; но условие про порт (пункт 3) остаётся в силе.
Частые ошибки
| Симптом | Причина | Решение |
|---|---|---|
| Сборка падает: пакет не найден | Зависимость не объявлена в манифесте | Добавьте её в манифест и lock-файл, закоммитьте |
| Сборка проходит, но контейнер сразу останавливается | Нет корректной команды запуска | Задайте команду запуска (см. статью по стеку) |
| Деплой успешен, но домен отдаёт 502 | Приложение слушает не тот порт или только localhost | Слушайте PORT на 0.0.0.0 (пункт 3) |
| Локально работает, на платформе — ошибки подключения | Захардкожены локальные адреса/секреты | Вынесите в переменные окружения (пункт 4) |
| После деплоя пропали данные | Данные лежали в файлах контейнера | Перенесите в базу данных (пункт 5) |
Дальше
Настройка под конкретный стек, с примерами команды запуска и кода: