Feat: [main] hufs-notice-crawler CI/CD까지 구현 완료

README.operation.md

@@ -0,0 +1,253 @@
+# 운영 문서
+
+이 문서는 `HUFS 컴퓨터공학부 공지 크롤러`의 운영과 배포 절차를 설명합니다.
+
+관련 문서:
+
+- 서비스 개요: [`README.md`](/C:/Users/USER/Desktop/notice_crawler/README.md)
+- 테스트: [`README.test.md`](/C:/Users/USER/Desktop/notice_crawler/README.test.md)
+- n8n 연동: [`README.n8n.md`](/C:/Users/USER/Desktop/notice_crawler/README.n8n.md)
+
+## PostgreSQL 준비
+
+중요:
+
+- `DB 자체는 직접 만들어야 합니다.`
+- 앱이 자동으로 생성하는 것은 `테이블`까지입니다.
+- 즉 `DATABASE_URL`로 접속할 데이터베이스는 미리 존재해야 합니다.
+
+예:
+
+```sql
+CREATE DATABASE hufs_notice_crawler;
+```
+
+필요하면 사용자와 권한도 준비합니다.
+
+```sql
+CREATE USER crawler_user WITH PASSWORD 'your-password';
+GRANT ALL PRIVILEGES ON DATABASE hufs_notice_crawler TO crawler_user;
+```
+
+## 호스트에서 Postgres 컨테이너로 DB 생성
+
+컨테이너 이름 확인:
+
+```bash
+docker ps
+```
+
+예를 들어 PostgreSQL 컨테이너 이름이 `postgres`라면:
+
+### 1. DB 생성
+
+```bash
+docker exec -it postgres psql -U postgres -d postgres -c "CREATE DATABASE hufs_notice_crawler;"
+```
+
+### 2. 사용자 생성
+
+```bash
+docker exec -it postgres psql -U postgres -d postgres -c "CREATE USER crawler_user WITH PASSWORD 'your-password';"
+```
+
+### 3. 권한 부여
+
+```bash
+docker exec -it postgres psql -U postgres -d postgres -c "GRANT ALL PRIVILEGES ON DATABASE hufs_notice_crawler TO crawler_user;"
+```
+
+### 4. 확인
+
+DB 목록:
+
+```bash
+docker exec -it postgres psql -U postgres -d postgres -c "\\l"
+```
+
+특정 DB 접속:
+
+```bash
+docker exec -it postgres psql -U postgres -d hufs_notice_crawler -c "\\dt"
+```
+
+처음에는 `\dt` 결과에 테이블이 없어도 정상입니다. 앱이 시작되면 필요한 테이블을 자동 생성합니다.
+
+## 스키마 적용
+
+스키마 파일:
+
+- [`sql/schema.sql`](/C:/Users/USER/Desktop/notice_crawler/sql/schema.sql)
+
+직접 적용하려면:
+
+```bash
+psql -h <POSTGRES_HOST> -U <POSTGRES_USER> -d <POSTGRES_DB> -f sql/schema.sql
+```
+
+정리:
+
+- DB가 아직 없으면 먼저 `CREATE DATABASE`
+- DB는 있고 테이블을 수동 생성하고 싶으면 `schema.sql` 적용
+- DB는 있고 앱이 자동 생성하게 둘 거면 `schema.sql` 생략 가능
+
+## bootstrap mode 운영 의미
+
+이 서비스는 최초 실행 시 `scraped_posts` 테이블이 비어 있으면 `bootstrap mode`로 동작합니다.
+
+판단 기준:
+
+- `scraped_posts`에 행이 0개
+  - `bootstrap_mode = true`
+- `scraped_posts`에 행이 1개 이상
+  - `bootstrap_mode = false`
+
+bootstrap 동작:
+
+- 기존 글을 저장만 함
+- `new_posts_count = 0`
+- `new_posts = []`
+- `latest_posts_by_board`는 `new_posts_count == 0`일 때만 포함
+
+주의:
+
+- `scraped_posts`를 전부 비우면 다음 호출은 다시 bootstrap 모드가 됩니다.
+
+## Docker 이미지 빌드
+
+```bash
+docker build -t your-dockerhub-id/hufs-notice-crawler:latest .
+```
+
+버전 태그와 같이 빌드:
+
+```bash
+docker build -t your-dockerhub-id/hufs-notice-crawler:1.0.0 -t your-dockerhub-id/hufs-notice-crawler:latest .
+```
+
+## Docker Hub 로그인 및 push
+
+로그인:
+
+```bash
+docker login
+```
+
+push:
+
+```bash
+docker push your-dockerhub-id/hufs-notice-crawler:1.0.0
+docker push your-dockerhub-id/hufs-notice-crawler:latest
+```
+
+## 서버 배포
+
+이 프로젝트는 Docker Hub 이미지를 `pull`해서 실행하는 구조입니다.
+
+### 1. `.env` 준비
+
+```env
+APP_ENV=production
+DB_USER=postgres
+DB_PASSWORD=postgres
+POSTGRES_HOST=postgres
+POSTGRES_PORT=5432
+POSTGRES_DB=hufs_notice_crawler
+BASE_URL=https://computer.hufs.ac.kr
+REQUEST_TIMEOUT_SECONDS=15
+MAX_PAGES_PER_BOARD=5
+DOCKER_IMAGE=your-dockerhub-id/hufs-notice-crawler:latest
+```
+
+### 2. `docker-compose.yml` 확인
+
+[`docker-compose.yml`](/C:/Users/USER/Desktop/notice_crawler/docker-compose.yml) 은 `build`가 아니라 `image pull` 기반입니다.
+
+핵심 구조:
+
+```yaml
+name: nkeys-apps
+
+services:
+  hufs-notice-crawler:
+    image: ${DOCKER_IMAGE}
+    env_file:
+      - .env
+    environment:
+      - DATABASE_URL=postgresql+psycopg://${DB_USER}:${DB_PASSWORD}@${POSTGRES_HOST}:${POSTGRES_PORT}/${POSTGRES_DB}
+    networks:
+      - nkeysworld-network
+      - obs
+```
+
+포인트:
+
+- `name: nkeys-apps`
+- 외부 네트워크 `nkeysworld-network`, `obs` 사용
+- `ports:` 없음
+- 같은 Docker network 내부 통신 전제
+
+### 3. pull 및 실행
+
+```bash
+docker compose pull
+docker compose up -d
+```
+
+업데이트 배포도 동일합니다.
+
+## 내부 호출 URL
+
+같은 Docker network 내부에서 직접 호출:
+
+```text
+http://hufs-notice-crawler:8000/api/v1/crawl
+```
+
+헬스체크:
+
+```text
+http://hufs-notice-crawler:8000/health
+```
+
+## nginx reverse proxy
+
+nginx를 통해 외부에 노출할 경우 예시는 아래와 같습니다.
+
+```nginx
+location /api/hufs/ {
+    set $hufs_up http://hufs-notice-crawler:8000;
+
+    rewrite ^/api/hufs/crawl$ /api/v1/crawl break;
+    rewrite ^/api/hufs/health$ /health break;
+
+    proxy_pass $hufs_up;
+
+    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_set_header X-Forwarded-Proto $scheme;
+
+    proxy_read_timeout 120;
+    proxy_send_timeout 120;
+}
+```
+
+외부 호출 URL:
+
+- `POST https://nkeystudy.site/api/hufs/crawl`
+- `GET https://nkeystudy.site/api/hufs/health`
+
+주의:
+
+- nginx 컨테이너도 `hufs-notice-crawler`와 같은 Docker network에 연결되어 있어야 합니다.
+- 같은 network 내부에서만 통신할 거면 `ports:`는 열 필요가 없습니다.
+
+## 로컬 개발 실행
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+uvicorn app.main:app --host 0.0.0.0 --port 8000
+```