Быстрое развёртывание на Ubuntu¶

Минимальные шаги, чтобы поднять систему на сервере Ubuntu за несколько минут.

1. Установить Docker и Docker Compose¶

sudo apt update
sudo apt install -y ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
sudo usermod -aG docker $USER
# Выйдите и зайдите снова (или newgrp docker), чтобы применить группу

2. Клонировать проект и перейти в каталог¶

cd /opt   # или другой каталог, например /var/www
sudo git clone <URL-репозитория> library_system
cd library_system

3. Создать файл окружения `.env`¶

В корне проекта (рядом с docker-compose.yml) создайте файл .env:

nano .env

Минимальное содержимое (без пробелов вокруг =, без кавычек, каждое значение в одну строку):

POSTGRES_PASSWORD=придумайте_надёжный_пароль
JWT_SECRET=ваш_jwt_секрет_32_символа_hex
CSRF_SECRET=ваш_csrf_секрет_32_символа_hex
VITE_API_URL=/api

Секреты можно сгенерировать: openssl rand -hex 32. Файл должен называться именно .env и лежать в корне проекта (рядом с docker-compose.yml).

Если вы используете уже свой .env (например с внешней БД и LDAP): достаточно добавить в него одну строку для сборки фронта: VITE_API_URL=/api. Backend подхватит из .env DATABASE_URL, JWT_SECRET, LDAP_* и т.д. Контейнер PostgreSQL в этом случае не запускается (он в профиле db). Запуск: docker compose up -d (без --profile db).

Если поднимаете БД в Docker: добавьте в .env POSTGRES_PASSWORD=... и запускайте с профилем: docker compose --profile db up -d.

4. Запуск (вариант «только HTTP», без SSL)¶

Используйте готовый compose-файл для быстрого старта (Nginx слушает только порт 80):

docker compose up -d

Первая сборка может занять 2–5 минут. После запуска приложение доступно по адресу http://IP-ВАШЕГО-СЕРВЕРА.

Развёртывание с доменом и HTTPS¶

Если у вас уже есть домен (например library.example.com), можно поднять сайт по HTTPS с бесплатным сертификатом Let's Encrypt.

Предварительно¶

DNS: Укажите A-запись вашего домена на IP сервера (например library.example.com → 123.45.67.89). Дождитесь обновления DNS (проверка: ping library.example.com).
Порты: На сервере должны быть открыты 80 и 443 (если есть файрвол: sudo ufw allow 80 && sudo ufw allow 443 && sudo ufw enable).

Шаг 1. Запуск по HTTP (порт 80)¶

Создайте .env в корне проекта (как в разделе 3 выше), затем:

docker compose up -d
docker compose exec backend node migrations/migration-runner.js

Проверьте: в браузере открывается http://ваш-домен.ru.

Шаг 2. Получение сертификата Let's Encrypt¶

Временно остановите контейнер Nginx, чтобы порт 80 был свободен для certbot:

docker compose stop nginx

Установите certbot и получите сертификат (подставьте свой домен):

sudo apt install -y certbot
sudo certbot certonly --standalone -d ваш-домен.ru -d www.ваш-домен.ru

Укажите email, примите условия. Сертификаты появятся в /etc/letsencrypt/live/ваш-домен.ru/.

Снова запустите Nginx (пока без HTTPS):

docker compose start nginx

Шаг 3. Конфиг Nginx с вашим доменом и SSL¶

Скопируйте конфиг и подставьте свой домен:

cp nginx.prod.conf nginx.prod.my.conf

В nginx.prod.my.conf замените все вхождения library.codnix.ru на ваш домен (например library.example.com) и пути к сертификатам:

ssl_certificate /etc/letsencrypt/live/ваш-домен.ru/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/ваш-домен.ru/privkey.pem;

(Если certbot выдал один домен без www, оставьте один server_name и один путь к сертификату.)

Шаг 4. Запуск с HTTPS (production)¶

Остановите быстрый вариант и запустите полный prod с вашим конфигом:

