test-tva — Frontend + Backend

Проект с React-фронтендом и NestJS-бэкендом. Включает полный CI/CD пайплайн на основе GitOps: Forgejo Actions, Harbor, ArgoCD + Image Updater.

Содержание

• Локальная разработка
• Архитектура пайплайна
• Предварительные требования
• Подготовка Harbor
• Подготовка Forgejo
• Структура проекта
• Docker-образы
• Kubernetes-манифесты
• CI/CD (Forgejo Actions)
• Деплой через ArgoCD
• Работа пайплайна
• Промоушен в прод
• Операции

---

Локальная разработка

# Backend
cd backend
npm install
npm run start:dev

# Frontend (в другом терминале)
cd frontend
npm install
npm run dev

Frontend: http://localhost:5173 Backend: http://localhost:3000 API-прокси: Vite автоматически проксирует /api → localhost:3000

---

Архитектура пайплайна

Push в Forgejo (main / tag v*)
       ↓
Forgejo Actions Runner
  ├── Тесты (backend + frontend)
  ├── Линтинг
  ├── Сборка Docker-образов
  └── Пуш в Harbor
       ↓
Harbor Registry
       ↓
ArgoCD Image Updater
  ├── Опрашивает Harbor
  └── Обновляет образы в git
       ↓
ArgoCD
  ├── Детектирует изменения
  └── Синхронизирует в K8s
       ↓
Kubernetes (dev / prod)

---

Предварительные требования

• Kubernetes кластер (v1.28+)
• kubectl настроенный на кластер
• Forgejo инстанс с включенным Actions runner и Docker-раннером
• Harbor реестр (доступен из CI runner и из кластера)
• ArgoCD установлен в кластере (argocd namespace)
• ArgoCD Image Updater установлен и настроен
• kustomize v5+ (или встроенный в kubectl)

---

Подготовка Harbor

1. Создайте проект

В Harbor UI создайте проект myproject (или ваше название).

2. Создайте robot-аккаунт

Harbor → myproject → Robot Accounts → New Robot Account:

• Permissions: pull + push для проекта myproject
• Запомните имя (например, robot$myproject+ci) и токен

3. Создайте секреты в Kubernetes

HARBOR_URL=harbor.example.com
HARBOR_USER=robot$myproject+ci
HARBOR_PASS=<токен-robot-аккаунта>

for NS in argocd test-tva-dev test-tva-prod; do
  kubectl create namespace "$NS" --dry-run=client -o yaml | kubectl apply -f -
  kubectl create secret docker-registry harbor-credentials \
    --namespace "$NS" \
    --docker-server="$HARBOR_URL" \
    --docker-username="$HARBOR_USER" \
    --docker-password="$HARBOR_PASS" \
    --dry-run=client -o yaml | kubectl apply -f -
done

---

Подготовка Forgejo

1. Добавьте секреты в репозиторий

Forgejo → репозиторий test-tva → Settings → Secrets → Actions:

Секрет	Значение
REGISTRY_USER	robot$myproject+ci (Harbor robot-аккаунт)
REGISTRY_PASSWORD	Токен robot-аккаунта

2. Зарегистрируйте репозиторий в ArgoCD

kubectl create secret generic repo-test-tva \
  --namespace argocd \
  --from-literal=type=git \
  --from-literal=url=https://forgejo.example.com/yourorg/test-tva.git \
  --from-literal=username=<git-пользователь> \
  --from-literal=password=<git-токен> \
  --dry-run=client -o yaml | kubectl apply -f -

kubectl label secret repo-test-tva -n argocd \
  argocd.argoproj.io/secret-type=repository

---

Структура проекта

.
├── backend/
│   ├── src/                  # Исходный код NestJS
│   ├── Dockerfile            # Multi-stage: build → production
│   └── package.json
├── frontend/
│   ├── src/                  # Исходный код React + Vite
│   ├── nginx.conf            # Прокси /api → backend
│   ├── Dockerfile            # Multi-stage: build → nginx
│   └── package.json
├── k8s/
│   ├── base/                 # Базовые манифесты
│   │   ├── backend-deployment.yaml
│   │   ├── backend-service.yaml
│   │   ├── frontend-deployment.yaml
│   │   ├── frontend-service.yaml
│   │   └── kustomization.yaml
│   └── overlays/
│       ├── dev/              # Окружение dev (1 реплика, авто-sync)
│       └── prod/             # Окружение prod (3 реплики, ручной sync)
├── argocd/
│   ├── application-dev.yaml
│   └── application-prod.yaml
└── .forgejo/
    └── workflows/
        └── ci.yaml

