Add Maia chess gameplay and deployment
This commit is contained in:
박원엽
@@ -1,33 +1,43 @@
|
||||
# CI/CD 운영 메모
|
||||
|
||||
이 저장소는 Gitea Actions 기준으로 `main` 브랜치에 push되면 자동 배포되도록 구성한다.
|
||||
현재 운영 서버는 Docker Compose가 아니라 Java 21 + systemd 방식으로 실행 중이다.
|
||||
이 저장소는 Gitea Actions 기준으로 `main` 브랜치에 push되면 백엔드와 Maia3 체스 엔진 브리지를 함께 자동 배포하도록 구성되어 있다.
|
||||
|
||||
## 현재 운영 방식
|
||||
|
||||
- 운영 서비스: `blog-api.service`
|
||||
- 실행 디렉터리: `/root/blog-backend`
|
||||
- 실행 파일: `/root/blog-backend/blog-backend.jar`
|
||||
- 실행 방식: `java -jar -Duser.timezone=Asia/Seoul -Dspring.profiles.active=prod blog-backend.jar`
|
||||
- 운영 환경 변수와 외부 DB/Redis/S3 설정은 systemd service에 등록되어 있다.
|
||||
- 백엔드 서비스: `blog-api.service`
|
||||
- 백엔드 실행 디렉터리: `/root/blog-backend`
|
||||
- 백엔드 실행 파일: `/root/blog-backend/blog-backend.jar`
|
||||
- 백엔드 실행 방식: `java -jar -Duser.timezone=Asia/Seoul -Dspring.profiles.active=prod blog-backend.jar`
|
||||
- Maia 엔진 서비스: `maia-engine.service`
|
||||
- Maia 엔진 실행 디렉터리: `/root/blog-backend/maia-engine`
|
||||
- Maia 엔진 venv: `/root/blog-backend/maia-engine-venv`
|
||||
- Maia 엔진 URL: `http://127.0.0.1:8000`
|
||||
|
||||
## 동작 흐름
|
||||
백엔드는 기본값으로 `MAIA_ENGINE_URL=http://localhost:8000`을 사용하므로, Maia 엔진을 같은 서버에서 띄우면 별도 환경변수 없이 연동된다.
|
||||
|
||||
## 배포 흐름
|
||||
|
||||
1. `main` 브랜치 push 또는 수동 실행(`workflow_dispatch`)
|
||||
2. Java 21로 `./gradlew test --no-daemon` 실행
|
||||
3. 테스트 성공 시 `./gradlew clean bootJar -x test --no-daemon`으로 Spring Boot jar 빌드
|
||||
4. 빌드된 jar를 SSH/SCP로 서버의 `/tmp/blog-backend.jar.new`에 업로드
|
||||
5. 서버에서 기존 `/root/blog-backend/blog-backend.jar`를 timestamp 백업
|
||||
6. 새 jar를 `/root/blog-backend/blog-backend.jar`로 교체
|
||||
7. `systemctl restart blog-api.service` 실행 후 active 상태 확인
|
||||
8. 재시작 실패 또는 비정상 종료 시 직전 jar로 rollback 시도
|
||||
3. Python 3.11로 `maia-engine/app/main.py` 문법 검사
|
||||
4. 테스트 성공 시 `./gradlew clean bootJar -x test --no-daemon`으로 Spring Boot jar 빌드
|
||||
5. `maia-engine` 디렉터리를 tar로 패키징
|
||||
6. jar, Maia 엔진 tar, `deploy/systemd/maia-engine.service`를 SSH/SCP로 서버에 업로드
|
||||
7. 서버에서 Maia 엔진 코드를 `/root/blog-backend/maia-engine`으로 교체
|
||||
8. `/root/blog-backend/maia-engine-venv`를 생성하거나 재사용
|
||||
9. `requirements.txt` 해시가 바뀌었으면 Python 의존성 재설치
|
||||
10. `maia-engine.service` 설치, `systemctl daemon-reload`, enable, restart
|
||||
11. `http://127.0.0.1:8000/health` 헬스체크
|
||||
12. Spring Boot jar를 `/root/blog-backend/blog-backend.jar`로 교체
|
||||
13. `blog-api.service` 재시작 후 active 상태 확인
|
||||
|
||||
Maia 엔진 배포 실패 시 이전 Maia 코드 디렉터리로 롤백을 시도한다. 백엔드 jar 재시작 실패 시 직전 jar 백업으로 롤백을 시도한다.
|
||||
|
||||
## Gitea Actions 준비
|
||||
|
||||
- Repository Settings에서 Actions를 활성화한다.
|
||||
- Repository Settings에서 Actions가 활성화되어 있어야 한다.
|
||||
- Gitea Runner가 `ubuntu-latest` label을 처리할 수 있어야 한다.
|
||||
- 현재 백엔드 서버에는 `blog-backend` runner가 `ubuntu-latest` label로 등록되어 있다.
|
||||
- Docker는 runner job 실행에 쓰일 수 있지만, 애플리케이션 배포 방식은 systemd jar 교체 방식이다.
|
||||
- `actions/checkout`, `actions/setup-java`, `actions/setup-python` 액션을 사용할 수 있어야 한다.
|
||||
|
||||
## Repository Secrets
|
||||
|
||||
@@ -36,14 +46,38 @@ Gitea repository secrets에 다음 값을 등록한다.
|
||||
| 이름 | 설명 |
|
||||
| --- | --- |
|
||||
| `DEPLOY_HOST` | 배포 서버 호스트 또는 IP |
|
||||
| `DEPLOY_PORT` | SSH 포트, 비우면 22 |
|
||||
| `DEPLOY_PORT` | SSH 포트. 비우면 22 |
|
||||
| `DEPLOY_USER` | 배포 서버 SSH 사용자 |
|
||||
| `DEPLOY_KEY` | 배포 서버 접속용 private key |
|
||||
|
||||
## 서버 준비 사항
|
||||
|
||||
- 서버에는 Java 21이 설치되어 있어야 한다.
|
||||
- `blog-api.service`가 `/root/blog-backend/blog-backend.jar`를 실행하도록 구성되어 있어야 한다.
|
||||
- `DEPLOY_USER`는 `/root/blog-backend`에 jar를 쓸 수 있고 `systemctl restart blog-api.service`를 실행할 수 있어야 한다.
|
||||
- 운영 DB는 배포 전에 백업하는 것을 권장한다. Flyway migration은 애플리케이션 시작 시 자동 적용된다.
|
||||
- `docker-compose.yml`은 현재 CI/CD 배포 경로에서 사용하지 않는다.
|
||||
서버에는 다음이 필요하다.
|
||||
|
||||
- Java 21
|
||||
- systemd
|
||||
- Python 3.11 또는 Python 3
|
||||
- Python venv 모듈(`python3-venv` 계열 패키지)
|
||||
- `git`
|
||||
- `sha256sum`
|
||||
- `tar`
|
||||
- 외부 네트워크 접근. `requirements.txt`가 `git+https://github.com/CSSLab/maia3.git`를 설치한다.
|
||||
- `DEPLOY_USER`가 `/root/blog-backend`에 쓸 수 있고 `/etc/systemd/system`에 서비스 파일을 설치하며 `systemctl`을 실행할 수 있어야 한다.
|
||||
|
||||
첫 설치 또는 Maia3 의존성 변경 시 Python 패키지 설치와 모델 캐시 준비 때문에 배포가 오래 걸릴 수 있다. 모델 캐시는 `/root/blog-backend/.cache/huggingface`에 저장된다.
|
||||
|
||||
## 체스 배포 확인
|
||||
|
||||
배포 후 서버에서 다음을 확인할 수 있다.
|
||||
|
||||
```bash
|
||||
systemctl status maia-engine.service
|
||||
curl -fsS http://127.0.0.1:8000/health
|
||||
systemctl status blog-api.service
|
||||
```
|
||||
|
||||
백엔드 체스 API는 로그인한 사용자만 사용할 수 있다. 퍼즐 API(`/api/chess-puzzles/**`)는 비로그인 접근이 유지된다.
|
||||
|
||||
## Docker Compose
|
||||
|
||||
`docker-compose.yml`에도 Maia 엔진 서비스가 정의되어 있지만, 현재 CI/CD 경로는 Docker Compose가 아니라 systemd 기반 jar + Maia systemd 서비스 배포를 사용한다.
|
||||
|
||||
Reference in New Issue
Block a user