Dokploy 서버 관리 스킬

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

센터 프로젝트 Dokploy 설정 정보

참고: 아래 정보는 센터 프로젝트의 실제 Dokploy 설정입니다. 설정 파일 위치:

.claude/skills/center-skill/scripts/config.sh

http://209.97.169.136:3000

https://sonub.com

root@sonub.com

DYmNZmKYtRG0RdNrsGcfn

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

1.2.3.4

ROOT_SSH_CONNECTION

root@1.2.3.4

DOKPLOY_API_KEY

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

사용자에게 요청할 질문

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 완료)

참조 문서

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

빠른 참조

필수 포트 설정

컨테이너 수신 주소

# 올바른 설정 (모든 인터페이스에서 수신)
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

)

/uploads/*

layout.php

배포 워크플로우

# 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

  - 브라우저 테스트