초기 웹 서비스나 MVP를 배포할 때 창업자나 1인 개발자가 가장 먼저 고민하는 것은 '인프라 비용과 관리 공수'입니다.
- Vercel, Render, Heroku 같은 PaaS:
git push한 번으로 배포되고 편리하지만, 트래픽이 조금만 늘거나 상용 데이터베이스를 붙이면 월 10~30만 원 이상의 요금이 청구됩니다. - AWS ECS, EKS, 쿠버네티스: 엔터프라이즈급 확장성을 제공하지만, 초기 단계의 1인 개발자나 스타트업이 관리하기에는 아키텍처 복잡도와 러닝커브가 너무 큽니다.
8년간 다수의 웹 서비스를 직접 개발하고 운영해 온 큐룸(QUROOM)에서는 월 1~2만 원대 가상서버(VPS) 단 한 대에 오픈소스 PaaS인 Dokku를 올려, Heroku와 똑같이 git push dokku main 명령어 하나로 무중단 배포와 SSL 자동 갱신을 운영하고 있습니다.
이 글에서는 비싼 클라우드 비용을 아끼고 개발 생산성을 극대화할 수 있는 실전 Dokku 배포 환경 구축 5단계를 상세한 터미널 명령과 함께 공개합니다.
1. Dokku 아키텍처의 핵심 장점
Dokku는 Docker 기반의 초경량 오픈소스 PaaS(Platform as a Service)입니다.
- 철저한 프로세스 격리: 단일 서버 안에서 여러 개의 독립된 앱(예: 프론트엔드, Django 백엔드, 챗봇 등)을 Docker 컨테이너로 격리하여 실행합니다.
- Git Push 배포: 로컬 컴퓨터에서
git push dokku main만 치면, 서버에서 코드를 빌드하고 정적 파일을 수집한 뒤 새 컨테이너를 띄웁니다. - Zero-downtime(무중단 교체): 새 컨테이너가 정상적으로 5000번 포트를 열고 헬스체크에 통과한 것을 확인한 뒤에야 Nginx 트래픽을 넘기므로 서비스 중단이 없습니다.
- 플러그인 생태계: 공식 플러그인 한 줄로 PostgreSQL 데이터베이스 생성, 환경변수(
DATABASE_URL) 자동 주입, Let's Encrypt 무료 SSL 자동 갱신까지 원클릭으로 끝납니다.
2. 실전 구축 5단계
Ubuntu 22.04 LTS 또는 24.04 LTS가 설치된 단일 VPS(Hetzner, Vultr, 네이버클라우드, AWS Lightsail 등) 기준입니다.
1단계: Dokku Core 설치 및 SSH 키 등록
서버 터미널에 root 권한으로 접속하여 공식 부트스트랩 스크립트를 실행합니다:
# Dokku 자동 설치 (Docker 엔진 자동 구성 포함)
wget -NP /tmp https://dokku.com/bootstrap.sh
sudo DOKKU_TAG=v0.34.8 bash /tmp/bootstrap.sh
# 로컬 개발용 컴퓨터의 SSH 공개키 등록 (비밀번호 없는 git push 지원)
cat ~/.ssh/id_rsa.pub | sudo dokku ssh-keys:add admin2단계: 애플리케이션 생성 및 포트 매핑
호스팅할 프로젝트 이름을 정의하고 앱을 생성합니다:
# 'landing'이라는 이름의 앱 생성
dokku apps:create landing
# 포트 매핑: Nginx 외부 80/443 포트를 내부 컨테이너 5000번으로 연결
dokku proxy:ports-add landing http:80:5000
dokku proxy:ports-add landing https:443:5000⚠️ 도메인 DNS 설정 및 포트 바인딩 기본 개념이 낯설다면 실서버 배포 장애 4가지와 해결 절차를 먼저 읽어보시는 것을 권장합니다.
3단계: 공식 PostgreSQL 플러그인 연동
외부 유료 DB 서비스(AWS RDS 등)를 따로 계약할 필요 없이, 같은 서버 내 Docker 격리 컨테이너로 Postgres를 띄우고 앱에 연결합니다:
# 공식 postgres 플러그인 설치
sudo dokku plugin:install https://github.com/dokku/dokku-postgres.git postgres
# DB 인스턴스 생성 및 landing 앱 링크
dokku postgres:create landing-db
dokku postgres:link landing-db landing링크가 완료되면 DATABASE_URL=postgres://landing:비밀번호@dokku-postgres-landing-db:5432/landing_db 환경변수가 앱 컨테이너 내부로 자동 주입됩니다. Django나 Node.js는 이 환경변수 하나만 읽으면 DB 연결이 끝납니다.
4단계: 무중단 배포를 위한 헬스체크 (app.json)
코드 저장소 루트에 app.json을 작성하여 새 컨테이너가 뜬 후 정상 작동할 때만 Nginx 프록시를 스위칭하도록 설정합니다:
{
"healthchecks": {
"web": [
{
"type": "port",
"port": 5000,
"attempts": 3,
"timeout": 5,
"wait": 5
}
]
}
}5단계: Let's Encrypt 무료 SSL 자동화
도메인의 A 레코드가 서버 IP를 가리키도록 설정한 후, 플러그인을 통해 인증서를 발급합니다:
# letsencrypt 플러그인 설치 및 도메인 바인딩
sudo dokku plugin:install https://github.com/dokku/dokku-letsencrypt.git
dokku domains:set landing quroom.kr www.quroom.kr
# 이메일 등록 및 인증서 자동 발급
dokku letsencrypt:set landing email [email protected]
dokku letsencrypt:enable landing
# 만료 전 자동 갱신 크론탭 활성화
dokku letsencrypt:cron-job --add이제 매월 만료일을 신경 쓸 필요 없이 백그라운드에서 Let's Encrypt SSL이 자동 갱신됩니다.
3. 로컬에서 배포하는 워크플로우
설정이 끝났다면, 로컬 개발 컴퓨터의 Git 원격 저장소에 Dokku를 추가하기만 하면 됩니다:
# 로컬 Git에 dokku 리모트 추가
git remote add dokku [email protected]:landing
# 단 한 줄로 무중단 프로덕션 배포 실행
git push dokku main터미널에서 자동으로 빌드팩 실행, collectstatic, DB 마이그레이션 실행, 컨테이너 헬스체크를 순차적으로 통과한 뒤 1분 이내에 실서버에 적용됩니다.
4. 인프라 비용 절감 효과
| 구분 | 일반 클라우드 PaaS/AWS 조합 | 큐룸 권장 VPS Dokku 모놀리스 |
|---|---|---|
| 웹 서버 | Vercel Pro ($20) + AWS ECS ($40) | 단일 VPS 2코어 4GB (월 1.5만 원) |
| 데이터베이스 | AWS RDS PostgreSQL t4g.micro (월 2.5만 원) | Dokku 내장 PostgreSQL (무료) |
| SSL 인증서 | 도메인 업체 유료 SSL (연 3~5만 원) | Let's Encrypt 플러그인 (무료) |
| 월간 총비용 | 월 12~20만 원 이상 | 월 1.5~2만 원 고정 |
비용 절감뿐만 아니라, 모든 서비스와 데이터베이스가 단일 네트워크 내부에서 통신하므로 응답 지연(Latency)이 극도로 낮아진다는 강력한 기술적 이점이 있습니다.
📚 함께 읽으면 좋은 큐룸(QUROOM) 기술 아티클
- 🛠️ Codex·Claude 생성 코드를 실서버에 배포할 때 발생하는 기술적 장애 4가지와 해결 절차
- 💰 스타트업 MVP 외주 개발 견적 분석: 에이전시 M/M 산정 방식 vs 1인 풀스택 린 아키텍처
- 📋 외주 개발 계약 시 분쟁을 예방하는 5대 과업 제외 범위(Out-of-Scope)와 인수 검수 기준
- 🏗️ Codex·Claude로 만든 AI 프로토타입, 상용화할 때 '살릴 코드'와 '버릴 코드'의 기술적 기준
- 💳 포트원 V2 결제 웹훅 멱등성 보장과 금액 위변조 방지 아키텍처
- 🏠 큐룸(QUROOM) 8년 차 풀스택 개발사 소개 및 인프라 구축 자문 안내
＊ 본 글은 8년 차 1인 풀스택 개발사 큐룸(QUROOM)의 실제 경험을 바탕으로 AI와 함께 작성했습니다.