[HomeLabs] Docker Compose 2026 홈랩 멀티컨테이너 완전 가이드: Compose v5 실전 설정

목차

• 홈랩에서 Docker Compose가 정말 빛나는 순간
• Docker Compose란 뭔가요? — 쉽게 말해서
• 2026년 Docker Compose 최신 버전 현황
• 홈랩 환경 준비 — 제 실제 서버 스펙 공개
• Docker Engine 설치 확인
• 실전 구현 — 홈랩 멀티컨테이너 스택 구성하기
• 1단계: 디렉터리 구조 잡기
• 2단계: 환경변수 파일(.env) 설정
• 3단계: 메인 compose.yaml 작성
• 4단계: Traefik 설정 파일 작성
• 5단계: 스택 실행
• ⚠️ 삽질 모음 — 제가 겪은 트러블슈팅
• 문제 1: "network proxy not found" 에러
• 문제 2: Nextcloud 설치 후 "신뢰할 수 없는 도메인" 에러
• 문제 3: 컨테이너 시작 순서 문제 (depends_on과 healthcheck)
• 문제 4: 볼륨 권한 문제
• 2026년 Docker Compose 신기능 — Watch 모드와 Profiles
• Profiles — 환경별 선택적 실행
• Watch 모드 — 개발 환경에서 파일 변경 자동 감지
• 2026년 중반 이후 체크포인트 — include, develop, OCI artifact
• 결과 확인 — 홈랩 모니터링 대시보드
• 서비스 접속 URL 정리
• 자주 묻는 질문 (FAQ)
• Q. Docker Compose와 Kubernetes(쿠버네티스) 중 홈랩엔 뭐가 낫나요?
• Q. compose.yaml 파일을 여러 개로 나눌 수 있나요?
• Q. 서버 재부팅 시 자동으로 컨테이너가 시작되나요?
• 마무리 — 그래서 뭘 배웠냐고요?

홈랩에서 Docker Compose가 정말 빛나는 순간

혹시 이런 경험 있으신가요? 홈서버에 이것저것 서비스를 올리다 보니 어느 순간 컨테이너가 10개, 20개를 넘어서고, docker run 명령어를 매번 손으로 치고 있는 자신을 발견하는 그 순간. 저도 그랬거든요. Plex, Jellyfin, Nextcloud, Pi-hole, Traefik까지 올라가면 그때부터는 홈서버 자동화가 안 되어 있으면 관리가 급격히 귀찮아집니다.

그때 Docker Compose를 제대로 파고들기 시작했는데, 2026년 7월 기준으로는 예전 감각으로 접근하면 놓치는 포인트가 꽤 많습니다. 특히 이제는 단순히 컨테이너를 묶어 올리는 수준을 넘어, compose.yaml 하나로 멀티컨테이너 운영, 선택 실행, 개발 워크플로, 원격 배포 흐름까지 정리할 수 있게 됐습니다. 이 글에서는 제가 직접 홈랩에 적용하면서 겪은 삽질과 노하우를 최대한 실전 위주로 정리해 보겠습니다.

Docker Compose란 뭔가요? — 쉽게 말해서

쉽게 말하면 여러 개의 컨테이너를 하나의 프로젝트처럼 선언하고, 한 번에 올리고 내리고 관리하게 해 주는 도구입니다. 웹 서비스, 데이터베이스, 리버스 프록시, 캐시, 모니터링 도구를 각각 따로 실행하는 대신, compose.yaml 파일에 정의해 두고 docker compose up -d 한 번으로 관리하는 방식이죠.

중요한 점은 이제 예전의 docker-compose 독립 실행 파일 기준으로 생각하면 안 된다는 겁니다. 홈랩에서 지금 기준으로 권장되는 방식은 Docker CLI 플러그인 형태의 docker compose를 쓰는 것입니다. 구형 docker-compose v1 계열은 사실상 레거시 취급이라, 새로 홈서버를 꾸민다면 굳이 그쪽으로 갈 이유가 없습니다.

2026년 Docker Compose 최신 버전 현황

이전 글에서는 Docker Compose 2.29.2를 최신으로 적어 두었지만, 그 정보는 이제 맞지 않습니다. 2026년 7월 기준 공개된 최신 Docker Compose 릴리스는 v5.1.4입니다. 공식 릴리스 공개일은 2026년 5월 20일이었고, 현재는 v2 계열과 v5 계열 문서가 함께 언급되는 구간이라 버전 표기를 혼동하기 쉽습니다.