docker compose down

Скопируйте nginx.prod.conf в свой файл (например nginx.prod.my.conf) и укажите домен. SSL подключается файлом docker-compose.ssl.yml (том /etc/letsencrypt, порты 80/443).

Запуск:

docker compose -f docker-compose.yml -f docker-compose.ssl.yml up -d

Проверка: https://ваш-домен.ru и https://ваш-домен.ru/api/health.

Шаг 5. Переменные окружения для домена¶

В корневом .env можно задать (опционально, для бэкенда/фронта):

VITE_API_URL=/api

Фронт собирается с этим значением; при доступе по https://ваш-домен.ru запросы уходят на /api того же домена — менять ничего не нужно.

Обновление сертификата (раз в ~90 дней)¶

Let's Encrypt выдаёт сертификаты на 90 дней. Обновление:

sudo certbot renew
sudo docker compose -f docker-compose.yml -f docker-compose.ssl.yml exec nginx nginx -s reload

Или через cron (проверка дважды в день):

sudo crontab -e
# Добавить:
0 3,15 * * * certbot renew -q && docker compose -f /opt/library_system/docker-compose.yml -f /opt/library_system/docker-compose.ssl.yml exec nginx nginx -s reload

(Путь к проекту замените на свой.)

5. Выполнить миграции БД¶

После первого запуска контейнеров:

docker compose exec backend node migrations/migration-runner.js

Или, если в образе есть npm-скрипт:

docker compose exec backend npm run migrate

6. Проверка¶

Сайт: http://IP-ВАШЕГО-СЕРВЕРА или http://ваш-домен
API: http://IP-ВАШЕГО-СЕРВЕРА/api/health — должен вернуть {"status":"ok"} или аналог
Первый вход: создайте пользователя-администратора через скрипт или через API (если есть эндпоинт первичной настройки).

7. Фоновые задачи¶

Очередь бронирований (outbox)¶

В Docker очередь обрабатывает отдельный контейнер outbox-worker (scripts/run-outbox-daemon.js). У backend по умолчанию OUTBOX_WORKER_ENABLED=false, чтобы не дублировать обработку.

После возврата и отмены брони API сразу вызывает продвижение очереди; outbox-worker — подстраховка. Отдельный cron для outbox обычно не нужен.

Проверка:

docker compose ps outbox-worker
docker compose logs outbox-worker | tail -20

При необходимости ручной прогон:

docker compose exec backend node scripts/process-outbox-events.js

Просроченные бронирования¶

Рекомендуется профиль jobs (контейнер booking-cleanup, раз в сутки) или cron на хосте:

sudo crontab -e

0 * * * * cd /opt/library_system && docker compose exec -T backend node scripts/cleanup-expired-bookings.js

Резервные копии¶

В .env: BACKUP_ENABLED=true. Каталог ./backups монтируется в контейнер. Управление: Администрирование → Система.

Вариант без Docker (только Node + PostgreSQL на Ubuntu)¶

Установить Node.js 18+, PostgreSQL 14+, npm.
Создать БД и пользователя в PostgreSQL.
В корне: cp server/env.example server/.env, прописать DATABASE_URL и секреты.
npm install в корне и в server/.
В server/: npm run migrate, затем npm start.
В корне: npm run build, раздавать каталог dist через Nginx и проксировать /api на http://localhost:3001 (или порт из server/.env).

Подробности — в DEPLOYMENT.md.

SSL (Let's Encrypt) позже¶

Когда будет домен:

Установите certbot: sudo apt install certbot.
Получите сертификат: sudo certbot certonly --webroot -w /var/www/certbot -d ваш-домен.ru.
Для SSL в Docker используйте docker-compose.ssl.yml (см. DOCKER.md).
Замените конфиг nginx на nginx.prod.conf и подставьте в нём свой server_name и пути к сертификатам (или скопируйте блок из текущего nginx.prod.conf).

Подробнее — раздел «Настройка SSL» в DEPLOYMENT.md.