Руководство по настройке CI/CD для Next.js проекта с GitLab, Yarn и VPS

1. Подготовка проекта

1. Структура проекта:
   Убедитесь, что в package.json используются скрипты для Yarn:

   "scripts": {
     "build": "next build",
     "start": "next start",
     "dev": "next dev"
   }
   

   Проверьте локальную сборку:

   yarn build && yarn start
   

2. Игнорируемые файлы:
   Добавьте в .gitignore:

   .env
   .next
   node_modules
   .yarn/cache
   .yarn/unplugged
   .yarn/install-state.gz
   

3. Настройка переменных окружения:
   Создайте .env.production с продакшен-переменными.

2. Создание репозитория на GitLab

1. Создайте новый проект в GitLab.
2. Привяжите локальный проект:

   git remote add origin git@gitlab.com:your-username/your-project.git
   git push -u origin main
   

3. Настройка VPS (Ubuntu 22.04 LTS)

1. Установка базовых зависимостей:

   sudo apt update && sudo apt upgrade -y
   sudo apt install -y nginx git
   
   # Установка Node.js и Yarn
   curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
   sudo apt install -y nodejs
   sudo corepack enable
   sudo corepack prepare yarn@stable --activate
   
   # Установка PM2
   sudo yarn global add pm2
   

2. Создание пользователя для деплоя:

   sudo adduser deploy
   usermod -aG sudo deploy
   

3. Настройка Nginx (аналогично предыдущему руководству).

4. Настройка SSH-доступа:
   Скопируйте публичный SSH-ключ пользователя deploy в ~/.ssh/authorized_keys.

4. Интеграция GitLab с VPS

1. Создание SSH-ключа для CI/CD:
   На VPS выполните:

   sudo -u deploy ssh-keygen -t ed25519 -C "gitlab-ci"
   

   Добавьте публичный ключ в ~/.ssh/authorized_keys.

2. Добавление приватного ключа в GitLab:

   • Скопируйте содержимое приватного ключа (cat ~/.ssh/id_ed25519) с VPS.
   • В GitLab: Settings > CI/CD > Variables → добавьте переменную SSH_PRIVATE_KEY.

5. Настройка GitLab CI/CD

Создайте файл .gitlab-ci.yml:

stages:
  - build
  - deploy

cache:
  key: ${CI_COMMIT_REF_SLUG}
  paths:
    - .yarn/cache
    - node_modules/
    - .next/cache/

build:
  stage: build
  image: node:20-alpine
  before_script:
    - corepack enable
    - corepack prepare yarn@stable --activate
  script:
    - yarn install --immutable
    - yarn build
  artifacts:
    paths:
      - .next
      - public
      - package.json
      - yarn.lock
      - next.config.js
      - .yarn/**
  only:
    - main

deploy:
  stage: deploy
  image: alpine:latest
  before_script:
    - apk add --no-cache openssh-client rsync
    - eval $(ssh-agent -s)
    - echo "$SSH_PRIVATE_KEY" | tr -d '\r' | ssh-add -
    - mkdir -p ~/.ssh
    - chmod 700 ~/.ssh
  script:
    - rsync -azP --delete \
      --exclude=".git" \
      --exclude=".env" \
      --exclude="node_modules" \
      . deploy@your-server-ip:/home/deploy/app/
    - ssh deploy@your-server-ip "cd /home/deploy/app && yarn install --production --immutable && pm2 restart next-app"

6. Дополнительные настройки

1. PM2-конфигурация:
   На VPS создайте ecosystem.config.js в папке проекта:

   module.exports = {
     apps: [{
       name: "next-app",
       script: "yarn start",
       env: {
         NODE_ENV: "production"
       }
     }]
   };
   

2. Переменные окружения на VPS:
   Создайте файл /home/deploy/app/.env.production и добавьте секреты.

7. Запуск CI/CD

1. После пуша в ветку main GitLab автоматически запустит сборку.
2. Убедитесь, что:
   • В артефакты включен .yarn/cache для кэширования пакетов.
   • Используется --immutable для гарантии идентичности зависимостей.

8. Мониторинг

1. Проверьте статус пайплайна в GitLab CI/CD.
2. На VPS просмотрите логи PM2:

   pm2 logs next-app
   

Важно!

• Используйте yarn install --immutable для строгого контроля версий.
• Для Next.js 14+ добавьте кэширование Turbopack (если используется) в cache GitLab CI.