auto-stock/deploy/NAS-SETUP-GUIDE.md

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 디렉토리 생성

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 설치

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 설치

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에서 배포 디렉토리 접근)

초기 비밀번호 확인:

docker exec jenkins cat /var/jenkins_home/secrets/initialAdminPassword

2.4 Jenkins 컨테이너 내부 도구 설치

Python3 + rsync + curl:

docker exec -u root jenkins bash -c "apt-get update && apt-get install -y python3 rsync curl"

• systemd 관련 에러 발생하지만 무시 가능 (Python3는 정상 설치됨)

Docker CLI (바이너리 직접 설치):

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 (독립 바이너리):

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 소켓 권한:

docker exec -u root jenkins bash -c "chmod 666 /var/run/docker.sock"

2.5 설치 검증

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 설정

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 파일을 수동 생성하고 비밀번호를 설정:

# 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 부재로 실패할 경우:

cd /volume1/docker/autostock
# .env 파일이 준비된 상태에서
docker-compose up -d

---

7. 트러블슈팅

에러: python3: not found

원인: Jenkins 컨테이너에 Python 미설치 해결:

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 바이너리 직접 설치

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에서 독립 바이너리 직접 다운로드

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

원인: 이전 설정 데이터가 꼬진 상태 해결:

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 사용

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가 유지됩니다 (볼륨 아님, 컨테이너 레이어에 저장). 단, 컨테이너를 삭제 후 재생성하면 재설치 필요:

# 전체 재설치 (컨테이너 삭제 후 재생성 시)
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