실제로 여러분 서버에 설치된 버전은 Docker Desktop 채널이나 Linux 플러그인 패키지 반영 시점에 따라 다를 수 있으니, 아래 명령으로 먼저 확인하시는 걸 추천드립니다.

docker compose version

그리고 한 가지 더. 예전 예제에서 흔히 보이던 version: "3.8" 같은 최상위 버전 필드는 이제 사실상 obsolete입니다. 최신 Compose는 해당 숫자에 맞춰 동작하는 게 아니라 Compose Specification을 기준으로 가장 최신 스키마를 해석합니다. 홈랩용 새 파일을 작성할 때는 version 필드를 굳이 넣지 않는 쪽이 더 깔끔합니다.

홈랩 환경 준비 — 제 실제 서버 스펙 공개

제 기준 홈랩은 저전력 미니 PC 한 대와 NAS 스토리지를 조합한 구성입니다. CPU가 아주 강력하지 않아도 Compose 기반 운영에는 큰 문제가 없지만, 메모리는 생각보다 중요합니다. 특히 Nextcloud, DB, 리버스 프록시, 모니터링 스택까지 같이 돌리면 16GB 아래에서는 금방 답답해질 수 있습니다.

운영체제는 Ubuntu Server 계열이 가장 무난했고, 저장소는 서비스 데이터와 설정 파일을 분리해 두는 게 관리가 훨씬 편했습니다. 홈랩 운영에서 중요한 건 최고 사양보다도 복구하기 쉬운 구조입니다.

Docker Engine 설치 확인

먼저 Docker Engine과 Compose 플러그인이 제대로 설치되어 있는지 확인합니다. 둘 다 있어야 최신 문법과 기능을 안정적으로 활용할 수 있습니다.

docker --version
docker compose version

여기서 docker compose 명령이 없다면 예전 독립형 바이너리만 설치된 경우일 수 있습니다. 2026년 홈서버 구축 기준으로는 이 부분부터 정리해 두는 게 좋습니다.

실전 구현 — 홈랩 멀티컨테이너 스택 구성하기

이번 예시는 제가 홈랩에서 자주 쓰는 전형적인 조합입니다. Traefik으로 라우팅하고, Nextcloud를 올리고, 필요한 경우 DB와 Redis를 묶는 형태죠. 핵심은 서비스가 늘어나도 구조가 무너지지 않게 디렉터리와 환경변수를 먼저 정리하는 겁니다.

1단계: 디렉터리 구조 잡기

homelab/
├── compose.yaml
├── .env
├── traefik/
│   ├── traefik.yml
│   └── acme/
├── nextcloud/
│   └── data/
└── postgres/
    └── data/

폴더 구조는 심플할수록 좋습니다. 나중에 백업하거나 서비스를 통째로 옮길 때도 이 구조가 큰 힘을 발휘합니다.

2단계: 환경변수 파일(.env) 설정

DOMAIN=home.example.com
TZ=Asia/Seoul
POSTGRES_DB=nextcloud
POSTGRES_USER=nextcloud
POSTGRES_PASSWORD=change-me
NEXTCLOUD_TRUSTED_DOMAINS=cloud.home.example.com

민감한 값은 .env로 분리해 두는 게 기본입니다. 특히 홈랩에서는 여러 서비스를 빠르게 복제하다 보면 패스워드를 YAML에 하드코딩하는 실수를 자주 하게 되는데, 초반부터 습관을 잡아 두는 편이 낫습니다.

3단계: 메인 compose.yaml 작성

name: homelab

services:
  traefik:
    image: traefik:v3.4
    container_name: traefik
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - ./traefik/traefik.yml:/etc/traefik/traefik.yml:ro
      - ./traefik/acme:/acme
    networks:
      - proxy

  db:
    image: postgres:17
    container_name: nextcloud-db
    restart: unless-stopped
    environment:
      POSTGRES_DB: ${POSTGRES_DB}
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
    volumes:
      - ./postgres/data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"]
      interval: 10s
      timeout: 5s
      retries: 5
    networks:
      - internal

  nextcloud:
    image: nextcloud:31
    container_name: nextcloud
    restart: unless-stopped
    depends_on:
      db:
        condition: service_healthy
    environment:
      POSTGRES_DB: ${POSTGRES_DB}
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_HOST: db
      TZ: ${TZ}
    volumes:
      - ./nextcloud/data:/var/www/html
    labels:
      - traefik.enable=true
      - traefik.http.routers.nextcloud.rule=Host(`cloud.home.example.com`)
      - traefik.http.routers.nextcloud.entrypoints=websecure
      - traefik.http.routers.nextcloud.tls=true
    networks:
      - proxy
      - internal

