Docker Compose 개발 서비스 격리: 프로젝트별 PostgreSQL·Redis를 충돌 없이 실행하는 법

로컬 PostgreSQL이나 Redis를 ‘몇 초 만에 켠다’는 경험은 좋다. 나는 새 도구를 볼 때 속도보다 그 다음 질문을 먼저 본다. 다른 프로젝트를 열었을 때도 같은 버전·같은 초기 데이터·같은 접속 경계가 재현되는가. 8월 8일 Hacker News 새 글에 올라온 Servitor는 MySQL, PostgreSQL, Redis, RabbitMQ 같은 개발 서비스를 Docker 컨테이너로 선택해 실행하는 데 초점을 둔다. 이런 GUI가 설치·실행 장벽을 낮추는 것은 사실이다. 하지만 팀의 로컬 환경이 안정되려면 클릭 이력이나 개인 머신의 전역 컨테이너가 아니라, 저장소 안에 남는 Compose 프로젝트명, 명시한 포트, 볼륨 수명, healthcheck 기반 시작 조건이 필요하다. 결론부터 말하면 개발 서비스의 기본 단위는 ‘내 컴퓨터의 DB’가 아니라 한 저장소가 소유하고 언제든 지울 수 있는 프로젝트 범위의 의존성 묶음이어야 한다.

빠른 GUI와 재현 가능한 계약은 다른 문제다

Servitor 저장소는 Docker가 실행 중인 환경에서 서비스와 버전을 고르고 시작하는 GUI를 제공한다. Go·TypeScript·React·Wails로 만든 로컬 앱이며, README는 PostgreSQL, Redis, RabbitMQ 등 일반적인 개발 의존성을 컨테이너로 띄우는 목적을 분명히 적는다. 이는 데모와 개인 실험에서 유용하다. 다만 그 앱의 현재 릴리스는 서명되지 않았다고 README가 밝히므로, 운영자 입장에서는 OS 보안 경고를 우회하는 절차를 팀 표준으로 삼을 이유가 없다. 개발 편의 도구의 신뢰 경계와 서비스의 재현 계약은 분리해야 한다.

Compose는 이 계약을 코드로 남기는 기본 도구다. Docker 공식 문서는 여러 Compose 파일을 -f로 합칠 수 있고, 뒤 파일이 기존 설정을 override하거나 새 서비스를 추가할 수 있다고 설명한다. 이를 이용하면 저장소에는 공통 DB·캐시 정의를 남기고, 개발자 개인의 포트나 관찰 도구만 override 파일에 분리할 수 있다. 중요한 점은 파일을 여러 개 쓰는 기술 자체가 아니다. 어느 값이 저장소 표준이고 어느 값이 개인 편의인지 구별되는 구조가 핵심이다.

충돌은 포트보다 데이터 수명에서 더 자주 시작한다

로컬 서비스가 불안정해지는 첫 증상은 5432 already in use 같은 포트 오류다. 이 문제는 다른 호스트 포트를 매핑하거나, 프로젝트명으로 Compose 네트워크를 분리해 비교적 빨리 찾을 수 있다. 더 위험한 문제는 이름이 비슷한 전역 볼륨을 두 프로젝트가 공유해 버리는 경우다. 테스트를 위해 비운다고 생각한 데이터가 다른 기능 브랜치의 상태를 지우거나, 오래된 migration 데이터가 새 작업의 성공처럼 보이게 만든다.

그래서 개발 서비스에는 세 가지 이름을 함께 고정해야 한다.

1. 프로젝트명: Compose 프로젝트명을 저장소 이름이나 작업 환경 이름으로 정한다. 예를 들어 docker compose -p myapp-dev ...처럼 명시하면 컨테이너·네트워크·볼륨 이름이 같은 접두사 아래에 묶인다.
2. 호스트 포트: 앱이 호스트에서 직접 접속해야 할 때만 POSTGRES_PORT처럼 환경변수로 노출한다. 서비스 간 통신은 호스트 포트가 아니라 Compose 내부 서비스명과 컨테이너 포트를 쓴다.
3. 볼륨 수명: 개발 DB 데이터가 브랜치 간에도 살아야 하는지, 매번 초기화해야 하는지 먼저 정한다. 후자라면 종료와 함께 데이터를 지우는 명령을 의도적으로 사용하고, 전자라면 프로젝트 접두사를 가진 named volume만 유지한다.

이 원칙은 PostgreSQL뿐 아니라 Redis의 캐시와 RabbitMQ의 큐에도 똑같이 적용된다. 캐시는 비어 있어도 된다고 생각하기 쉽지만, 오래된 키가 테스트의 재현성을 망치는 순간 캐시도 데이터베이스와 같은 운영 대상이 된다.

시작 순서는 ‘컨테이너가 떴다’가 아니라 ‘의존성이 준비됐다’로 판단한다

