도커 컴포즈 네트워크 설정: 기본 동작과 커스텀 구성
핵심 요약 도커 컴포즈는 프로젝트마다 기본 네트워크를 만들어 서비스 이름만으로 컨테이너끼리 통신하게 한다. 2026년 7월 기준 기본 동작부터 커스텀 네트워크 분리, 외부 네트워크 재사용까지 개발자 눈높이로 정리했다.
도커 컴포즈(Docker Compose, 여러 컨테이너를 설정 파일 하나로 묶어 함께 실행하는 도구)로 서비스를 여러 개 띄우면, 같은 프로젝트에 속한 컨테이너끼리는 서비스 이름만으로 서로를 찾아 통신할 수 있다. 도커 공식 문서(docs.docker.com)에 따르면 컴포즈는 프로젝트마다 기본 네트워크를 하나 만들어 정의된 서비스를 전부 여기에 연결한다고 안내한다. 덕분에 웹 컨테이너가 데이터베이스에 접속할 때 바뀌기 쉬운 IP 주소 대신 db 같은 서비스 이름을 호스트명으로 쓰면 된다.
이 글은 2026년 7월 기준 Docker Compose v2(compose.yaml 또는 docker-compose.yml)에서 네트워크를 설정하는 방법을 개발자 눈높이로 정리한다. 단일 호스트에서 여러 컨테이너를 연결하는 상황을 기준으로 하며, 여러 서버에 걸친 오버레이 네트워크나 도커 스웜·쿠버네티스의 네트워크 구성은 다루지 않는다.
기본 네트워크는 어떻게 동작하나
컴포즈를 실행하면 별도 설정이 없어도 프로젝트 이름을 딴 기본 브리지 네트워크가 자동으로 만들어지는 것으로 안내된다. 브리지 네트워크(bridge network)는 같은 호스트 안의 컨테이너를 하나의 가상 랜처럼 묶어 주는 도커의 기본 연결 방식이다. 여기에 들어간 서비스는 내부 DNS가 서비스 이름을 주소로 풀어 주어 서로를 찾는다.
아래 예시에서 web과 db는 같은 기본 네트워크에 자동으로 들어간다. 그래서 web 안의 애플리케이션은 데이터베이스 접속 정보에 호스트명으로 db를, 포트로 컨테이너 내부 포트인 5432를 적으면 된다.
services:
web:
build: .
ports:
- "8080:80"
db:
image: postgres:16
environment:
POSTGRES_PASSWORD: example
여기서 헷갈리기 쉬운 부분이 포트다. ports의 8080:80은 호스트(내 컴퓨터)의 8080번을 컨테이너의 80번으로 연결해 바깥에서 접근하도록 여는 설정이다. 반면 컨테이너끼리 내부에서 주고받을 때는 이 공개 포트가 필요 없고, 상대 컨테이너가 실제로 열어 둔 포트로 바로 붙는다.
서비스 이름으로 통신하고 별칭 붙이기
서비스 사이 통신의 핵심은 서비스 이름이 곧 호스트명이 된다는 점이다. IP를 직접 관리하지 않아도 컴포즈 내부 DNS가 이름을 컨테이너 주소로 풀어 준다고 도커 공식 문서는 설명한다. 컨테이너를 다시 만들어 IP가 바뀌어도 이름은 그대로여서, 설정 파일에 IP를 박아 둘 이유가 없다.
기존 코드가 특정 호스트명을 기대하거나 한 서비스를 다른 이름으로도 부르고 싶을 때는 별칭(alias)을 붙일 수 있다. 아래처럼 기본 네트워크 아래 aliases를 지정하면 db 서비스에 postgres라는 이름으로도 접근할 수 있는 것으로 안내된다.
services:
db:
image: postgres:16
networks:
default:
aliases:
- postgres
별칭은 데이터베이스 호스트명이 postgres로 굳어 있는 라이브러리를 그대로 쓰거나, 서비스 이름을 바꾸면서 기존 연결을 유지해야 할 때 쓸모가 있다.
커스텀 네트워크로 서비스 나누기
규모가 커지면 모든 서비스를 한 네트워크에 두기보다 역할별로 나누는 편이 안전하다. 최상위 networks 키에 네트워크를 정의하고, 각 서비스의 networks에 연결할 대상을 적으면 된다. 같은 네트워크에 속한 서비스끼리만 서로를 볼 수 있어, 데이터베이스를 바깥에 노출되는 서비스와 떼어 놓는 구성이 가능하다.
services:
web:
build: .
networks:
- frontend
api:
build: ./api
networks:
- frontend
- backend
db:
image: postgres:16
networks:
- backend
networks:
frontend:
backend:
이 구성에서 web은 frontend에만 연결돼 api까지는 닿지만 db에는 직접 접근하지 못한다. api만 두 네트워크에 걸쳐 있어, 프론트 요청을 받아 데이터베이스로 넘기는 중간 다리 역할을 맡는다. 어떤 서비스에도 ports로 호스트 포트를 열지 않으면 그 서비스는 같은 네트워크의 다른 컨테이너에서만 접근할 수 있고, 호스트 바깥에서는 보이지 않는다.
이미 만든 네트워크는 어떻게 붙이나
이미 다른 프로젝트나 docker network create로 만들어 둔 네트워크가 있다면, external: true로 표시해 그대로 재사용할 수 있는 것으로 안내된다. 이때 컴포즈는 네트워크를 새로 만들지 않고 기존 것을 찾아 연결하며, 해당 네트워크가 없으면 오류를 내는 것으로 알려져 있다.
networks:
shared:
external: true
네트워크 드라이버는 기본값이 bridge이며, 단일 호스트 구성에서는 대개 이 값을 그대로 두면 된다. 호스트 네트워크나 오버레이처럼 다른 드라이버가 필요한 경우는 여러 서버를 묶는 오케스트레이션 환경에서 주로 나오므로, 단일 호스트 개발·배포에서는 손댈 일이 드물다. 여러 서버로 확장해 컨테이너 배치를 자동화하는 단계에서 만나는 도구가 쿠버네티스다.
설정이 맞는지 확인하는 방법
네트워크 구성이 의도대로 됐는지는 몇 가지 명령으로 바로 확인할 수 있다. docker compose config는 최종 병합된 설정을 출력해 오타나 잘못된 들여쓰기를 잡아 준다. 실행 중이라면 docker compose ps로 서비스 상태를, docker network ls로 실제 만들어진 네트워크 목록을 확인한다.
docker compose config
docker compose ps
docker network ls
서비스 사이 연결이 안 될 때는 두 컨테이너가 같은 네트워크에 있는지부터 살피는 편이 빠르다. 이름을 잘못 적었거나 서로 다른 커스텀 네트워크에만 연결돼 있으면, 서비스 이름을 호스트명으로 써도 주소를 찾지 못한다. 대부분의 연결 문제는 이 두 가지에서 갈린다.