Dokploy 서버 관리 스킬

Dokploy는 셀프호스팅 PaaS(Platform as a Service) 도구로, Docker 기반 애플리케이션 배포를 간편하게 관리합니다.

센터 프로젝트 Dokploy 설정 정보

참고: 아래 정보는 센터 프로젝트의 실제 Dokploy 설정입니다. 설정 파일 위치: .claude/skills/center-skill/scripts/config.sh

항목	값
Dokploy 서버 URL	http://209.97.169.136:3000
프로덕션 사이트	https://sonub.com
SSH 접속	root@sonub.com
애플리케이션 ID	DYmNZmKYtRG0RdNrsGcfn
PostgreSQL 호스트	209.97.169.136:5433
데이터베이스 이름	center

배포 모니터링 스크립트

# 배포 상태 실시간 모니터링
./.claude/skills/center-skill/scripts/deploy-watch.sh

# 배포 상태 및 이력 조회
./.claude/skills/center-skill/scripts/deploy-monitor.sh

# 배포 실패 시 에러 로그 확인
./.claude/skills/center-skill/scripts/deploy-error-check.sh auto

---

일반 Dokploy 서버 접속 정보

새로운 Dokploy 서버 작업 시, 반드시 사용자에게 아래 정보를 요청합니다:

변수	설명	예시
DOKPLOY_SERVER_IP	Dokploy 서버 IP	1.2.3.4
ROOT_SSH_CONNECTION	Root SSH 접속 주소	root@1.2.3.4
DOKPLOY_API_KEY	Dokploy API 키	Settings → Profile → API/CLI에서 생성

보안 원칙: 접속 정보는 메모리에만 보관하고, 파일에 저장하지 않습니다.

사용자에게 요청할 질문

Dokploy 서버 작업을 진행하기 전에 다음 정보가 필요합니다:

1. Dokploy 서버 IP 주소 (예: 1.2.3.4)
2. Root SSH 접속 주소 (예: root@1.2.3.4)
3. Dokploy API 키 (Settings → Profile → API/CLI에서 생성)

※ SSH 키 인증이 설정되어 있어야 합니다 (ssh-copy-id 완료)

---

참조 문서

작업 유형에 따라 해당 문서를 참조합니다:

작업	문서	주요 내용
API를 통한 원격 관리	api.md	Dokploy REST API, 인증, 배포 자동화
애플리케이션 관리/설정	applications.md	환경변수, 모니터링, 리소스 관리, Swarm 설정
빌드 타입 선택	build-types.md	Nixpacks, Dockerfile, Buildpack 비교
Cloudflare 도메인/SSL	cloudflare.md	Cloudflare DNS, Origin CA, 프록시 설정
traefik.me 무료 도메인	traefik-me-domain.md	테스트용 무료 도메인 (HTTP only)
볼륨 백업/복원	volume-backups.md	S3 연동, Named Volume 백업/복원
데이터베이스 관리	database.md	PostgreSQL, MySQL, MongoDB, Redis 관리
Docker Compose 관리	docker-compose.md	멀티 컨테이너 설정, 볼륨 마운트 규칙
문제 해결/디버깅	debugging.md	502 에러, 도메인 접속 문제, Traefik 로그
서버 유지보수/업데이트	maintenance.md	Dokploy 업데이트, 디스크 관리, 백업

---

빠른 참조

필수 포트 설정

프레임워크	기본 포트
Next.js / Node.js	3000
Laravel / PHP	8000
Django / Python	8000
NGINX (정적)	80

컨테이너 수신 주소

# 올바른 설정 (모든 인터페이스에서 수신)
0.0.0.0:3000

# 잘못된 설정 (외부 접근 불가)
127.0.0.1:3000

Docker Compose 볼륨 마운트

# 올바른 형식 (상대 경로)
volumes:
  - "../files/my-data:/var/lib/data"

# 잘못된 형식 (절대 경로 사용 금지)
volumes:
  - "/folder:/path/in/container"

---

SSH 기반 작업 예시

서버 상태 확인

# Docker 컨테이너 상태 확인
ssh root@$SERVER_IP "docker ps"

# Dokploy 필수 컨테이너 확인 (4개: dokploy, postgres, redis, traefik)
ssh root@$SERVER_IP "docker ps | grep -E 'dokploy|postgres|redis|traefik'"

# 디스크 사용량 확인
ssh root@$SERVER_IP "df -h"

도메인 접속 문제 진단

# DNS 확인
dig +short example.com

# HTTP 응답 확인
curl -sI https://example.com | head -10

# Traefik 설정에서 도메인 검색
ssh root@$SERVER_IP "grep -r 'example.com' /etc/dokploy/traefik/dynamic/*.yml"

# SSL 인증서 확인
echo | openssl s_client -connect example.com:443 -servername example.com 2>/dev/null | openssl x509 -noout -dates

컨테이너 로그 확인