docker compose up이 컨테이너 프로세스를 시작했다는 사실은 애플리케이션이 DB에 연결할 준비가 됐다는 뜻이 아니다. PostgreSQL은 초기화와 migration 전에 포트를 열 수 있고, Redis도 인증·설정 경로가 맞지 않으면 연결만 성공한 채 애플리케이션 요구를 충족하지 못할 수 있다. Docker Compose 공식 문서가 depends_on과 healthcheck 기반의 startup order를 별도 how-to로 다루는 이유도 여기에 있다.

작은 팀의 기본 절차는 다음처럼 단순하게 만들 수 있다. 아래 명령은 Docker Compose 공식 CLI의 프로젝트 지정·파일 병합 방식에 맞춘 실행 순서다. 실제 저장소에서는 compose.yaml의 서비스와 환경변수 이름만 그 프로젝트의 규칙에 맞게 바꾸면 된다.

# 1. 현재 Docker/Compose 설치 상태를 확인한다.
docker compose version

# 2. 공통 정의와 개인 개발 override를 같은 프로젝트 이름으로 실행한다.
docker compose -p myapp-dev -f compose.yaml -f compose.dev.yaml up -d

# 3. 서비스 상태와 healthcheck 결과를 먼저 읽는다.
docker compose -p myapp-dev ps

# 4. 테스트용 상태를 의도적으로 폐기할 때만 볼륨까지 제거한다.
docker compose -p myapp-dev down -v

여기서 네 번째 명령은 ‘정리 명령’이 아니라 데이터 파기 명령이다. PR 테스트나 매일 새로 만드는 샌드박스에는 적절하지만, 개발자가 이어서 작업할 데이터를 가진 환경에는 부적절하다. 이 차이를 README와 make target에 적지 않으면 팀원은 컨테이너만 내린다고 생각하고 실제로는 데이터까지 지우게 된다.

언제 전역 도구가 더 나은가

모든 개발 의존성을 Compose로 감싸야 한다는 뜻은 아니다. 로컬 CLI가 직접 제공하는 일회성 SQLite 데이터베이스, 테스트 프레임워크가 테스트마다 만들고 지우는 in-memory fake, 팀 전체가 관리하는 원격 preview DB는 별도 컨테이너가 오히려 복잡도를 늘릴 수 있다. 반론도 타당하다. 개인 프로젝트에서 PostgreSQL 하나를 오래 쓰고 포트 충돌이 없다면, GUI로 바로 띄우는 편이 처음에는 더 빠르다.

하지만 작업자가 늘거나 브랜치·서비스가 늘어난 순간, ‘누가 지금 이 DB를 쓰는가’가 설명되지 않는 전역 상태는 속도 이점을 잃는다. 프로젝트별 Compose 정의는 Docker를 더 쓰기 위한 형식이 아니다. 개발 의존성의 소유자와 삭제 권한을 저장소 단위로 제한하는 방법이다. 특히 AI 코딩 에이전트가 로컬에서 테스트를 반복하는 환경이라면, 에이전트가 전역 DB를 건드리지 않도록 프로젝트명·전용 포트·임시 볼륨을 명시하는 편이 훨씬 안전하다.

내 의견: 개발 환경의 성숙도는 설치 속도가 아니라 폐기 가능성으로 드러난다

나는 개발 서비스 UX의 다음 기준이 ‘한 번의 클릭으로 켜지는가’보다 ‘실패한 실험을 다른 작업에 피해 없이 지울 수 있는가’가 되어야 한다고 본다. 가벼운 반론은 명확하다. Compose 파일, 환경변수, healthcheck를 만들면 작은 프로젝트가 너무 의식적으로 변한다. 맞다. 단일 서비스·단일 개발자·휘발성 데이터라면 관리 비용이 더 클 수 있다. 하지만 데이터 마이그레이션, 캐시, 큐, 여러 브랜치가 한 머신에 공존하기 시작하면 그 명시성은 문서 비용이 아니라 복구 비용을 낮추는 보험이 된다.

김덕환 운영자 관점

김덕환 운영자 관점에서는 이번 주에 가장 자주 만지는 로컬 의존성 하나만 골라 프로젝트 범위를 선언하면 된다. docker compose -p <repo>-dev ps가 항상 같은 서비스 이름을 보여 주게 만들고, README에 ‘데이터 유지 종료’와 ‘테스트 데이터 폐기 종료’를 나눠 적는다. 다음으로 CI·에이전트용 실행에는 별도 프로젝트명과 down -v 경로를 둔다. 이 작은 분리만으로도 개인 작업, 기능 브랜치, 자동화 실행이 같은 Redis 키나 PostgreSQL 볼륨을 우연히 공유하는 일을 줄일 수 있다.

참고 자료

• Servitor GitHub README — PostgreSQL·Redis·RabbitMQ 등 로컬 개발 서비스를 Docker 컨테이너로 실행하는 GUI, Docker 실행 요구사항과 현재 unsigned release 안내
• Dev services, spun up in seconds — Hacker News item, 2026-08-08 확인
• Use multiple Compose files — Docker Docs: -f 파일 병합과 override·추가 서비스 동작
• Control startup order — Docker Docs: depends_on과 healthcheck 기반 의존성 시작 조건