networks:
  proxy:
    external: true
  internal:
    driver: bridge

여기서 포인트는 세 가지입니다. 첫째, 최상위 version 필드를 넣지 않았습니다. 둘째, depends_on에 service_healthy를 붙여 시작 순서를 좀 더 현실적으로 맞췄습니다. 셋째, 프로젝트 이름은 name으로 명시해 두면 폴더명이 바뀌어도 네트워크와 리소스 이름이 덜 흔들립니다.

4단계: Traefik 설정 파일 작성

api:
  dashboard: true

entryPoints:
  web:
    address: ":80"
  websecure:
    address: ":443"

providers:
  docker:
    exposedByDefault: false

certificatesResolvers:
  letsencrypt:
    acme:
      email: admin@example.com
      storage: /acme/acme.json
      httpChallenge:
        entryPoint: web

홈랩에서 Traefik은 여전히 강력합니다. 특히 Docker 레이블만으로 라우팅을 붙일 수 있어서 서비스가 늘어나도 유지보수가 비교적 편합니다. 다만 HTTPS 인증서 발급을 위해서는 외부 DNS, 포트 개방, 도메인 설정이 먼저 정상이어야 합니다.

5단계: 스택 실행

docker network create proxy
docker compose up -d

처음 띄울 때는 docker compose logs -f로 로그를 같이 보는 걸 권장합니다. 특히 홈랩 멀티컨테이너 구성에서는 한 서비스만 실패해도 전체가 정상처럼 보여서 초반 진단이 꼬이는 일이 많습니다.

⚠️ 삽질 모음 — 제가 겪은 트러블슈팅

실전에서는 YAML 문법보다도 네트워크, 권한, DNS, 초기 기동 순서에서 더 많이 막힙니다. 아래는 제가 실제로 자주 겪었던 문제들입니다.

문제 1: "network proxy not found" 에러

외부 네트워크를 선언해 놓고 미리 생성하지 않으면 자주 나는 에러입니다. 위 예시처럼 external: true를 썼다면 반드시 먼저 만들어야 합니다.

docker network create proxy

문제 2: Nextcloud 설치 후 "신뢰할 수 없는 도메인" 에러

이건 Nextcloud 쪽 신뢰 도메인 설정이 빠졌을 가능성이 큽니다. 리버스 프록시 뒤에서 운영할 때는 실제 접속 도메인을 정확히 반영해야 합니다. 홈서버에서 도메인을 자주 바꾸는 분들은 이 부분이 특히 잘 꼬입니다.

문제 3: 컨테이너 시작 순서 문제 (depends_on과 healthcheck)

요즘도 많이 착각하는 부분인데, depends_on만으로는 애플리케이션이 완전히 준비된 상태까지 보장되지 않습니다. 홈랩에서 DB를 붙이는 서비스는 healthcheck와 함께 쓰는 편이 훨씬 안정적입니다.

문제 4: 볼륨 권한 문제

리눅스 홈서버에서는 여전히 가장 흔한 문제입니다. 컨테이너 사용자 UID/GID와 호스트 디렉터리 권한이 안 맞으면 정상 기동처럼 보여도 실제 쓰기가 실패합니다. 새 서비스를 추가할 때는 데이터 폴더 권한부터 확인하세요.

2026년 Docker Compose 신기능 — Watch 모드와 Profiles

이 섹션은 2026년 7월 기준으로 다시 보면 더 의미가 커졌습니다. 홈랩 그 자체는 운영 환경이지만, 설정 파일을 자주 만지거나 자체 서비스도 같이 운영한다면 Compose의 개발 보조 기능이 생각보다 유용합니다.

Profiles — 환경별 선택적 실행

profiles는 특정 서비스만 골라서 띄우고 싶을 때 정말 편합니다. 예를 들어 평소에는 모니터링만 상시 운영하고, 테스트용 Adminer나 디버깅 도구는 필요할 때만 켜는 식으로 관리할 수 있습니다.

services:
  adminer:
    image: adminer
    profiles:
      - debug

docker compose --profile debug up -d

홈랩에서는 리소스가 한정적이기 때문에, 이런 선택 실행 기능이 생각보다 체감이 큽니다.

Watch 모드 — 개발 환경에서 파일 변경 자동 감지

Compose Watch는 여전히 유효하고, 현재 공식 기준으로는 Docker Compose 2.22.0 이상에서 사용할 수 있습니다. 즉, 문서와 예제가 섞여 보여도 핵심은 develop.watch 문법을 이해하는 것입니다.

