Deployment

Руководство по развертыванию Integ API в различных окружениях.

Обзор окружений

Проект поддерживает три окружения:

Окружение	Назначение	Doppler Config
Local	Локальная разработка	`local`
Dev	Development сервер	`dev`
Prod	Production сервер	`prod`

Подготовка к деплою

1. Настройка переменных окружения

Убедитесь, что все переменные настроены в Doppler для целевого окружения:

bash

# Проверка переменных
doppler secrets --config dev

# Добавление переменных
doppler secrets set POSTGRES_HOST your-db-host --config dev

Полный список переменных см. в Configuration.

2. Сборка приложения

bash

# Для dev окружения
npm run build:dev

# Для prod окружения
npm run build:prod

Это:

Генерирует environment.ts из Doppler
Компилирует TypeScript в JavaScript
Создает папку dist/ с готовым приложением

3. Проверка сборки

bash

# Запуск собранного приложения локально
npm run start:dev

# Или для prod
npm run start:prod

Docker Deployment

Dockerfile

Проект включает два Dockerfile:

Dockerfile.dev - для development
Dockerfile.prod - для production (multi-stage build)

Production Dockerfile

dockerfile

# Stage 1: Build
FROM node:20-alpine AS builder

WORKDIR /app

COPY package*.json ./
RUN npm ci

COPY . .
RUN npm run build:prod

# Stage 2: Production
FROM node:20-alpine

WORKDIR /app

COPY package*.json ./
RUN npm ci --only=production

COPY --from=builder /app/dist ./dist

EXPOSE 3000

CMD ["node", "dist/main"]

Сборка Docker образа

bash

# Production
docker build -f Dockerfile.prod -t happ-integ-api:latest .

# Development
docker build -f Dockerfile.dev -t happ-integ-api:dev .

Запуск контейнера

bash

# С переменными из Doppler
docker run -d \
  --name integ-api \
  -p 3000:3000 \
  -e DATABASE_HOST=your-db-host \
  -e DATABASE_PASSWORD=your-password \
  -e JWT_SECRET=your-jwt-secret \
  happ-integ-api:latest

# Или используя Doppler
doppler run --config prod -- docker run -d \
  --name integ-api \
  -p 3000:3000 \
  --env-file <(doppler secrets download --format docker --config prod) \
  happ-integ-api:latest

Docker Compose

Production setup

yaml

version: "3.8"

services:
  integ-api-db:
    image: postgres:16
    container_name: integ-api-db
    restart: unless-stopped
    environment:
      POSTGRES_USER: user
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: integ-api
    ports:
      - "5432:5432"
    volumes:
      - integ-api-db:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U user -d integ-api"]
      interval: 5s
      timeout: 5s
      retries: 5

  integ-api:
    image: happ-integ-api:latest
    container_name: happ-integ-api
    restart: unless-stopped
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=production
      - PORT=3000
      - POSTGRES_HOST=integ-api-db
    depends_on:
      integ-api-db:
        condition: service_healthy
    env_file:
      - .env.prod

volumes:
  integ-api-db:

Запуск с Docker Compose

bash

# Запуск
docker-compose up -d

# Просмотр логов
docker-compose logs -f integ-api

# Остановка
docker-compose down

# Остановка с удалением volumes
docker-compose down -v

Миграции базы данных

На production сервере

bash

# SSH на сервер
ssh user@your-server

# Перейти в директорию проекта
cd /path/to/integ-api

# Запустить миграции
npm run migration:run

# Или через Docker
docker exec integ-api npm run migration:run

Rollback миграций

bash

# Откат последней миграции
npm run migration:revert

# Или через Docker
docker exec integ-api npm run migration:revert

Cloud Platforms

DigitalOcean App Platform

Подготовка:
- Создайте PostgreSQL managed database
- Настройте environment variables

Создание App:

yaml

name: integ-api
services:
  - name: api
    github:
      repo: your-org/integ-api
      branch: main
    build_command: npm run build:prod
    run_command: npm run start:prod
    environment_slug: node-js
    instance_count: 1
    instance_size_slug: basic-xxs
    envs:
      - key: PORT
        value: "3000"
      - key: NODE_ENV
        value: "production"
