배포스크립트
This commit is contained in:
274
deploy/NAS-SETUP-GUIDE.md
Normal file
274
deploy/NAS-SETUP-GUIDE.md
Normal file
@@ -0,0 +1,274 @@
|
||||
# Auto-Stock NAS 배포 가이드 (Synology DS1517)
|
||||
|
||||
## 환경 정보
|
||||
- NAS: Synology DS1517+ (16GB RAM)
|
||||
- OS: DSM 7.x (Linux 3.10.108, x86_64)
|
||||
- Docker: 24.0.2
|
||||
- Docker Compose: v2.20.1 (호스트) / v2.20.3 (Jenkins 내부)
|
||||
- Cloudflare Tunnel 사용 중
|
||||
|
||||
---
|
||||
|
||||
## 1. 디렉토리 구조
|
||||
|
||||
```
|
||||
/volume1/docker/
|
||||
├── autostock/ # 앱 배포 디렉토리
|
||||
│ ├── .env # 환경변수 (Git에 없음, 수동 관리)
|
||||
│ ├── docker-compose.yml
|
||||
│ ├── docker/
|
||||
│ ├── backend/
|
||||
│ ├── mcp-server/
|
||||
│ ├── frontend/
|
||||
│ ├── logs/
|
||||
│ └── backups/
|
||||
├── gitea/ # Gitea 데이터
|
||||
├── jenkins/ # Jenkins 데이터
|
||||
└── cicd/ # CI/CD 인프라 설정
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. 초기 설정
|
||||
|
||||
### 2.1 디렉토리 생성
|
||||
```bash
|
||||
sudo mkdir -p /volume1/docker/autostock
|
||||
sudo mkdir -p /volume1/docker/gitea
|
||||
sudo mkdir -p /volume1/docker/jenkins
|
||||
sudo chown -R shuim:users /volume1/docker/autostock /volume1/docker/gitea
|
||||
sudo chown -R 1000:1000 /volume1/docker/jenkins
|
||||
```
|
||||
|
||||
### 2.2 Gitea 설치
|
||||
```bash
|
||||
docker run -d --name gitea --restart unless-stopped -p 23000:3000 -v /volume1/docker/gitea:/data -e TZ=Asia/Seoul -e "GITEA__server__ROOT_URL=https://gitea.shium.net" gitea/gitea:latest
|
||||
```
|
||||
|
||||
- Cloudflare Tunnel: `gitea.shium.net:443 → localhost:23000`
|
||||
- 초기 설정: https://gitea.shium.net 접속 → SQLite3 선택 → 관리자 생성
|
||||
- 저장소 생성: `auto-stock` (Private)
|
||||
|
||||
### 2.3 Jenkins 설치
|
||||
|
||||
```bash
|
||||
docker run -d --name jenkins --restart unless-stopped -p 21080:8080 -p 21000:50000 -v /volume1/docker/jenkins:/var/jenkins_home -v /var/run/docker.sock:/var/run/docker.sock -v /volume1/docker/autostock:/volume1/docker/autostock -e TZ=Asia/Seoul -e JAVA_OPTS="-Xmx512m -Xms256m" --user root jenkins/jenkins:lts-jdk17
|
||||
```
|
||||
|
||||
**중요**: `-v /volume1/docker/autostock:/volume1/docker/autostock` 마운트 필수 (Jenkins에서 배포 디렉토리 접근)
|
||||
|
||||
초기 비밀번호 확인:
|
||||
```bash
|
||||
docker exec jenkins cat /var/jenkins_home/secrets/initialAdminPassword
|
||||
```
|
||||
|
||||
### 2.4 Jenkins 컨테이너 내부 도구 설치
|
||||
|
||||
**Python3 + rsync + curl:**
|
||||
```bash
|
||||
docker exec -u root jenkins bash -c "apt-get update && apt-get install -y python3 rsync curl"
|
||||
```
|
||||
- `systemd` 관련 에러 발생하지만 무시 가능 (Python3는 정상 설치됨)
|
||||
|
||||
**Docker CLI (바이너리 직접 설치):**
|
||||
```bash
|
||||
docker exec -u root jenkins bash -c "curl -fsSL https://download.docker.com/linux/static/stable/x86_64/docker-24.0.7.tgz -o /tmp/docker.tgz && tar xz -C /tmp -f /tmp/docker.tgz && cp /tmp/docker/docker /usr/local/bin/docker && chmod +x /usr/local/bin/docker && rm -rf /tmp/docker /tmp/docker.tgz && docker --version"
|
||||
```
|
||||
- `docker.io` apt 패키지는 Synology 커널과 호환되지 않음 (systemd 의존성 충돌)
|
||||
- 바이너리 직접 설치로 해결
|
||||
|
||||
**Docker Compose (독립 바이너리):**
|
||||
```bash
|
||||
docker exec -u root jenkins bash -c "curl -fsSL -o /tmp/dc https://github.com/docker/compose/releases/download/v2.20.3/docker-compose-linux-x86_64 && mv /tmp/dc /usr/local/bin/docker-compose && chmod +x /usr/local/bin/docker-compose && docker-compose version"
|
||||
```
|
||||
- NAS 호스트의 `docker-compose`를 `docker cp`로 복사하면 GLIBC 버전 불일치 발생
|
||||
- GitHub에서 독립 바이너리 다운로드로 해결
|
||||
- `curl -o /usr/local/bin/docker-compose` 직접 쓰면 `client returned ERROR on write` 발생 → `/tmp/dc`에 먼저 받고 `mv`로 해결
|
||||
|
||||
**Docker 소켓 권한:**
|
||||
```bash
|
||||
docker exec -u root jenkins bash -c "chmod 666 /var/run/docker.sock"
|
||||
```
|
||||
|
||||
### 2.5 설치 검증
|
||||
```bash
|
||||
docker exec jenkins bash -c "python3 --version && docker --version && docker-compose version"
|
||||
```
|
||||
예상 출력:
|
||||
```
|
||||
Python 3.13.x
|
||||
Docker version 24.0.7, build afdd53b
|
||||
Docker Compose version v2.20.3
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. Jenkins 파이프라인 설정
|
||||
|
||||
### 3.1 Pipeline 프로젝트 생성
|
||||
1. Jenkins 대시보드 → **+ 새로운 Item**
|
||||
2. 이름: `auto-stock`, 타입: **Pipeline** → OK
|
||||
|
||||
### 3.2 Pipeline 설정 (구성 페이지)
|
||||
1. Pipeline 섹션 → Definition: **Pipeline script from SCM**
|
||||
2. SCM: **Git**
|
||||
3. Repository URL: `https://gitea.shium.net/shuim/auto-stock.git`
|
||||
4. Credentials: **Add** → Username/Password (Gitea 계정)
|
||||
5. Branch: `*/main`
|
||||
6. Script Path: `Jenkinsfile`
|
||||
7. **Lightweight checkout: 반드시 체크 해제** (체크 시 `fatal: not in a git directory` 에러)
|
||||
8. 저장
|
||||
|
||||
### 3.3 Gitea Webhook (자동 빌드)
|
||||
Gitea 저장소 → Settings → Webhooks → Add Webhook:
|
||||
- URL: `http://localhost:21080/gitea-webhook/post`
|
||||
- Content Type: `application/json`
|
||||
- Trigger: Push Events
|
||||
|
||||
---
|
||||
|
||||
## 4. 로컬 Git 설정
|
||||
|
||||
```bash
|
||||
cd /Users/commylife/myproject/java/workspace/auto-stock
|
||||
git remote add nas https://gitea.shium.net/shuim/auto-stock.git
|
||||
git push nas main
|
||||
```
|
||||
|
||||
배포 흐름:
|
||||
```
|
||||
로컬 코드 수정 → git push nas main → Jenkins 자동 빌드 → NAS 배포
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. .env 설정
|
||||
|
||||
`/volume1/docker/autostock/.env` 파일을 수동 생성하고 비밀번호를 설정:
|
||||
|
||||
```bash
|
||||
# NAS SSH 접속 후
|
||||
nano /volume1/docker/autostock/.env
|
||||
```
|
||||
|
||||
필수 변경 항목:
|
||||
- `POSTGRES_PASSWORD`: 강력한 비밀번호
|
||||
- `REDIS_PASSWORD`: 강력한 비밀번호
|
||||
- `SECRET_KEY`: 64자 이상 랜덤 문자열
|
||||
- `API_KEY`, `MCP_API_KEY`: API 인증키
|
||||
- `ANTHROPIC_API_KEY`: Claude API 키
|
||||
- `KIS_*`: 한국투자증권 API 키
|
||||
- `TELEGRAM_BOT_TOKEN`, `TELEGRAM_CHAT_ID`: 텔레그램 알림
|
||||
|
||||
---
|
||||
|
||||
## 6. 수동 첫 배포
|
||||
|
||||
Jenkins 파이프라인이 .env 부재로 실패할 경우:
|
||||
|
||||
```bash
|
||||
cd /volume1/docker/autostock
|
||||
# .env 파일이 준비된 상태에서
|
||||
docker-compose up -d
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. 트러블슈팅
|
||||
|
||||
### 에러: `python3: not found`
|
||||
**원인**: Jenkins 컨테이너에 Python 미설치
|
||||
**해결**:
|
||||
```bash
|
||||
docker exec -u root jenkins bash -c "apt-get update && apt-get install -y python3"
|
||||
```
|
||||
|
||||
### 에러: `docker.io` 설치 시 systemd dpkg 에러
|
||||
**원인**: Synology 커널(3.10.108)이 최신 systemd와 호환되지 않음
|
||||
**해결**: `docker.io` 패키지 대신 Docker CLI 바이너리 직접 설치
|
||||
```bash
|
||||
docker exec -u root jenkins bash -c "curl -fsSL https://download.docker.com/linux/static/stable/x86_64/docker-24.0.7.tgz -o /tmp/docker.tgz && tar xz -C /tmp -f /tmp/docker.tgz && cp /tmp/docker/docker /usr/local/bin/docker && chmod +x /usr/local/bin/docker && rm -rf /tmp/docker /tmp/docker.tgz"
|
||||
```
|
||||
|
||||
### 에러: `unknown shorthand flag: 'f' in -f` (docker compose)
|
||||
**원인**: Jenkins 내부 Docker CLI에 `compose` 플러그인이 없음. `docker compose`(v2 플러그인)가 아닌 `docker-compose`(독립 바이너리) 사용 필요
|
||||
**해결**: docker-compose 독립 바이너리 설치 (섹션 2.4 참조)
|
||||
|
||||
### 에러: `docker-compose: not found`
|
||||
**원인**: NAS 호스트의 docker-compose를 `docker cp`로 복사하면 GLIBC 버전 불일치
|
||||
**해결**: GitHub에서 독립 바이너리 직접 다운로드
|
||||
```bash
|
||||
docker exec -u root jenkins bash -c "curl -fsSL -o /tmp/dc https://github.com/docker/compose/releases/download/v2.20.3/docker-compose-linux-x86_64 && mv /tmp/dc /usr/local/bin/docker-compose && chmod +x /usr/local/bin/docker-compose"
|
||||
```
|
||||
|
||||
### 에러: `curl: (23) client returned ERROR on write of 1369 bytes`
|
||||
**원인**: `/usr/local/bin/`에 직접 쓸 때 권한/공간 문제
|
||||
**해결**: `/tmp`에 먼저 다운로드 후 `mv`로 이동
|
||||
|
||||
### 에러: `fatal: not in a git directory`
|
||||
**원인**: Pipeline 설정에서 **Lightweight checkout**이 활성화되어 있으면 git workspace 없이 Jenkinsfile을 읽으려 함
|
||||
**해결**: Pipeline 구성 → **Lightweight checkout 체크 해제** → 저장
|
||||
|
||||
### 에러: `mkdir: cannot create directory '/volume1': Permission denied`
|
||||
**원인**: Jenkins 컨테이너에 NAS 볼륨이 마운트되지 않음
|
||||
**해결**: Jenkins 컨테이너 재생성 시 `-v /volume1/docker/autostock:/volume1/docker/autostock` 볼륨 마운트 추가
|
||||
|
||||
### 에러: Gitea 500 Internal Server Error
|
||||
**원인**: 이전 설정 데이터가 꼬진 상태
|
||||
**해결**:
|
||||
```bash
|
||||
docker rm -f gitea
|
||||
sudo rm -rf /volume1/docker/gitea/*
|
||||
# 다시 docker run으로 재생성
|
||||
```
|
||||
|
||||
### 에러: `git push nas main` → `Failed to connect to port 3001`
|
||||
**원인**: Cloudflare Tunnel 사용 시 직접 포트 접근 불가
|
||||
**해결**: HTTPS URL 사용
|
||||
```bash
|
||||
git remote remove nas
|
||||
git remote add nas https://gitea.shium.net/shuim/auto-stock.git
|
||||
git push nas main
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. Jenkins 컨테이너 재시작 후 복구
|
||||
|
||||
Jenkins 컨테이너가 재시작되면 바이너리 설치된 Docker CLI와 docker-compose가 유지됩니다 (볼륨 아님, 컨테이너 레이어에 저장). 단, 컨테이너를 **삭제 후 재생성**하면 재설치 필요:
|
||||
|
||||
```bash
|
||||
# 전체 재설치 (컨테이너 삭제 후 재생성 시)
|
||||
docker exec -u root jenkins bash -c "apt-get update && apt-get install -y python3 rsync curl && curl -fsSL https://download.docker.com/linux/static/stable/x86_64/docker-24.0.7.tgz -o /tmp/docker.tgz && tar xz -C /tmp -f /tmp/docker.tgz && cp /tmp/docker/docker /usr/local/bin/docker && chmod +x /usr/local/bin/docker && rm -rf /tmp/docker /tmp/docker.tgz && curl -fsSL -o /tmp/dc https://github.com/docker/compose/releases/download/v2.20.3/docker-compose-linux-x86_64 && mv /tmp/dc /usr/local/bin/docker-compose && chmod +x /usr/local/bin/docker-compose && chmod 666 /var/run/docker.sock"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 9. 메모리 배분 (docker-compose.yml)
|
||||
|
||||
| 서비스 | 메모리 제한 |
|
||||
|--------|-----------|
|
||||
| PostgreSQL | 1GB |
|
||||
| Backend | 768MB |
|
||||
| RabbitMQ | 512MB |
|
||||
| Redis | 256MB (maxmemory 200MB) |
|
||||
| MCP Server | 256MB |
|
||||
| Frontend (Nginx) | 64MB |
|
||||
| Gitea | ~200MB |
|
||||
| Jenkins | ~1GB (빌드 시) |
|
||||
| **합계** | ~4.1GB / 16GB |
|
||||
|
||||
---
|
||||
|
||||
## 10. Cloudflare Tunnel 라우팅
|
||||
|
||||
| 도메인 | 포트 | 용도 |
|
||||
|--------|------|------|
|
||||
| gitea.shium.net:443 | localhost:23000 | Gitea (Git 웹 UI) |
|
||||
| jenkins.shium.net:443 | localhost:21080 | Jenkins (CI/CD) |
|
||||
| stock.shium.net:443 | localhost:3000 | Frontend |
|
||||
| stock.shium.net/api | localhost:8000 | Backend API |
|
||||
|
||||
---
|
||||
|
||||
*마지막 업데이트: 2026-03-27*
|
||||
Reference in New Issue
Block a user