services:
  app:
    build: .
    develop:
      watch:
        - path: ./app
          action: sync
          target: /app
        - path: package.json
          action: rebuild

실행은 아래처럼 합니다.

docker compose up --watch

운영 서버에서 직접 쓸 기능은 아니지만, 홈랩에서 대시보드나 내부 툴을 직접 개발하는 분이라면 꽤 생산성이 좋습니다.

2026년 중반 이후 체크포인트 — include, develop, OCI artifact

이전 버전 글에는 없었지만, 지금 시점에서는 꼭 짚고 넘어가야 할 변화가 몇 가지 있습니다. 특히 규모가 조금만 커져도 Compose include와 원격 배포 흐름은 홈랩 구조를 훨씬 깔끔하게 만들어 줍니다.

첫 번째는 include입니다. Compose는 이제 여러 개의 Compose 파일을 더 모듈식으로 조합할 수 있고, 로컬 파일뿐 아니라 OCI artifact나 Git 저장소 기반 원격 소스도 포함할 수 있습니다. 홈서버에서 공통 인프라 스택과 개별 서비스 스택을 나눠 관리할 때 특히 유용합니다.

include:
  - ./stacks/monitoring.compose.yaml
  - oci://docker.io/username/my-compose-app:latest

두 번째는 develop 문법 정리입니다. 예전에는 Watch를 기능처럼만 이해했다면, 지금은 아예 develop 하위에 개발용 동작을 모으는 형태가 더 명확해졌습니다. 팀 단위로 홈랩 앱을 같이 관리한다면 이 문법이 유지보수에 유리합니다.

세 번째는 docker compose publish 기반의 OCI artifact 배포 흐름입니다. 공식 기준으로는 Docker Compose 2.34.0 이상에서 OCI artifact publish 기능을 사용할 수 있습니다. 아직 홈랩 필수 기능은 아니지만, 여러 서버에 동일한 스택을 재배포해야 하는 분들에게는 꽤 실용적입니다.

결과 확인 — 홈랩 모니터링 대시보드

정상적으로 구성이 끝나면 가장 먼저 확인할 건 세 가지입니다. 컨테이너 상태, 프록시 라우팅, 그리고 데이터 영속성입니다. 이 세 가지가 안정적이면 이후 서비스 추가는 훨씬 쉬워집니다.

서비스 접속 URL 정리

https://cloud.home.example.com
https://traefik.home.example.com

실제 운영에서는 URL 표를 따로 정리해 두는 걸 추천합니다. 홈랩이 길어질수록 어떤 서비스가 어느 포트와 어떤 도메인을 쓰는지 헷갈리기 시작하거든요.

자주 묻는 질문 (FAQ)

Q. Docker Compose와 Kubernetes(쿠버네티스) 중 홈랩엔 뭐가 낫나요?

대부분의 개인 홈랩이라면 아직도 Compose가 더 낫습니다. 쿠버네티스는 분명 강력하지만, 운영 복잡도까지 감당해야 합니다. 단일 서버나 소규모 홈서버 자동화라면 Compose가 훨씬 빠르고 현실적입니다.

Q. compose.yaml 파일을 여러 개로 나눌 수 있나요?

가능합니다. 여전히 -f 옵션 조합이 유효하고, 2026년 기준으로는 include까지 활용할 수 있어 더 구조적으로 나눌 수 있습니다. 인프라, 앱, 개발 오버라이드용으로 분리하면 관리가 편합니다.

Q. 서버 재부팅 시 자동으로 컨테이너가 시작되나요?

보통은 서비스별로 restart: unless-stopped를 설정해 두면 재부팅 후 자동으로 올라옵니다. 다만 외부 네트워크, 마운트 경로, 스토리지 준비 상태가 꼬이면 일부 서비스만 실패할 수 있으니 부팅 직후 로그 확인은 필요합니다.

마무리 — 그래서 뭘 배웠냐고요?

정리하면 이렇습니다. 2026년의 Docker Compose는 여전히 홈랩의 중심 도구이고, 예전보다 훨씬 성숙해졌습니다. 단순 실행 도구를 넘어서 compose.yaml 표준화, Compose Watch, Compose include, OCI artifact까지 이어지는 흐름이 만들어졌습니다.

제가 홈서버를 계속 만지면서 느끼는 건, 결국 오래 살아남는 구성은 화려한 구성보다 다시 띄우기 쉬운 구성이라는 점입니다. Docker Compose 2026 기준으로 홈랩을 정리하려는 분이라면, 지금이 구조를 한 번 정리하기 가장 좋은 타이밍입니다.

🔄 마지막 업데이트: 2026년 07월