guardia-manager/.claude/skills/manager-deploy/SKILL.md

---
name: manager-deploy
description: >
  GUARDiA Manager 자체를 서버에 배포하고 CI/CD 파이프라인을 구성하는 스킬.
  Nginx 설정, systemd 서비스 등록, Gitea 저장소 생성, Jenkinsfile 작성을 포함한다.
  트리거: Manager 배포 설정, Nginx 구성, systemd 서비스 등록, CI/CD 파이프라인,
  Gitea 저장소 생성, Jenkinsfile 작성 요청 시.
---

# GUARDiA Manager 배포 스킬

## 포트 계획

| 서비스 | 포트 | 설명 |
|--------|------|------|
| GUARDiA ITSM | 8001 | 기존 (변경 금지) |
| Spring Boot (홈페이지) | 8082 | 기존 (변경 금지) |
| Jenkins | 8080 | 기존 (변경 금지) |
| **Manager Frontend** | **8090** | Nginx 신규 |
| **Manager Backend** | **8002** | FastAPI 신규 |

## Nginx 설정 (/etc/nginx/sites-available/guardia-manager)

```nginx
server {
    listen 8090;
    server_name _;

    # React SPA
    root /var/www/manager;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
        add_header Cache-Control no-cache;
    }

    # Manager Backend API 프록시
    location /api/ {
        proxy_pass         http://127.0.0.1:8002;
        proxy_http_version 1.1;
        proxy_set_header   Host $host;
        proxy_set_header   X-Real-IP $remote_addr;
        proxy_set_header   X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_read_timeout 60s;
    }

    # GUARDiA ITSM API 프록시 (CORS 우회)
    location /guardia-api/ {
        proxy_pass         http://127.0.0.1:8001/;
        proxy_set_header   Host $host;
        proxy_set_header   X-Real-IP $remote_addr;
    }

    # 정적 파일 캐시
    location ~* \.(js|css|png|jpg|ico|svg|woff2)$ {
        expires 7d;
        add_header Cache-Control "public, immutable";
    }

    gzip on;
    gzip_types text/plain text/css application/javascript application/json;
}
```

## systemd 서비스 (Manager Backend)

```ini
# /etc/systemd/system/guardia-manager.service
[Unit]
Description=GUARDiA Manager API Backend
After=network.target guardia.service

[Service]
User=root
WorkingDirectory=/opt/manager/backend
EnvironmentFile=-/opt/manager/backend/.env
ExecStart=/opt/manager/venv/bin/uvicorn main:app --host 127.0.0.1 --port 8002 --workers 1
Restart=on-failure
RestartSec=5
StandardOutput=append:/var/log/guardia-manager/backend.log
StandardError=append:/var/log/guardia-manager/backend.log

[Install]
WantedBy=multi-user.target
```

## 배포 디렉터리 구조 (서버)

```
/opt/manager/
├── backend/             ← FastAPI 소스
│   ├── main.py
│   ├── .env
│   └── routers/
└── venv/                ← Python 가상환경

/var/www/manager/        ← React 빌드 결과물
/var/log/guardia-manager/
└── backend.log
```

## Jenkinsfile

```groovy
pipeline {
    agent any
    environment {
        DEPLOY_FRONTEND = '/var/www/manager'
        DEPLOY_BACKEND  = '/opt/manager/backend'
        VENV            = '/opt/manager/venv'
    }
    stages {
        stage('Checkout') {
            steps { checkout scm }
        }
        stage('Frontend Build') {
            steps {
                dir('frontend') {
                    sh 'npm ci --prefer-offline 2>/dev/null || npm install'
                    sh 'npm run build'
                    sh "cp -r dist/. ${DEPLOY_FRONTEND}/"
                }
            }
        }
        stage('Backend Deploy') {
            steps {
                sh """
                    cp -r backend/. ${DEPLOY_BACKEND}/
                    ${VENV}/bin/pip install -r ${DEPLOY_BACKEND}/requirements.txt -q
                    systemctl restart guardia-manager
                    sleep 3
                    systemctl is-active guardia-manager
                """
            }
        }
        stage('Health Check') {
            steps {
                sh 'curl -sf http://localhost:8002/health | grep ok'
                sh 'curl -sf http://localhost:8090/ -o /dev/null -w "HTTP %{http_code}"'
            }
        }
    }
    post {
        success { echo "Manager 배포 완료" }
        failure { echo "배포 실패 — 로그 확인" }
    }
}
```

## 서버 초기 설정 스크립트

```bash
#!/bin/bash
# deploy/init_server.sh — 최초 1회 실행

# 디렉터리 생성
mkdir -p /opt/manager/backend /var/www/manager /var/log/guardia-manager

# Python 가상환경
python3 -m venv /opt/manager/venv
/opt/manager/venv/bin/pip install -r /opt/manager/backend/requirements.txt -q

# Nginx 설정
ln -sf /etc/nginx/sites-available/guardia-manager /etc/nginx/sites-enabled/
nginx -t && systemctl reload nginx

# systemd 등록
systemctl daemon-reload
systemctl enable guardia-manager
systemctl start guardia-manager

# UFW 포트 오픈
ufw allow 8090/tcp comment 'GUARDiA Manager'
ufw allow 8002/tcp comment 'Manager Backend'

echo "Manager 초기 설정 완료"
echo "접속: http://zioinfo.co.kr:8090"
```

## Gitea 저장소 생성

```bash
# 서버에서 실행
curl -s -X POST http://localhost:3000/api/v1/user/repos \
  -H "Content-Type: application/json" \
  -u "zio:Zio@Admin2026!" \
  -d '{"name":"guardia-manager","description":"GUARDiA 관리자 시스템","private":false,"auto_init":true}'
```