mkd/docs/UBUNTU_SETUP.md

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

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

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

```bash
# Через 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:

```bash
sudo apt update
sudo apt install -y nodejs npm
```

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

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

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

```bash
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 нужны системные библиотеки:

```bash
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`), переходите в него:

```bash
cd /home/its/mkd
```

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

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

```bash
npm install
cd backend && npm install && cd ..
```

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

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

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

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

```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 — бэкенд:**

```bash
cd /home/its/mkd/backend
npm start
```

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

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

```bash
cd /home/its/mkd
npm run dev
```

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

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

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

### Сборка для production

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