databases:
  - name: integ-db
    engine: PG
    version: "16"

Deploy:
- Push to main branch
- Automatic deployment via GitHub Actions

AWS (EC2 + RDS)

RDS Setup:

bash

# Создайте PostgreSQL RDS instance
aws rds create-db-instance \
  --db-instance-identifier integ-api-db \
  --db-instance-class db.t3.micro \
  --engine postgres \
  --engine-version 16 \
  --master-username admin \
  --master-user-password your-password \
  --allocated-storage 20

EC2 Setup:

bash

# SSH на EC2 instance
ssh -i your-key.pem ec2-user@your-instance

# Установка Node.js
curl -fsSL https://rpm.nodesource.com/setup_20.x | sudo bash -
sudo yum install -y nodejs

# Установка Docker
sudo yum install -y docker
sudo systemctl start docker
sudo systemctl enable docker

# Клонирование и запуск
git clone your-repo
cd integ-api
docker-compose up -d

Security Groups:
- Открыть порт 3000 для приложения
- Открыть порт 5432 для RDS (только для EC2 security group)

Heroku

Создание приложения:

bash

heroku create integ-api
heroku addons:create heroku-postgresql:hobby-dev

Настройка переменных:

bash

heroku config:set JWT_SECRET=your-secret
heroku config:set CRYPTO_KEY=your-master-encryption-key
heroku config:set CRYPTO_SALT=your-encryption-salt
# ... другие переменные

Деплой:
bash
```
git push heroku main
```
Запуск миграций:
bash
```
heroku run npm run migration:run
```

CI/CD

GitHub Actions

Пример workflow для автоматического деплоя:

yaml

# .github/workflows/deploy.yml
name: Deploy to Production

on:
  push:
    branches: [main]

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v3

      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: "20"

      - name: Install dependencies
        run: npm ci

      - name: Install Doppler CLI
        uses: dopplerhq/cli-action@v1

      - name: Generate environment
        run: doppler run --config prod -- npm run generate:env:prod
        env:
          DOPPLER_TOKEN: ${{ secrets.DOPPLER_TOKEN }}

      - name: Build application
        run: npm run build:prod

      - name: Run tests
        run: npm test

      - name: Build Docker image
        run: docker build -f Dockerfile.prod -t integ-api:${{ github.sha }} .

      - name: Push to registry
        run: |
          docker tag integ-api:${{ github.sha }} registry.example.com/integ-api:latest
          docker push registry.example.com/integ-api:latest

      - name: Deploy to server
        uses: appleboy/ssh-action@master
        with:
          host: ${{ secrets.SERVER_HOST }}
          username: ${{ secrets.SERVER_USER }}
          key: ${{ secrets.SSH_KEY }}
          script: |
            cd /app/integ-api
            docker-compose pull
            docker-compose up -d
            docker exec integ-api npm run migration:run

GitLab CI

yaml

# .gitlab-ci.yml
stages:
  - build
  - test
  - deploy

build:
  stage: build
  script:
    - npm ci
    - npm run build:prod
  artifacts:
    paths:
      - dist/

test:
  stage: test
  script:
    - npm ci
    - npm test

deploy-prod:
  stage: deploy
  only:
    - main
  script:
    - docker build -f Dockerfile.prod -t integ-api:latest .
    - docker push registry.gitlab.com/your-org/integ-api:latest
    - ssh user@server 'cd /app && docker-compose up -d'

Cloudflare Pages (Документация)

Документация приложения развёртывается автоматически на Cloudflare Pages через GitHub Actions.

Автоматический деплой

Workflow .github/workflows/docs.yml автоматически:

Собирает документацию при push в ветки main или dev с изменениями в папке docs/
Создает Pages проекты если их ещё нет на Cloudflare
Деплоит в проект integ-api-docs

Проекты Pages

Проект	Ветка	URL по умолчанию	Домен
`integ-api-docs`	main	integ-api-docs.pages.dev	api.integ.docs.happ.tools

