Compose에서 먼저 맞춰야 하는 연결

Django, PostgreSQL, Nginx를 하나의 Compose 파일에 적었다고 바로 서비스가 완성되지는 않습니다. 이전 예제에서는 Nginx의 정적 파일 alias를 적어 놓고 실제 파일을 공유하는 volume 연결이 빠져 있었습니다. 이 글은 현재 저장소의 docker/dev/docker-compose.dev.yml과 docker/prod/docker-compose.prod.yml을 기준으로 이름·경로·준비 상태를 맞추는 과정을 설명합니다.

기존 프로젝트의 설정을 통째로 교체하는 예제는 아닙니다. 처음 만든 일반 예제와 현재 win-j 프로젝트의 파일 위치가 달라졌기 때문에, 아래 발췌는 각 연결을 확인하는 용도로 사용합니다.

서비스 이름과 호스트 포트를 구분한다

개발 DB는 호스트의 5433번을 컨테이너의 5432번에 연결합니다. 따라서 개발 PC의 DB 클라이언트는 localhost:5433, 같은 Compose 네트워크의 Django는 db:5432를 사용합니다. web 안에서 localhost는 web 자신을 가리킵니다.

운영 파일은 네 서비스가 backend 네트워크에 참여합니다. Nginx upstream에는 실제 컨테이너 이름인 myapp_web:8000이 적혀 있습니다. 서비스 이름과 컨테이너 이름은 같은 개념이 아니므로 설정을 다른 프로젝트로 옮길 때 upstream 이름도 함께 대조해야 합니다. IP를 고정해 복사하기보다 이름으로 연결하는 원리는 Docker Compose 네트워크 안내를 참고할 수 있습니다.

파일 경로가 달라도 같은 volume이면 연결된다

운영 설정에서 정적·업로드 파일을 연결하는 부분을 줄이면 다음과 같습니다. 이것만으로 실행할 수 있는 전체 Compose 파일은 아닙니다.

services:
  web:
    volumes:
      - static_volume:/app/staticfiles
      - media_volume:/app/media
  nginx:
    volumes:
      - static_volume:/var/www/static:ro
      - media_volume:/var/www/media:ro
volumes:
  static_volume:
  media_volume:

Django의 STATIC_ROOT 기본값은 /app/staticfiles이고 Nginx의 /static/ alias는 /var/www/static/입니다. 두 절대 경로를 같은 문자열로 만들 필요는 없습니다. 같은 named volume의 같은 파일을 각 컨테이너가 자기 경로에서 볼 수 있어야 합니다.

반대로 alias만 /app/staticfiles/로 고쳐도 Nginx에 그 폴더가 연결되지 않았다면 파일은 보이지 않습니다. volume 이름도 Compose 프로젝트 이름에 따라 실제 리소스 이름이 달라질 수 있으므로 다른 작업 폴더에서 임의로 새 스택을 띄우지 않습니다.

실행 순서와 서비스 준비는 다르다

현재 web은 DB의 healthcheck 성공을 기다립니다. DB 검사는 pg_isready를 사용하며, 운영 Nginx는 web의 healthcheck를 기다립니다. 다만 web 검사는 내부 8000번 포트에 소켓 연결이 가능한지만 확인합니다. 로그인, DB 쿼리, 정적 파일까지 검사하는 구성은 아닙니다.

단순한 depends_on: [db]와 condition: service_healthy의 차이는 Docker 시작 순서 문서에 설명되어 있습니다. 시작 시 검사에 통과했다고 이후 DB 장애나 요청 실패를 자동으로 모두 복구하는 것은 아닙니다.

실행 명령이 하는 일을 읽고 시작한다

명령 또는 설정 이 프로젝트에서 확인할 의미
config --quiet 설정 해석만 검사, 서비스 시작 없음
build Dockerfile·패키지로 이미지 생성
up 컨테이너 생성·재생성 및 실행 가능
개발 web 기본 명령 migrate 성공 후 runserver 실행
운영 web 기본 명령 migrate → collectstatic → Gunicorn
restart 기존 컨테이너 재시작, 이미지 재빌드 아님

운영 명령에는 set -e와 &&가 있어 앞 단계가 실패하면 Gunicorn까지 진행하지 않습니다. 그래서 컨테이너가 반복 시작되면 Gunicorn 옵션뿐 아니라 migration이나 static 수집 오류도 로그에서 확인해야 합니다. Dockerfile의 기본 CMD만 보고 실제 실행 과정을 판단하면 Compose의 command 덮어쓰기를 놓칠 수 있습니다.

다음 두 명령은 프로젝트 루트에서 개발 구성을 확인하는 용도입니다.

docker compose -f .\docker\dev\docker-compose.dev.yml config --quiet
docker compose -f .\docker\dev\docker-compose.dev.yml ps

실패했을 때 기록할 최소 정보

환경 파일을 찾지 못하면 env_file이 Compose 파일 기준 어느 위치를 가리키는지 확인합니다. 포트 충돌이면 호스트 쪽 포트를 점검하고, DB 이름 해석 실패면 web과 db의 네트워크를 확인합니다. CSS 404라면 수집 위치 → 공유 volume → Nginx alias 순서로 추적합니다.

공유할 기록에는 사용한 Compose 파일 경로, 실패한 서비스 이름, 오류 발생 시각, 마지막 오류 메시지를 남깁니다. 환경 변수 전체나 DB 접속 URL을 그대로 게시할 필요는 없습니다. 이어서 Django 실행 경로와 static 점검, PostgreSQL 연결 진단에서 각 실패 지점을 더 좁혀볼 수 있습니다.