Dokploy 설정 가이드 — Ubuntu

Dokploy란 무엇인가요?
Dokploy는 무료로 제공되는 셀프 호스팅 (self-hosted) PaaS입니다. 여러분의 VPS에서 실행되는 자신만의 Vercel/Heroku라고 할 수 있습니다. Docker Swarm, Traefik (SSL + 라우팅용), PostgreSQL, Redis를 하나의 웹 대시보드로 묶어 제공합니다. 수동적인 Docker 설정 없이도 단일 UI에서 앱을 배포하고, 데이터베이스를 관리하며, 도메인을 처리할 수 있습니다.

✅ 테스트 완료된 Ubuntu 버전

• Ubuntu 24.04 LTS
• Ubuntu 22.04 LTS
• Ubuntu 20.04 LTS

✅ 최소 서버 요구 사항

리소스	최소 사양
RAM	2 GB (4 GB 권장)
...

✅ 필수 포트 — 설치 전 해당 포트가 비어 있는지 확인하세요

포트	용도
80	HTTP 트래픽 (Traefik)
...

1️⃣ 첫 번째 단계 — VPS에 연결하기

✅ 1. 자격 증명(Credentials) 확보
호스팅 제공업체로부터 다음 세 가지 정보가 필요합니다:

• IP 주소: 568.82.48.166
• 사용자 이름 (Username): root
• 비밀번호 (Password): Subham@Xam_08

✅ 2. 터미널을 통해 연결

ssh root@568.82.48.166

✅ 3. 연결 확인
호스트 인증 프롬프트가 나타납니다:

The authenticity of host '568.82.48.166' can't be established.
Are you sure you want to continue connecting (yes/no/[fingerprint])?

yes를 입력하고 Enter를 누르세요.

✅ 4. 비밀번호 입력

root@568.82.48.166's password:

비밀번호를 붙여넣고 Enter를 누르세요. 입력하는 동안 터미널에 문자가 표시되지 않는 것은 정상입니다.

✅ 5. 성공!
Ubuntu 환영 화면이 나타나며 셸 (shell)에 진입하게 됩니다:

root@your-hostname:~#

2️⃣ 두 번째 단계 — 시스템 준비

✅ 1. 터미널 화면 지우기

clear

✅ 2. 운영체제(OS) 확인

lsb_release -a

예상 출력 결과:

Distributor ID: Ubuntu
Description:    Ubuntu 22.04.x LTS
Release:        22.04

✅ 3. 패키지 리스트 업데이트

sudo apt update

✅ 4. 설치된 패키지 업그레이드

sudo apt upgrade -y

업그레이드 중에 설정 프롬프트(configuration prompts)가 나타나면, Tab 키를 눌러 OK를 강조한 뒤 Enter를 누르세요.

✅ 5. 필수 도구 설치 (Install Essential Tools)

sudo apt install -y curl wget ca-certificates

✅ 6. 필요 시 재부팅 (Reboot if Prompted)
업그레이드 중에 커널 업데이트(kernel update)가 언급된다면:

sudo reboot

그 후 다시 SSH로 접속하세요.

3️⃣ 세 번째 단계 — Docker 설치

Ubuntu에서는 Dokploy의 설치 프로그램이 Docker를 자동으로 설치할 수 있습니다. 하지만 버전과 설정을 완전히 제어할 수 있도록 Docker를 직접 먼저 설치하는 것이 권장되는 모범 사례(best practice)입니다.

✅ 1. 기존 Docker 버전 제거 (Remove Any Old Docker Versions)

sudo apt remove -y docker docker-engine docker.io containerd runc

(이 패키지들이 설치되어 있지 않아도 괜찮습니다. 명령어가 단순히 "설치되지 않음"이라고 표시할 것입니다.)