---

Docker-образы

Backend (NestJS)

Multi-stage сборка:

1. builder — npm ci, компиляция TypeScript
2. Production — только dist/, node_modules (prod), пользователь appuser

Порт: 3000, healthcheck: /healthz

Frontend (React + Vite)

Multi-stage сборка:

1. builder — npm ci, npm run build (Vite)
2. Production — nginx:alpine, статику из dist/, прокси /api → test-tva-backend:3000

Порт: 80, healthcheck: /

---

Kubernetes-манифесты

Базовые (k8s/base/)

Содержат Deployment и Service для backend и frontend с:

• Liveness / Readiness probes
• Resource requests и limits
• Безопасный пользователь (non-root)

Окружение dev (k8s/overlays/dev/)

• Namespace: test-tva-dev
• 1 реплика каждого компонента
• Автоматическая синхронизация через ArgoCD
• Image Updater отслеживает теги: sha-<commit> (каждый пуш в main)

Окружение prod (k8s/overlays/prod/)

• Namespace: test-tva-prod
• 3 реплики каждого компонента
• Повышенные resource limits
• Ручная синхронизация через ArgoCD
• Image Updater отслеживает теги: v1.0.0-<commit> (только semver-теги)

---

CI/CD (Forgejo Actions)

Workflow: .forgejo/workflows/ci.yaml

Триггеры

Событие	Что происходит
Push в main	Тесты → сборка → пуш образов с тегом sha-<commit>
Тег v*	Тесты → сборка → пуш образов с тегом v1.0.0-<commit>
Pull Request в main	Только тесты (без пуша образов)

Джобы

test-backend ──────┐
                   ├── build-and-push-backend → Harbor
test-frontend ─────┤
                   └── build-and-push-frontend → Harbor

Коммиты от Image Updater (содержат automatic update) не триггерят повторный билд.

Теги образов

Событие	Тег	Пример
Push в main	sha-<commit>	sha-abc1234
Git-тег v*	<tag>-<commit>	v1.0.0-abc1234
Всегда	latest	latest

---

Деплой через ArgoCD

Замените плейсхолдеры

Перед применением отредактируйте argocd/application-dev.yaml и argocd/application-prod.yaml:

# Замените на ваши значения:
repoURL: https://forgejo.example.com/yourorg/test-tva.git  # URL репозитория
harbor.example.com/myproject/test-tva-backend               # Путь к образу backend
harbor.example.com/myproject/test-tva-frontend              # Путь к образу frontend

Примените манифесты

kubectl apply -f argocd/application-dev.yaml
kubectl apply -f argocd/application-prod.yaml

Проверьте статус

kubectl get applications -n argocd
argocd app get test-tva-dev
argocd app get test-tva-prod

---

Работа пайплайна

1. Разработчик пушит в main

git push origin main

2. Forgejo Actions

• Запускает тесты backend и frontend параллельно
• Собирает Docker-образы
• Пушит в Harbor: harbor.example.com/myproject/test-tva-backend:sha-abc1234

3. ArgoCD Image Updater

• Опрашивает Harbor, видит новый тег sha-abc1234
• Обновляет образ в kustomization.yaml → делает коммит в репозиторий

4. ArgoCD

• Детектирует изменение в git
• Dev: автоматически синхронизирует
• Prod: ожидает ручного подтверждения в ArgoCD UI

5. Kubernetes

Rolling update подов в соответствующих namespaces.

---

Промоушен в прод

После проверки в dev:

git tag v1.0.0
git push origin v1.0.0

CI соберет образы v1.0.0-<commit>, Image Updater подхватит тег и обновит prod-окружение.

---

Операции

Ручной деплой

# Dev (авто)
kubectl rollout restart deployment/test-tva-backend -n test-tva-dev
kubectl rollout restart deployment/test-tva-frontend -n test-tva-dev

# Prod
kubectl rollout restart deployment/test-tva-backend -n test-tva-prod
kubectl rollout restart deployment/test-tva-frontend -n test-tva-prod

Проверка статуса подов

kubectl get pods -n test-tva-dev
kubectl get pods -n test-tva-prod

Логи

kubectl logs -f deployment/test-tva-backend -n test-tva-dev
kubectl logs -f deployment/test-tva-frontend -n test-tva-dev

Откат

kubectl rollout undo deployment/test-tva-backend -n test-tva-prod

Пересборка образов

При необходимости принудительной пересборки:

1. Сделайте пустой коммит: git commit --allow-empty -m "trigger rebuild"
2. Запушьте: git push origin main