04-node — Node.js (NodeSource + corepack)

Ставит Node.js нужной мажорной версии из официального репозитория NodeSource, включает npm, corepack и через него pnpm и yarn. ☐ опциональный модуль.

Зачем нужен #

Node.js — среда выполнения JavaScript на сервере. Модуль нужен всем приложениям, которые собираются и запускаются на Node: Next.js, NestJS, Express, обычные Node-сервисы, а также утилитам сборки фронтенда. Вместе с Node приходит npm (менеджер пакетов) и corepack — встроенный в Node «диспетчер» альтернативных менеджеров пакетов, через который активируются pnpm и yarn без ручной глобальной установки.

Модуль ставит именно свежую версию из репозитория NodeSource, а не устаревшую из стандартного репозитория дистрибутива.

Когда включать и когда не нужен #

Включайте, если разворачиваете приложение с пресетом node, next или nest (mitdev app), либо любой другой инструмент, которому нужен Node/npm.

Не нужен, если на сервере только PHP (модуль 20-php), Python (21-python), Go (22-go) или контейнеры Docker — в этих случаях Node на хосте не требуется.

Зависимости и требования #

• Базовые модули установщика (01-system — там ставится curl и gnupg, нужные для импорта GPG-ключа).
• Для реального запуска приложений почти всегда ставят в паре модуль 07-pm2 (менеджер процессов) и 06-nginx (reverse-proxy). PM2 сам по себе требует, чтобы модуль node был установлен первым.
• Интернет-доступ к deb.nodesource.com (Debian/Ubuntu) или rpm.nodesource.com (RHEL).

Что именно делает #

Шаги module_install (файл modules/04-node.sh):

1. Проверка на пропуск. Если node уже установлен и его версия совпадает с нужной мажорной (node -v начинается с v${NODE_MAJOR}.), репозиторий не подключается — модуль сразу переходит к corepack.
2. Debian/Ubuntu: создаёт каталог ключей /etc/apt/keyrings, импортирует GPG-ключ NodeSource в /etc/apt/keyrings/nodesource.gpg (GPG-ключ — цифровая подпись, которой apt проверяет подлинность пакетов), записывает репозиторий в /etc/apt/sources.list.d/nodesource.list, обновляет индекс пакетов и ставит пакет nodejs версии ${NODE_MAJOR}.x.
3. RHEL/SUSE: запускает официальный rpm-скрипт https://rpm.nodesource.com/setup_${NODE_MAJOR}.x, затем ставит пакет nodejs.
4. corepack enable — активирует corepack (идёт в комплекте с Node).
5. Через corepack устанавливает pnpm (corepack prepare pnpm@latest --activate) и yarn (corepack prepare yarn@stable --activate). Это официально поддерживаемый способ установки этих менеджеров, начиная с Node 16.
6. Верификация и отметка модуля выполненным.

Все шаги обёрнуты в run_step — полный вывод пишется в /var/log/mitdev/install.log, а откатные действия регистрируются в стеке отката на случай сбоя.

Файлы, службы и порты #

Служб (systemd-юнитов) модуль не создаёт: Node — это среда выполнения, а не демон. Порты открывает уже само приложение (по умолчанию 3000), проксируемое через nginx.

Настройка #

Это единственная переменная модуля (см. config/defaults.conf).

Как переопределить настройки #

Три способа (в порядке приоритета):

# 1. Экспорт переменной перед запуском установщика (флаг -E сохраняет переменные окружения при sudo):
export NODE_MAJOR=22
sudo -E ./install.sh

# 2. Правка значения по умолчанию в config/defaults.conf:
#    NODE_MAJOR="${NODE_MAJOR:-22}"

# 3. Установка одного модуля уже после первичной настройки:
sudo NODE_MAJOR=22 mitdev add node

Вопросов в интерактивном установщике этот модуль не задаёт — версия берётся из переменной.

Проверка, что всё работает #

Автоматическая верификация (module_verify) проверяет, что есть node и npm и что версия node начинается с v${NODE_MAJOR}..

Вручную:

node -v      # ожидается: v24.x.x
npm -v       # ожидается номер версии npm
pnpm -v      # ожидается номер версии pnpm
yarn -v      # ожидается номер версии yarn
mitdev node status   # сводка: node / npm / pnpm / yarn / pm2

Развёртывание приложения на этом рантайме #

Сквозной пример для Next.js-приложения (пресет next; для обычного Node — node, для NestJS — nest, всё работает одинаково: сборка → запуск под PM2 → nginx reverse-proxy).

Предполагается, что установлены модули node, pm2, nginx, а для HTTPS — certbot.

# 1. Развернуть приложение из git:
sudo mitdev app next webapp https://github.com/you/webapp.git app.example.com

Что произойдёт:

