Docker Compose 서비스 이름을 명확하게 짓는 이유

Docker Compose에서 서비스 이름은 단순한 레이블이 아니다. 같은 네트워크 안의 다른 컨테이너에서 이 이름으로 직접 호스트명처럼 접근할 수 있다.

services:
  api:
    build: ./api
  db:
    image: postgres:16

이 경우 api 컨테이너에서 db:5432로 PostgreSQL에 연결할 수 있다. 서비스 이름이 database였다면 database:5432가 된다. 이름이 애매하면 연결 설정을 볼 때마다 compose 파일을 다시 확인해야 한다.

실행 중인 컨테이너 확인

docker ps

NAMES 컬럼에 projectname-servicename-1 형태로 컨테이너 이름이 나온다. 로그를 볼 때는 서비스 이름으로 지정한다.

docker logs --tail=100 projectname-api-1

또는 compose 명령으로:

docker compose logs --tail=100 api

환경변수와 이름의 연결

서비스 이름이 결정되면 환경변수도 그에 맞게 쓴다.

DATABASE_URL=postgresql://user:pass@db:5432/mydb
REDIS_URL=redis://cache:6379

db, cache 같은 이름이 compose 파일의 서비스 이름과 정확히 일치해야 컨테이너 간 통신이 된다. 이름이 여러 군데 흩어져 있으면 한 쪽만 바꾸고 나머지를 빠뜨리는 실수가 생긴다.

포트 매핑 확인

docker inspect projectname-api-1 | grep -A5 'PortBindings'

어떤 포트가 호스트에 노출됐는지 확인할 때 쓴다. 컨테이너 내부 포트와 호스트 포트가 다른 경우 외부에서 접근할 때 혼동이 생길 수 있다.

이름을 정할 때 기준

• 기능 단위로 짧게: api, worker, db, cache, proxy
• 여러 DB가 있으면 구체적으로: db-main, db-analytics
• 이름에 환경(dev/prod)을 넣지 않는다 — 환경 구분은 compose 파일로 분리

이름 하나를 잘 정해두면 로그 확인, 환경변수 설정, 컨테이너 간 통신 설정이 전부 일관된다.