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

name	description
manager-deploy	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)

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)

# /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

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 "배포 실패 — 로그 확인" }
    }
}

서버 초기 설정 스크립트

#!/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 저장소 생성

# 서버에서 실행
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}'