hyungi/hyungi_document_server
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: rewrite all documentation for v2 architecture

Browse Source 
- CLAUDE.md: FastAPI + Docker 기반으로 전면 재작성
- README.md: v2 기술 스택 및 Quick Start
- deploy.md: Docker Compose 배포 가이드 (launchd 제거)
- development-stages.md: Phase 0~5 개발 단계 (claude-code-commands.md 대체)
- architecture-v2.md → architecture.md 승격

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Hyungi Ahn
2026-04-02 09:39:36 +09:00
parent e48b6a2bb4
commit b338e6e424
6 changed files with 422 additions and 483 deletions
Download Patch File Download Diff File Expand all files Collapse all files

184
docs/deploy.md
View File

@@ -1,96 +1,154 @@
# Mac mini 배포 가이드
# 배포 가이드
## 1. 초기 설치
## 1. 사전 요구사항
- Docker & Docker Compose (Mac mini)
- NAS SMB 마운트 (`/Volumes/Document_Server`)
- Tailscale VPN 연결 (Mac mini ↔ GPU 서버 ↔ NAS)
## 2. Mac mini 배포
### 2-1. 코드 가져오기
```bash
# Mac mini에서
cd ~/Documents/code/
git clone https://git.hyungi.net/hyungi/devonthink_home.git "DEVONThink_my server"
cd "DEVONThink_my server"
# Python 가상환경
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
git clone https://git.hyungi.net/hyungi/hyungi_document_server.git hyungi_Document_Server
cd hyungi_Document_Server
```
## 2. 인증 정보 설정
### 2-2. 인증 정보 설정
```bash
mkdir -p ~/.config/pkm
nano ~/.config/pkm/credentials.env
chmod 600 ~/.config/pkm/credentials.env
cp credentials.env.example credentials.env
nano credentials.env # 실제 값 입력
chmod 600 credentials.env
```
credentials.env.example을 참고하여 실제 값 입력.
필수 값: `POSTGRES_PASSWORD`, `JWT_SECRET`, `TOTP_SECRET`, `MLX_ENDPOINT`
선택 값: `CLAUDE_API_KEY`, `LAW_OC` (법령 API 승인 후)
## 3. launchd 스케줄 등록
### 2-3. NAS SMB 마운트 확인
```bash
# 심볼릭 링크 생성
ln -sf ~/Documents/code/DEVONThink_my\ server/launchd/net.hyungi.pkm.law-monitor.plist ~/Library/LaunchAgents/
ln -sf ~/Documents/code/DEVONThink_my\ server/launchd/net.hyungi.pkm.mailplus.plist ~/Library/LaunchAgents/
ln -sf ~/Documents/code/DEVONThink_my\ server/launchd/net.hyungi.pkm.daily-digest.plist ~/Library/LaunchAgents/
# 등록
launchctl load ~/Library/LaunchAgents/net.hyungi.pkm.law-monitor.plist
launchctl load ~/Library/LaunchAgents/net.hyungi.pkm.mailplus.plist
launchctl load ~/Library/LaunchAgents/net.hyungi.pkm.daily-digest.plist
# macOS에서 SMB 마운트 (Finder 또는 CLI)
mount -t smbfs //hyungi@ds1525.hyungi.net/Document_Server /Volumes/Document_Server
# 확인
launchctl list | grep pkm
ls /Volumes/Document_Server/PKM/
```
## 4. 수동 테스트
Docker 컨테이너에서 이 경로를 `/documents`로 바인드 마운트한다.
### 2-4. 서비스 시작
```bash
cd ~/Documents/code/DEVONThink_my\ server/
source venv/bin/activate
docker compose up -d
# 각 스크립트 수동 실행
python3 scripts/law_monitor.py
python3 scripts/mailplus_archive.py
python3 scripts/pkm_daily_digest.py
# 상태 확인
docker compose ps
docker compose logs -f fastapi
```
## 5. DEVONthink Smart Rule 설정
1. DEVONthink → Preferences → Smart Rules
2. 새 Rule: "AI Auto Classify"
- Event: On Import
- Database: Inbox
- Condition: Tags is empty
- Action: Execute Script → External → `applescript/auto_classify.scpt`
3. 새 Rule: "OmniFocus Sync"
- Event: On Import
- Database: Projects
- Action: Execute Script → External → `applescript/omnifocus_sync.scpt`
## 6. 업데이트
### 2-5. 확인
```bash
cd ~/Documents/code/DEVONThink_my\ server/
# FastAPI OpenAPI 문서
curl http://localhost:8000/docs
# PostgreSQL 테이블 확인
docker compose exec postgres psql -U pkm -d pkm -c '\dt'
# kordoc 헬스체크
curl http://localhost:3100/health
```
### 2-6. 외부 접근 (Caddy)
Caddy가 자동으로 HTTPS 인증서를 발급한다.
- `pkm.hyungi.net` → FastAPI (:8000)
- `office.hyungi.net` → Synology Office (NAS 프록시)
DNS 레코드가 Mac mini의 공인 IP를 가리켜야 한다.
## 3. GPU 서버 배포
### 3-1. AI Gateway + Ollama
```bash
cd ~/Documents/code/hyungi_Document_Server/gpu-server/
cp ../credentials.env .env # 필요한 값만 복사
docker compose up -d
```
### 3-2. 모델 확인
```bash
# Ollama 모델 목록
docker compose exec ollama ollama list
# 필요 모델 pull
docker compose exec ollama ollama pull nomic-embed-text
docker compose exec ollama ollama pull qwen2.5-vl:7b
docker compose exec ollama ollama pull bge-reranker-v2-m3
```
### 3-3. AI Gateway 확인
```bash
curl http://localhost:8080/health
```
## 4. 업데이트
```bash
# Mac mini
cd ~/Documents/code/hyungi_Document_Server/
git pull
source venv/bin/activate
pip install -r requirements.txt
docker compose up -d --build
# GPU 서버
cd ~/Documents/code/hyungi_Document_Server/gpu-server/
git pull
docker compose up -d --build
```
## 7. 로그 확인
## 5. 로그 확인
```bash
# 스크립트 로그
tail -f logs/law_monitor.log
tail -f logs/mailplus.log
tail -f logs/digest.log
# FastAPI 로그
docker compose logs -f fastapi
# launchd 로그
tail -f logs/law_monitor_launchd.log
# 특정 워커 로그
docker compose logs -f fastapi | grep law_monitor
docker compose logs -f fastapi | grep mailplus
docker compose logs -f fastapi | grep digest
# PostgreSQL 로그
docker compose logs -f postgres
```
## 실행 스케줄
## 6. 자동화 스케줄 (APScheduler)
| 스크립트 | 시간 | 용도 |
|---------|------|------|
| law_monitor.py | 매일 07:00 | 법령 변경 모니터링 |
| mailplus_archive.py | 매일 07:00, 18:00 | 이메일 수집 |
| pkm_daily_digest.py | 매일 20:00 | 일일 다이제스트 |
Docker 내부에서 APScheduler로 관리 (launchd 대체):
| 시간 | 작업 | 주기 |
|------|------|------|
| 07:00 | law_monitor | 매일 |
| 07:00, 18:00 | mailplus_archive | 매일 2회 |
| 20:00 | daily_digest | 매일 |
| */5분 | file_watcher | 상시 |
| */10분 | processing_queue consumer | 상시 |
## 7. 백업
### 우선순위
1. **NAS 원본 파일** — Synology Drive 버전 이력 + Hyper Backup
2. **PostgreSQL** — `pg_dump` 정기 백업
3. **Docker volumes** — pgdata, caddy_data
### PostgreSQL 백업
```bash
docker compose exec postgres pg_dump -U pkm pkm > backup_$(date +%Y%m%d).sql
```