Необходимые секреты GitHub

Для работы workflow требуются следующие секреты в репозитории:

Секрет	Описание
`CLOUDFLARE_PAGES_API_TOKEN`	API токен Cloudflare для Pages (с правами на создание/редактирование проектов)
`CLOUDFLARE_ACCOUNT_ID`	ID вашего Cloudflare аккаунта

Добавление секретов:

Перейти в Settings → Secrets and variables → Actions
Нажать "New repository secret"
Добавить CLOUDFLARE_PAGES_API_TOKEN и CLOUDFLARE_ACCOUNT_ID

Привязка доменов

Для привязки проектов к доменам happ.tools:

В Cloudflare Dashboard перейти в Pages
Выбрать проект integ-api-docs
Settings → Domains → Add custom domain
Указать api.integ.docs.happ.tools

Требования к DNS

Убедитесь, что домен happ.tools настроен на Cloudflare:

Он должен быть добавлен в ваш Cloudflare аккаунт
Cloudflare должен быть nameserver для этого домена
Система CNAME для Pages подменов будет настроена автоматически при добавлении домена в Pages

Структура документации

Документация находится в папке docs/ и собирается с помощью VitePress:

docs/
├── index.md                    # Главная страница
├── api-guide/                  # API документация
├── architecture/               # Архитектура
├── deployment/                 # Развертывание (этот файл)
├── development/                # Разработка
├── getting-started/            # Начало работы
└── .vitepress/
    └── config.mts              # Конфигурация VitePress

Сборка документации локально

bash

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

# Развертывание в dev режиме
npm run docs:dev

# Сборка документации
npm run docs:build

# Предпросмотр собранной документации
npm run docs:preview

Troubleshooting

Деплой не срабатывает:

Проверьте наличие секретов CLOUDFLARE_PAGES_API_TOKEN и CLOUDFLARE_ACCOUNT_ID
Убедитесь, что у токена есть права на создание Pages проектов
Проверьте логи workflow в GitHub Actions

Проект не создается автоматически:

Проверьте ошибки в логах GitHub Actions на шаге "Create Pages project if it doesn't exist"
Убедитесь, что CLOUDFLARE_ACCOUNT_ID корректен
Проверьте, что токен валиден

Health Checks

Endpoint

http

GET /health

Response:

json

{
	"status": "ok",
	"info": {
		"database": {
			"status": "up"
		}
	},
	"error": {},
	"details": {
		"database": {
			"status": "up"
		}
	}
}

Мониторинг

Настройте health check проверки:

Docker Compose:

yaml

healthcheck:
  test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
  interval: 30s
  timeout: 10s
  retries: 3
  start_period: 40s

Kubernetes:

yaml

livenessProbe:
  httpGet:
    path: /health
    port: 3000
  initialDelaySeconds: 30
  periodSeconds: 10

readinessProbe:
  httpGet:
    path: /health
    port: 3000
  initialDelaySeconds: 5
  periodSeconds: 5

Monitoring & Logging

Sentry

Sentry уже интегрирован для отслеживания ошибок:

bash

# Установите SENTRY_DSN в Doppler
doppler secrets set SENTRY_DSN your-sentry-dsn --config prod

Logs

bash

# Docker logs
docker logs -f integ-api

# Docker Compose logs
docker-compose logs -f integ-api

# Systemd logs (если используется systemd)
journalctl -u integ-api -f

Backup & Recovery

Database Backup

bash

# Создание backup
docker exec integ-api-db pg_dump -U user integ-api > backup.sql

# Или через pg_dump напрямую
pg_dump -h your-db-host -U user -d integ-api > backup.sql

# Восстановление
psql -h your-db-host -U user -d integ-api < backup.sql

Автоматический backup

bash

# Cron job для ежедневного backup
0 2 * * * docker exec integ-api-db pg_dump -U user integ-api | gzip > /backups/integ-api-$(date +\%Y\%m\%d).sql.gz

Scaling

Horizontal Scaling

