Node.js на хостинге cPanel: установка и запуск приложения

Современный shared хостинг с cPanel поддерживает Node.js через Apache Passenger. Это позволяет запускать Express, Next.js и другие Node.js приложения без аренды VPS — Passenger сам управляет процессом Node.js так же, как обычно управляет PHP-FPM воркерами. Главное отличие от классического деплоя на VPS в том, что вам не нужно самостоятельно настраивать reverse proxy или systemd-сервис — весь жизненный цикл процесса (запуск, перезапуск при падении, остановка при простое) берёт на себя Apache через модуль mod_passenger.

Запуск Node.js через cPanel

Шаг 1: Setup Node.js App

cPanel → Software → Setup Node.js App → Create Application.

Шаг 2: Загрузить файлы

# Структура приложения в ~/myapp/
myapp/
├── app.js         (точка входа)
├── package.json
└── node_modules/  (создастся при npm install)

Шаг 3: Установить зависимости

В Setup Node.js App нажмите «Run NPM Install» или через SSH:

cd ~/myapp
npm install

Шаг 4: Минимальный app.js

const express = require('express');
const app = express();
const PORT = process.env.PORT || 3000;

app.get('/', (req, res) => {
    res.send('Hello from Node.js on cPanel!');
});

app.listen(PORT, () => {
    console.log(`Server running on port ${PORT}`);
});

Типичная ошибка запуска

Если зависимости не установлены или указан неверный стартовый файл, при обращении к сайту появляется стандартная страница Passenger с текстом:

Web application could not be started

Error: Cannot find module 'express'
Require stack:
- /home/user/myapp/app.js

Это означает, что npm install не выполнялся в той же версии Node.js, что указана в Setup Node.js App, либо папка node_modules была скопирована с другого сервера — нативные модули с бинарными зависимостями (например, bcrypt, sharp) собираются под конкретную версию Node.js и архитектуру и не переносятся между окружениями. Решение — удалить node_modules и выполнить npm install заново через интерфейс Setup Node.js App, который активирует нужное окружение автоматически.

Переменные окружения

В интерфейсе Setup Node.js App → Add Variable:

NODE_ENV=production
DATABASE_URL=mysql://user:pass@localhost/dbname
API_KEY=your_secret_key

Passenger автоматически управляет процессом — перезапускает при сбое, не нужен PM2. Порт назначается автоматически через переменную process.env.PORT — не хардкодьте 3000 или любой другой порт в production, иначе приложение не запустится, если этот порт уже занят другим сайтом на сервере.

Проксирование через .htaccess для нестандартного пути

# Если Application URL указывает на подпапку, а не корень домена,
# Setup Node.js App создаёт .htaccess автоматически:
PassengerAppRoot "/home/user/myapp"
PassengerBaseURI "/app"
PassengerAppType node
PassengerStartupFile app.js

Эти директивы прописываются в .htaccess корня домена или подпапки — редактировать их вручную обычно не требуется, но если файл случайно удалён или перезаписан другим деплоем, приложение перестанет открываться с ошибкой 404, хотя процесс Node.js продолжает работать в фоне. В таком случае помогает повторное сохранение настроек в Setup Node.js App — интерфейс перезаписывает .htaccess с правильными директивами без необходимости трогать файл вручную.

Когда Node.js на shared-хостинге не подходит

• Приложению нужны постоянные WebSocket-соединения с большим числом одновременных клиентов — Passenger на shared-тарифах ограничивает число процессов и не рассчитан на тысячи долгоживущих сокетов
• Нужны фоновые задачи и очереди (cron-воркеры, обработка видео) — LVE ограничивает CPU и память процесса, длительные вычисления будут принудительно остановлены
• Требуется root-доступ для установки системных зависимостей нативных модулей — на shared-хостинге нет sudo, компиляция некоторых пакетов с C++ биндингами может не пройти
• Проект использует Docker или требует конкретную версию инфраструктуры (Redis, RabbitMQ) на том же сервере — shared-хостинг с cPanel таких сервисов не предоставляет, нужен VPS

Проверка результата

curl -I https://example.com/app/
# Ожидаем: HTTP/1.1 200 OK

# Логи приложения находятся в:
~/nodevenv/myapp/20/logs/

Если curl возвращает 502 Bad Gateway, значит процесс Node.js упал сразу после старта — смотрите вывод в интерфейсе Setup Node.js App или в логах Passenger, там будет точный stack trace ошибки, а не только общее сообщение «application could not be started», которое видит посетитель сайта. Подробнее о разборе логов ошибок в cPanel — в статье логи ошибок в cPanel, а про SSH-доступ для отладки — в статье SSH-доступ на хостинге cPanel.