# Traefik 로그
ssh root@$SERVER_IP "docker logs dokploy-traefik --tail 100"

# 특정 서비스 로그
ssh root@$SERVER_IP "docker service logs <service-name> --tail 100"

Docker 재시작

# Traefik만 재시작
ssh root@$SERVER_IP "docker restart dokploy-traefik"

# Dokploy 전체 재시작
ssh root@$SERVER_IP "docker service update --force dokploy"

---

API 기반 작업 예시

프로젝트/애플리케이션 조회

# 모든 프로젝트 조회
curl -X GET "http://$SERVER_IP:3000/api/project.all" \
  -H "x-api-key: $API_KEY"

# 특정 애플리케이션 조회
curl -X GET "http://$SERVER_IP:3000/api/application.one?applicationId=$APP_ID" \
  -H "x-api-key: $API_KEY"

애플리케이션 재배포

curl -X POST "http://$SERVER_IP:3000/api/application.redeploy" \
  -H "Content-Type: application/json" \
  -H "x-api-key: $API_KEY" \
  -d "{\"applicationId\": \"$APP_ID\"}"

상세한 API 사용법은 api.md 참조.

---

문제 해결 순서

1. 포트 확인: 앱이 올바른 포트에서 실행 중인지
2. 수신 주소 확인: 0.0.0.0에서 수신 대기하는지
3. DNS 확인: 도메인이 서버 IP를 가리키는지
4. 컨테이너 로그 확인: docker service logs <service-name>
5. Traefik 설정 확인: /etc/dokploy/traefik/dynamic/*.yml
6. API로 배포 상태 확인: deployment.all 엔드포인트

상세한 문제 해결 가이드는 debugging.md 참조.

---

주요 작업 워크플로우

새 애플리케이션 배포

1. 프로젝트 생성 (UI 또는 API)
2. 애플리케이션 생성 및 Git 소스 연결
3. 빌드 타입 선택 (build-types.md 참조)
4. 환경 변수 설정
5. 도메인 설정 및 SSL 인증서 발급
6. 배포 실행

도메인 설정

1. DNS 레코드 설정 (A 레코드 → 서버 IP)
2. Dokploy에서 도메인 추가
3. HTTPS 활성화 및 인증서 타입 선택
4. 접속 테스트

Cloudflare 사용 시 cloudflare.md, 테스트용 도메인은 traefik-me-domain.md 참조.

볼륨 백업 설정

1. S3 호환 스토리지 연결
2. 명명 볼륨(Named Volume) 사용 확인
3. 백업 스케줄 설정 (Cron 형식)
4. 테스트 백업 실행

상세 가이드는 volume-backups.md 참조.

---

센터 프로젝트 Docker 설정

Dockerfile 구성 (etc/docker/Dockerfile)

FROM php:8.4-fpm

# 설치 패키지:
# - nginx, libpq-dev (PostgreSQL)
# - libpng-dev, libjpeg-dev, libwebp-dev, libfreetype6-dev (GD 이미지 처리)
# - APCu (PHP 공유 메모리 캐시)

# PHP 확장:
# - pdo, pdo_pgsql (PostgreSQL PDO)
# - gd (이미지 썸네일 생성)
# - apcu (캐시)

WORKDIR /www
COPY . /www
EXPOSE 80
CMD php-fpm -D && nginx -g "daemon off;"

주요 특징:

• PHP 8.4 + FPM + Nginx 단일 컨테이너
• PostgreSQL PDO 드라이버
• GD 라이브러리 (썸네일 생성)
• APCu 캐시
• 업로드 디렉토리: /uploads (777 권한)

docker-compose.yml (로컬 개발 전용)

services:
  center:
    build:
      context: .
      dockerfile: etc/docker/Dockerfile
    ports:
      - "8080:80"
    volumes:
      - .:/www          # 소스 코드 실시간 반영
      - ./uploads:/uploads  # 업로드 파일 영구 저장

중요: Dokploy 배포 시에는 docker-compose.yml을 사용하지 않습니다. Dockerfile만 사용하여 소스 코드가 COPY됩니다.

Nginx 설정 (etc/nginx/conf.d/center.conf)

설정	값	설명
client_max_body_size	50M	최대 업로드 크기
정적 파일 캐시	365일	/uploads/* 경로
PHP 실행 방지	403	uploads 폴더 내 PHP 차단
라우팅	layout.php	모든 요청을 Front Controller로

배포 워크플로우

# 1. 테스트 실행 (Deploy + Browser 테스트)
./deploy.sh

# 2. 빌드 날짜 업데이트
npm run patch:build-date

# 3. 커밋 및 푸시
git add .
git commit -m "커밋 메시지"
git push

# 4. 배포 모니터링
./.claude/skills/center-skill/scripts/deploy-watch.sh

deploy.sh 테스트 항목:

• tests/Deploy/**/*Test.php - 배포 환경 테스트
• tests/Browser/**/*Test.php - 브라우저 테스트