Для горизонтального масштабирования:

Используйте load balancer (nginx, HAProxy, AWS ALB)
Запустите несколько инстансов приложения
Используйте shared PostgreSQL и Redis

yaml

# Docker Compose с несколькими инстансами
services:
  integ-api:
    image: happ-integ-api:latest
    deploy:
      replicas: 3

Vertical Scaling

Увеличение ресурсов инстанса:

bash

# Docker ресурсы
docker run -d \
  --cpus="2.0" \
  --memory="2g" \
  integ-api:latest

Troubleshooting

Приложение не запускается

Проверьте логи: docker logs integ-api
Проверьте переменные окружения
Проверьте подключение к БД

Ошибки подключения к БД

bash

# Проверка подключения
docker exec integ-api-db psql -U user -d integ-api -c "SELECT 1"

# Проверка network
docker network inspect integ-api_default

Миграции не применяются

bash

# Проверка статуса миграций
docker exec integ-api npm run typeorm migration:show

# Ручной запуск
docker exec integ-api npm run migration:run

Best Practices

✅ DO:

Используйте managed databases в production
Настройте автоматические backups
Используйте SSL/TLS для БД подключений
Настройте мониторинг и алерты
Используйте secrets management (Doppler, AWS Secrets Manager)
Регулярно обновляйте зависимости

❌ DON'T:

Не храните секреты в коде или Git
Не используйте одинаковые секреты для разных окружений
Не запускайте миграции автоматически в production (делайте вручную)
Не забывайте про backups

Следующие шаги

Getting Started - Локальная разработка
Architecture - Архитектура приложения
API Guide - Использование API

Deployment ​

Обзор окружений ​

Подготовка к деплою ​

1. Настройка переменных окружения ​

2. Сборка приложения ​

3. Проверка сборки ​

Docker Deployment ​

Dockerfile ​

Production Dockerfile ​

Сборка Docker образа ​

Запуск контейнера ​

Docker Compose ​

Production setup ​

Запуск с Docker Compose ​

Миграции базы данных ​

На production сервере ​

Rollback миграций ​

Cloud Platforms ​

DigitalOcean App Platform ​

AWS (EC2 + RDS) ​

Heroku ​

CI/CD ​

GitHub Actions ​

GitLab CI ​

Cloudflare Pages (Документация) ​

Автоматический деплой ​

Проекты Pages ​

Необходимые секреты GitHub ​

Привязка доменов ​

Требования к DNS ​

Структура документации ​

Сборка документации локально ​

Troubleshooting ​

Health Checks ​

Endpoint ​

Мониторинг ​

Monitoring & Logging ​

Sentry ​

Logs ​

Backup & Recovery ​

Database Backup ​

Автоматический backup ​

Scaling ​

Horizontal Scaling ​

Vertical Scaling ​

Troubleshooting ​

Приложение не запускается ​

Ошибки подключения к БД ​

Миграции не применяются ​

Best Practices ​

Следующие шаги ​

Deployment

Обзор окружений

Подготовка к деплою

1. Настройка переменных окружения

2. Сборка приложения

3. Проверка сборки

Docker Deployment

Dockerfile

Production Dockerfile

Сборка Docker образа

Запуск контейнера

Docker Compose

Production setup

Запуск с Docker Compose

Миграции базы данных

На production сервере

Rollback миграций

Cloud Platforms

DigitalOcean App Platform

AWS (EC2 + RDS)

Heroku

CI/CD

GitHub Actions

GitLab CI

Cloudflare Pages (Документация)

Автоматический деплой

Проекты Pages

Необходимые секреты GitHub

Привязка доменов

Требования к DNS

Структура документации

Сборка документации локально

Troubleshooting

Health Checks

Endpoint

Мониторинг

Monitoring & Logging

Sentry

Logs

Backup & Recovery

Database Backup

Автоматический backup

Scaling

Horizontal Scaling

Vertical Scaling

Troubleshooting

Приложение не запускается

Ошибки подключения к БД

Миграции не применяются

Best Practices

Следующие шаги