# o2o-infrakit

aio2o의 분산된 인프라 서비스 및 설정을 단일 프로젝트로 통합하여 구축한 범용 인프라 솔루션입니다.

## 주요 기능

- **FastAPI 애플리케이션 서버**: Gunicorn + Uvicorn ASGI 워커 기반의 비동기 Python 웹 서버
- **Nginx 리버스 프록시**: SSL/TLS 지원, 정적 파일 서빙, WebSocket 지원
- **데이터베이스**: PostgreSQL 및 MySQL(Percona) 지원
- **캐싱 및 메시지 브로커**: Redis 기반 캐싱 및 Celery 태스크 큐 지원
- **SSL 인증서 자동화**: Let's Encrypt + Certbot 자동 갱신
- **로그 관리**: 일별 로그 로테이션 및 30일 보관

## 기술 스택

| 구분 | 기술 |
|------|------|
| 언어 | Python 3.13 |
| 프레임워크 | FastAPI |
| ASGI 서버 | Gunicorn + Uvicorn |
| 웹 서버 | Nginx 1.26 |
| 데이터베이스 | PostgreSQL, MySQL (Percona) |
| 캐시/브로커 | Redis |
| 태스크 큐 | Celery + Celery Beat |
| 컨테이너 | Docker, Docker Compose |

## 디렉토리 구조

```
o2o-infrakit/
├── compose/                    # Docker Compose 설정
│   ├── docker-compose.yml      # 메인 오케스트레이션 파일
│   ├── .env                    # 환경 변수
│   ├── mysql/                  # MySQL 데이터 볼륨
│   ├── pgdata/                 # PostgreSQL 데이터 볼륨
│   ├── redis/                  # Redis 설정 및 데이터
│   └── ssl/                    # SSL 인증서 및 Let's Encrypt
│
├── config/                     # 서비스별 설정
│   ├── app-server/             # 애플리케이션 서버 설정
│   │   └── gunicorn_uvicorn.conf.py
│   ├── database/               # 데이터베이스 설정
│   │   ├── mysql/              # MySQL 설정 (my.cnf, init.sql)
│   │   └── postgresql/         # PostgreSQL 설정
│   └── web-server/             # 웹 서버 설정
│       ├── nginx_conf/         # Nginx 메인 설정
│       ├── conf.d/             # 도메인별 Nginx 설정
│       └── proxy_params/       # 프록시 헤더 설정
│
├── docker/                     # Docker 이미지
│   ├── gunicorn/               # Python 앱 서버 Dockerfile
│   └── nginx/                  # Nginx Dockerfile
│
├── script/                     # 유틸리티 스크립트
│   ├── letsencrypt.sh          # SSL 인증서 설정
│   ├── crontab_gunicorn_set.sh # Cron 작업 설정
│   └── logrotate/              # 로그 로테이션 설정
│
├── log/                        # 로그 디렉토리 (볼륨)
│   ├── mysql/                  # MySQL 로그
│   ├── nginx/                  # Nginx 액세스/에러 로그
│   ├── postgresql/             # PostgreSQL 로그
│   └── uvicorn/                # Uvicorn/FastAPI 로그
│
└── www/                        # 애플리케이션 코드 볼륨
```

## 시스템 요구사항

- **CPU**: 4코어 이상
- **RAM**: 4GB 이상
- **스토리지**: SSD 권장
- **OS**: Linux (Ubuntu 24.04 권장)
- **Docker**: 20.10 이상
- **Docker Compose**: 2.0 이상

## 빠른 시작

### 1. 환경 변수 설정

```bash
cd compose
cp .env.example .env
# .env 파일을 프로젝트에 맞게 수정
```

주요 환경 변수:
- `PROJECT_DIR`: 애플리케이션 프로젝트 디렉토리명
- `POSTGRES_DB`, `POSTGRES_USER`, `POSTGRES_PASSWORD`: PostgreSQL 접속 정보
- `CELERY_BROKER_URL`: Celery 브로커 URL

### 2. 데이터베이스 볼륨 권한 설정

```bash
cd compose
chmod +x set_mysql_permission.sh
./set_mysql_permission.sh
```

### 3. SSL 인증서 설정 (선택)

```bash
cd script
chmod +x letsencrypt.sh
./letsencrypt.sh
```

### 4. 컨테이너 실행

```bash
cd compose
docker compose up -d
```

## 서비스 구성

### Docker Compose 서비스

| 서비스 | 설명 | 포트 |
|--------|------|------|
| nginx | 리버스 프록시, SSL 종료 | 80, 443 |
| uvicorn-app | FastAPI 애플리케이션 | 8000 (내부) |
| redis | 캐시 및 메시지 브로커 | 6379 (내부) |
| postgresql | 데이터베이스 | 5432 (내부) |
| mysql | 데이터베이스 (선택) | 3306 (내부) |

### Gunicorn 설정 (config/app-server/gunicorn_uvicorn.conf.py)

- **워커 수**: 4 (4GB RAM 기준 최적화)
- **워커 타입**: Uvicorn (비동기 I/O)
- **타임아웃**: 300초 (장시간 작업 지원)
- **최대 요청**: 1000 (메모리 누수 방지)
- **바인드**: 0.0.0.0:8000

### Nginx 설정 (config/web-server/nginx_conf/nginx.conf)

- **워커 프로세스**: auto (CPU 코어 수에 맞게 자동 조정)
- **워커 연결**: 1024/프로세스
- **Keep-alive**: 30초
- **최대 요청 본문**: 50MB
- **프록시 타임아웃**: 300초

## 운영 기능

### 로그 로테이션

- **주기**: 일별
- **보관 기간**: 30일
- **최대 파일 크기**: 100MB
- **설정 위치**: `script/logrotate/`

### SSL 인증서 자동 갱신

- **주기**: 매주 월요일 오전 5시
- **방식**: Certbot + Nginx 리로드
- **설정**: Nginx Dockerfile 내 crontab

### 자동 재시작

- **주기**: 매주 월요일 오전 6시 (선택적)
- **설정 스크립트**: `script/crontab_gunicorn_set.sh`

## 주요 스크립트

| 스크립트 | 설명 |
|----------|------|
| `script/letsencrypt.sh` | Let's Encrypt SSL 인증서 발급 |
| `compose/set_mysql_permission.sh` | 데이터베이스 볼륨 권한 설정 |
| `script/crontab_gunicorn_set.sh` | 컨테이너 자동 재시작 cron 설정 |