✅ 2. Docker 공식 GPG 키 및 저장소 추가 (Add Docker's Official GPG Key and Repository)

sudo install -m 0755 -d /etc/apt/keyrings

curl -fsSL https://download.docker.com/linux/ubuntu/gpg | \
...

✅ 3. Docker Engine + Compose 설치 (Install Docker Engine + Compose)

sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

✅ 4. Docker 활성화 및 시작 (Enable and Start Docker)

sudo systemctl enable --now docker

✅ 5. Docker 설치 확인 (Verify Docker Installation)

docker --version
docker compose version

예상 출력 결과:

Docker version 29.x.x, build ...
Docker Compose version v5.x.x

✅ 6. Docker 작동 테스트 (Test Docker Works)

docker run hello-world

출력 결과에 Hello from Docker!가 보여야 합니다.

4️⃣ 네 번째 단계 — 방화벽 포트 개방 (Open Firewall Ports)

✅ 1. 방화벽 상태 확인 (Check Firewall Status)

sudo ufw status

✅ 2. 필수 포트 개방 (Open Required Ports)

# SSH (중요 — 접속이 차단되지 않도록 주의하세요)
sudo ufw allow 22/tcp

...

✅ 3. 규칙 확인 (Verify Rules)

sudo ufw status numbered

예상 출력 결과:

Status: active

     To                         Action      From
...

5️⃣ 다섯 번째 단계 — Dokploy 설치

✅ 1. Dokploy 설치 프로그램 실행 (Run the Dokploy Installer)

curl -sSL https://dokploy.com/install.sh | sh

설치 프로그램이 자동으로 다음 작업을 수행합니다:

• Docker Swarm 초기화 (Initialize Docker Swarm)
• dokploy-network 오버레이 네트워크 (overlay network) 생성
• Dokploy 패널 (Dokploy panel) 컨테이너 배포
• dokploy-postgres (PostgreSQL 16) 배포 — Dokploy 전용 내부 DB
• dokploy-redis (Redis 7) 배포 — Dokploy 전용 배포 큐 (deployment queue)
• dokploy-traefik 배포 — 라우팅 및 SSL을 위한 리버스 프록시 (reverse proxy)

✅ 2. 설치 프로그램이 완료될 때까지 대기
다음 메시지가 표시됩니다:

Congratulations, Dokploy is installed!
Wait 15 seconds for the server to start
Please go to http://568.82.48.166:3000

브라우저를 열기 전 전체 15초 동안 기다려 주세요.

✅ 3. 모든 플랫폼 서비스가 실행 중인지 확인

docker service ls

예상 출력 결과 — 모든 서비스의 REPLICAS 항목이 1/1로 표시되어야 합니다:

NAME               MODE         REPLICAS   IMAGE
dokploy            replicated   1/1        dokploy/dokploy:latest
dokploy-postgres   replicated   1/1        postgres:16
...

또한 실행 중인 컨테이너를 확인하세요:

docker ps --format '{{.Names}}\t{{.Image}}\t{{.Status}}'

✅ 4. 패널이 응답하는지 확인

curl -I http://127.0.0.1:3000/

예상 결과:

HTTP/1.1 302 Found
Location: /register

6️⃣ 여섯 번째 단계 — 초기 대시보드 설정

✅ 1. 브라우저에서 Dokploy 열기

등록 페이지로 리다이렉트(redirect)됩니다.

✅ 2. 관리자 계정 생성
다음 정보를 입력하세요:

• 이메일 주소 (Email address)
• 비밀번호 (Password) (강력한 비밀번호를 사용하세요 — 이것이 당신의 마스터 관리자 계정입니다)

**계정 생성 (Create Account)**을 클릭하세요.

✅ 3. 대시보드 접속 완료!
주로 사용하게 될 주요 섹션은 다음과 같습니다:

• 프로젝트 (Projects) — 앱 및 데이터베이스 생성 및 관리
• 설정 (Settings) → 서버 (Server) — 도메인 및 SSL 구성
• 설정 (Settings) → 대상 (Destinations) — S3 백업 대상 설정

7️⃣ 일곱 번째 단계 — 도메인을 Dokploy로 연결하기

✅ 1. 도메인 구매

GoDaddy, Namecheap, Cloudflare 등에서 구매하세요.

✅ 2. DNS 레코드 추가

도메인 제공업체의 DNS 관리 페이지에서 다음을 추가하세요:

유형 (Type)	이름 (Name)	가리키는 대상 (Points To)	TTL
A	@	568.82.48.166	1 hour
A	www	568.82.48.166	1 hour

패널 서브도메인(예: panel.xyz.com)의 경우:

유형 (Type)	이름 (Name)	가리키는 대상 (Points To)	TTL
A	panel	568.82.48.166	1 hour

✅ 3. DNS 전파 확인 (Verify DNS Propagation)

nslookup yourdomain.com

예상 결과:

Name:    yourdomain.com
Address: 568.82.48.166

DNS 전파는 전 세계적으로 완료되는 데 최대 24시간이 걸릴 수 있습니다. 보통은 5~30분 정도 소요됩니다.

✅ 4. Dokploy에서 도메인 설정하기

1. Settings → Server로 이동합니다.
2. Dokploy Panel Domain 항목에 yourdomain.com을 입력합니다.
3. 인증서 제공업체(certificate provider)로 Let's Encrypt를 선택합니다.
4. SSL 알림을 받을 이메일 주소를 입력합니다.
5. Save를 클릭합니다.

Dokploy에 내장된 Traefik이 SSL 인증서를 자동으로 발급 및 갱신합니다.

✅ 5. HTTPS 작동 여부 확인

브라우저에 자물쇠 아이콘이 표시된 Dokploy 로그인 페이지가 나타나야 합니다.

✅ 6. (선택 사항) 직접적인 IP:Port 접속 비활성화

도메인과 HTTPS가 정상적으로 작동하는 것이 확인되면, 3000번 포트 노출을 제거하세요:

docker service update --publish-rm "published=3000,target=3000,mode=host" dokploy

⚠️ 반드시 도메인이 작동하는 것을 확인한 후에 이 명령을 실행하세요. 그렇지 않으면 접속 권한을 잃을 수 있습니다.

8️⃣ 여덟 번째 단계 — 애플리케이션을 위한 PostgreSQL 설정

참고: Dokploy는 자체 데이터를 위해 이미 내부적으로 PostgreSQL을 실행하고 있습니다. 여기서 생성하는 것은 애플리케이션을 위한 별도의 데이터베이스입니다.

✅ 1. 프로젝트 생성

1. Projects → New Project를 클릭합니다.
2. 이름을 입력합니다 (예: my-app).
3. Create를 클릭합니다.

✅ 2. PostgreSQL 데이터베이스 서비스 추가

1. 프로젝트 내부에서 Create New Service를 클릭합니다.
2. Database를 선택합니다.
3. PostgreSQL을 선택합니다.
4. 양식을 작성합니다:

필드 (Field)	예시 (Example)
서비스 이름 (Service Name)	my-app-db
...

1. Create를 클릭합니다.

✅ 3. 데이터베이스 배포 (Deploy)

1. PostgreSQL 서비스의 General 탭으로 이동합니다.
2. Deploy를 클릭합니다.
3. 상태 배지(status badge)가 초록색인 Running으로 바뀔 때까지 기다립니다.

✅ 4. 연결 문자열 (Connection Strings) 가져오기

동일한 프로젝트 내의 앱 컨테이너(app containers)를 사용하는 경우, 서비스 이름을 호스트 이름(hostname)으로 사용하세요:

DB_HOST=my-app-db
DB_PORT=5432
DB_NAME=myapp
...

⚠️ localhost나 서버 IP가 아닌 my-app-db(서비스 이름)를 호스트로 사용하세요. 동일한 프로젝트 내의 컨테이너들은 내부 Docker 네트워크를 통해 서비스 이름으로 통신합니다.

✅ 5. (선택 사항) PostgreSQL 외부 노출 (Expose Externally)

pgAdmin 또는 TablePlus를 사용하여 로컬 머신에서 연결하려면:

1. PostgreSQL 서비스 → General 탭으로 이동합니다.
2. External Credentials 항목 아래에서 External Port를 5433으로 설정합니다.
3. Save를 클릭합니다.
4. 포트를 개방합니다:

   sudo ufw allow 5433/tcp

1. 로컬 머신에서 연결합니다:

   Host:     568.82.48.166
   Port:     5433
   Database: myapp
...

✅ 6. 모니터링 및 로그 확인

• Monitoring tab — CPU, 메모리, 디스크 및 네트워크 그래프를 실시간으로 확인합니다.
• Logs tab — 컨테이너 로그를 확인하여 에러를 점검합니다.

✅ 7. 자동 백업 설정 (선택 사항)

1. Settings → Destinations로 이동하여 S3 버킷(AWS S3, Cloudflare R2, MinIO 등)을 추가합니다.
2. PostgreSQL 서비스의 Backups 탭으로 이동합니다.
3. S3 목적지(destination)를 선택하고, 스케줄을 설정한 뒤 Save를 클릭합니다.

9️⃣ 아홉 번째 단계 — 앱을 위한 Redis 설정

참고: Dokploy는 배포 대기열(deployment queuing)을 위해 자체적인 내부 Redis를 가지고 있습니다. 여기서 생성하는 것은 애플리케이션을 위한 별도의 Redis (캐싱, 세션, 큐 용도)입니다.

✅ 1. 프로젝트에 Redis 서비스 추가

1. 프로젝트 내부에서 Create New Service를 클릭합니다.
2. Database를 선택합니다.
3. Redis를 선택합니다.
4. 양식을 작성합니다:

필드 (Field)	예시 (Example)
Service Name	my-app-cache
...

1. Create를 클릭합니다.

✅ 2. Redis 배포 (Deploy)

1. General 탭으로 이동합니다.
2. Deploy를 클릭합니다.
3. 상태가 Running (초록색)으로 표시될 때까지 기다립니다.

✅ 3. 연결 문자열 (Connection Strings) 가져오기

REDIS_HOST=my-app-cache
REDIS_PORT=6379
REDIS_PASSWORD=RedisPass@2025
...

Redis 데이터베이스 번호(0–15)를 사용하는 여러 유스케이스(use cases)의 경우:

# 캐싱 (Caching) (DB 0)
CACHE_URL=redis://:RedisPass@2025@my-app-cache:6379/0

...

✅ 4. (선택 사항) RedisInsight를 위해 Redis를 외부로 노출하기

로컬의 RedisInsight에서 Redis를 관리하려면:

1. Redis 서비스로 이동 → General 탭
2. External Credentials 항목 아래에서 External Port를 6379로 설정합니다.
3. Save를 클릭합니다.
4. 포트를 개방합니다:

   sudo ufw allow 6379/tcp

1. RedisInsight에서 새로운 데이터베이스를 추가합니다:
   • Host: 568.82.48.166
   • Port: 6379
   • Username: default
   • Password: RedisPass@2025

🔟 열 번째 단계 — 애플리케이션 배포하기

✅ 1. 애플리케이션 서비스 추가

1. 프로젝트 내부에서 Create New Service를 클릭합니다.
2. Application을 선택합니다.
3. 소스 유형(source type)을 선택합니다:
   • GitHub / GitLab — 자동 CI/CD를 위해 리포지토리(repo)를 연결합니다.
   • Docker Compose — docker-compose.yml 파일을 업로드합니다.
   • Docker Image — 모든 레지스트리(registry)로부터 이미지를 가져옵니다(pull).

✅ 2. 환경 변수 (Environment Variables) 설정

Environment 탭으로 이동하여 변수를 추가합니다:

DATABASE_URL=postgresql://myapp_user:StrongPass@2025@my-app-db:5432/myapp
REDIS_URL=redis://:RedisPass@2025@my-app-cache:6379
PORT=3333
...

Save를 클릭합니다.

✅ 3. 앱을 위한 도메인 (Domain) 구성

1. Domains 탭으로 이동합니다.
2. Add Domain을 클릭합니다.
3. 앱의 서브도메인(subdomain)을 입력합니다 (예: app.yourdomain.com).
4. 앱이 리스닝(listening)하는 Container Port를 설정합니다 (예: 3333).
5. SSL을 위해 Let's Encrypt를 선택합니다.
6. Save를 클릭합니다.

DNS 설정에서 app.yourdomain.com이 서버 IP를 가리키는 A 레코드(A record)를 가지고 있는지 확인하십시오.

✅ 4. 배포 및 확인

1. General 탭으로 이동합니다.
2. Deploy를 클릭합니다.
3. 실시간 배포 로그(deployment logs)를 확인합니다.
4. 상태가 Running으로 표시되면, https://app.yourdomain.com에 접속합니다.

⚙️ Dokploy 관리하기

유용한 Docker Swarm 명령어

# 모든 Dokploy 플랫폼 서비스 보기
docker service ls

...

Dokploy를 최신 버전으로 업데이트하기

curl -sSL https://dokploy.com/install.sh | sh -s update

📝 문제 해결 (Troubleshooting)

⭐ 3000번 포트에 접속할 수 없는 경우

# 방화벽 규칙 확인
sudo ufw status

...

⭐ SSL 인증서가 발급되지 않는 경우

# ACME 오류 확인을 위해 Traefik 로그 확인
docker logs $(docker ps -q -f name=dokploy_dokploy-traefik) 2>&1 | tail -50

...

⭐ 앱이 PostgreSQL 또는 Redis에 연결할 수 없는 경우

호스트 이름으로 localhost 대신 **서비스 이름 (service name)**을 사용하세요:

# 잘못된 예
DATABASE_URL=postgresql://user:pass@localhost:5432/mydb

...

모든 서비스가 동일한 네트워크에 있는지 확인하세요:

docker network inspect dokploy-network

⭐ 재부팅 후 서비스가 자동으로 재시작되지 않는 경우