mkd/docs/UBUNTU_SETUP.md

Запуск проекта на Ubuntu 24.04

После переноса с Windows проект запускается на Ubuntu так же через Node.js и PostgreSQL. Ниже — пошаговая настройка.

1. Установка Node.js (18+)

# Через NodeSource (рекомендуется LTS)
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs

# Проверка
node -v   # v20.x.x
npm -v

Либо через стандартный репозиторий Ubuntu:

sudo apt update
sudo apt install -y nodejs npm

2. Установка PostgreSQL

sudo apt update
sudo apt install -y postgresql postgresql-contrib
sudo systemctl start postgresql
sudo systemctl enable postgresql

Создание пользователя и базы (опционально, если ещё не созданы):

sudo -u postgres psql -c "CREATE USER mkd_user WITH PASSWORD 'your_password';"
sudo -u postgres psql -c "CREATE DATABASE mkd_control_center OWNER mkd_user;"

Строка подключения для .env бэкенда:

postgres://mkd_user:your_password@localhost:5432/mkd_control_center

3. Зависимости для Puppeteer (бэкенд)

Бэкенд использует Puppeteer. На Ubuntu нужны системные библиотеки:

sudo apt install -y \
  ca-certificates fonts-liberation libasound2 libatk-bridge2.0-0 \
  libatk1.0-0 libc6 libcairo2 libcups2 libdbus-1-3 libexpat1 \
  libfontconfig1 libgbm1 libgcc1 libglib2.0-0 libgtk-3-0 libnspr4 \
  libnss3 libpango-1.0-0 libpangocairo-1.0-0 libstdc++6 libx11-6 \
  libx11-xcb1 libxcb1 libxcomposite1 libxcursor1 libxdamage1 \
  libxext6 libxfixes3 libxi6 libxrandr2 libxrender1 libxss1 \
  libxtst6 lsb-release wget xdg-utils

4. Настройка проекта

4.1 Клонирование / копирование

Если репозиторий уже скопирован в каталог проекта (например, /home/its/mkd), переходите в него:

cd /home/its/mkd

4.2 Установка зависимостей

В корне (фронтенд) и в backend:

npm install
cd backend && npm install && cd ..

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

Корень проекта — для фронтенда. Создайте .env или .env.local на основе .env.example:

cp .env.example .env.local
# Отредактируйте .env.local при необходимости (VITE_API_BASE_URL, Doma AI и т.д.)

Бэкенд — в backend/.env должны быть минимум:

# Обязательно для работы БД
DATABASE_URL=postgres://mkd_user:your_password@localhost:5432/mkd_control_center

# Обязательно в production
JWT_SECRET=ваш-секретный-ключ-для-jwt
JWT_EXPIRES_IN=7d

# Опционально: Doma AI, Turnstile и т.д.
# DOMA_API_URL=...
# DOMA_API_TOKEN=...

Пути в конфигах (например, path.join(__dirname, 'uploads')) на Linux не меняют — Node использует / и path.join корректно.

5. Запуск

Нужны два процесса: бэкенд (API) и фронтенд (Vite).

Вариант A: два терминала

Терминал 1 — бэкенд:

cd /home/its/mkd/backend
npm start

Должно появиться сообщение о запуске на порту 4000 (или вашем PORT).

Терминал 2 — фронтенд:

cd /home/its/mkd
npm run dev

Откройте в браузере: http://localhost:3000. Запросы к /api уйдут на бэкенд через прокси Vite (localhost:4000).

Вариант B: один терминал (фоновый бэкенд)

cd /home/its/mkd/backend && npm start &
cd /home/its/mkd && npm run dev

Сборка для production

cd /home/its/mkd
npm run build

Статика окажется в dist/. Раздавать её можно nginx’ом, указав API и uploads на бэкенд (порт 4000).

6. Проверка

Компонент	URL / проверка
Фронтенд	http://localhost:3000
API бэкенд	http://localhost:4000/api (например, health, если есть)
PostgreSQL	sudo -u postgres psql -c "\l" — список баз

7. Частые проблемы на Ubuntu

• «DATABASE_URL не задана» — добавьте DATABASE_URL в backend/.env и перезапустите бэкенд.
• Puppeteer/Chromium не запускается — установите зависимости из пункта 3; при необходимости в backend можно задать PUPPETEER_EXECUTABLE_PATH на системный chromium.
• Порт 3000 или 4000 занят — смените в .env: фронт — server.port в vite.config.ts или переменные Vite; бэкенд — PORT в backend/.env.
• Права на каталог uploads — если бэкенд пишет файлы от другого пользователя: chmod 755 backend/uploads (или 775 при необходимости).

После выполнения шагов 1–5 проект на Ubuntu 24.04 должен запускаться так же, как на Windows.