• репозиторий клонируется в ~deploy/apps/webapp (домашний каталог пользователя деплоя, по умолчанию /home/deploy/apps/webapp);
• если есть .env.example и нет .env — создаётся .env (отредактируйте его);
• устанавливаются зависимости: менеджер выбирается по lock-файлу — npm ci (при package-lock.json), pnpm install --frozen-lockfile (при pnpm-lock.yaml) или yarn install --frozen-lockfile (при yarn.lock), иначе npm install;
• выполняется npm run build (если сборка падает — не критично, продолжается);
• приложение запускается под PM2: PORT=3000 pm2 start npm --name webapp -- start (то есть в package.json должен быть скрипт start), затем pm2 save;
• nginx получает reverse-proxy app.example.com → 127.0.0.1:3000 из шаблона templates/nginx/app.conf.template (с поддержкой WebSocket), конфиг проверяется через nginx -t и включается;
• в конце установщик предложит выпустить SSL-сертификат.

# 2. Прописать переменные окружения (пример — БД и Redis):
sudo cat /root/.mitdev-credentials     # тут логины/пароли, созданные модулями PostgreSQL/Redis
sudo -u deploy nano ~deploy/apps/webapp/.env
# DATABASE_URL=postgresql://user:[email protected]:5432/app
# REDIS_URL=redis://:[email protected]:6379

# 3. Перезапустить с новым окружением:
sudo -u deploy -H pm2 restart webapp --update-env

# 4. Выпустить/перевыпустить сертификат вручную (если не сделали при app):
sudo mitdev ssl app.example.com [email protected]

# 5. Обновлять приложение после каждого push в git:
sudo mitdev deploy webapp
#    → git pull --ff-only, установка зависимостей, npm run build (если есть),
#      pm2 restart webapp --update-env.

Где логи приложения:

sudo -u deploy -H pm2 logs webapp        # живой поток stdout/stderr приложения
mitdev logs pm2                          # то же самое через mitdev
sudo tail -f /var/log/nginx/webapp.error.log   # ошибки reverse-proxy

Типовые задачи #

# Сменить мажорную версию Node и переустановить рантайм:
sudo NODE_MAJOR=22 mitdev add node       # подтвердите переустановку
node -v                                  # v22.x.x

# Обновить npm и pnpm до последних версий (без смены мажора Node):
sudo mitdev node update

# Обновить pnpm/yarn вручную через corepack:
sudo bash -c "COREPACK_ENABLE_DOWNLOAD_PROMPT=0 corepack prepare pnpm@latest --activate"

# Посмотреть, что стоит:
mitdev node status

# Перезапустить приложение:
sudo -u deploy -H pm2 restart webapp

# Откатить неудачное развёртывание Node (см. раздел «Откат и удаление»):
sudo mitdev remove node

Частые ошибки #

Симптом: mitdev app пишет «PM2 не найден у deploy — приложение не запущено». Причина: модуль node установлен, а модуль pm2 — нет. Решение: sudo mitdev add pm2, затем sudo mitdev deploy webapp.

Симптом: приложение не стартует, в pm2 logs — npm ERR! Missing script: "start". Причина: пресет node/next/nest запускает npm start, а в package.json нет скрипта start. Решение: добавьте "start" в scripts вашего package.json и повторите sudo mitdev deploy webapp.

Симптом: после установки node -v показывает старую версию. Причина: в системе уже был Node из стандартного репозитория, и его бинарник раньше в PATH. Решение: удалите старый пакет вручную и переустановите: sudo apt remove nodejs && sudo mitdev add node.

Симптом: установка падает на «Импорт GPG-ключа NodeSource». Причина: нет доступа к deb.nodesource.com (firewall/прокси). Решение: проверьте исходящий доступ; подробности — в /var/log/mitdev/errors.log.

Безопасность и продакшен #

• Не запускайте приложения от root. mitdev app всё делает от пользователя деплоя (deploy) — так и оставьте.
• Приложение слушает 127.0.0.1:PORT, наружу его публикует только nginx. Не открывайте порт приложения в файрволе.
• Держите зависимости обновлёнными (npm audit) и не храните секреты в git — используйте .env в каталоге приложения (он исключён из синхронизации при mitdev deploy из локального источника).
• Фиксируйте мажорную версию Node (NODE_MAJOR) под LTS, чтобы обновления не ломали сборку.

Откат и удаление #

module_rollback (срабатывает автоматически при сбое установки): удаляет пакет nodejs, файлы репозитория и ключа, обновляет индекс пакетов.

Ручное удаление:

sudo mitdev remove node

module_remove: отключает corepack, удаляет пакет nodejs (вместе с ним уходят npm, corepack, pnpm и yarn), убирает файлы репозитория NodeSource. Глобально установленные npm-пакеты удаляются вместе с рантаймом; node_modules в каталогах ваших приложений не трогаются. Флаг --purge для этого модуля дополнительных данных не удаляет.

См. также #

• ../COMMANDS.md — полный справочник команд (mitdev app, deploy, node, ssl, add, remove).
• 07-pm2.md — менеджер процессов для Node-приложений.
• ../DEPLOY.md и ../RECIPES.md — сценарии развёртывания.