Docker Compose 운영 구조 다시 정리하기 : Intel N100 홈서버 서비스 그룹화와 유지관리 흐름

 

 

※ 운영자가 직접 홈서버를 실험하면서 얻은 경험과 Docker 공식 문서를 참고해 이 글을 썼습니다. 글을 다듬는 과정에서 AI 도구의 도움을 일부 받았지만, 최종 내용은 운영자가 직접 꼼꼼하게 확인했습니다.

Docker Compose 운영 구조 다시 정리하기 : Intel N100 홈서버 서비스 그룹화와 유지관리 흐름

도입

2주차에는 Intel N100 홈서버에서 Proxmox VE와 Docker를 동시에 돌리면서, VM을 각각의 역할에 맞게 분리했습니다. 또 VT-x 지원 여부를 확인했고, 자동 재시작 정책이나 로그 관리, 그리고 모니터링 흐름 같은 기본적인 운영 방법도 정리해봤어요. 이제 3주차 월요일부터는 실제로 서비스가 하나씩 늘어나는 상황을 가정해서, Docker Compose를 활용한 운영 방식이 잘 돌아가는지 다시 점검해 보려고 합니다.

처음에는 하나의 compose.yml 파일 하나에 모든 서비스를 모아두는 것도 처음에는 크게 불편함이 없었어요. 그런데 Reverse Proxy나 n8n, Portainer, Jellyfin 같은 서비스들이 점점 늘고, 테스트용 컨테이너까지 추가되기 시작하면 상황이 달라집니다. 그때부터는 ‘어떤 서비스가 어느 볼륨을 사용하는지’, ‘환경 변수는 어디에 저장되어 있는지’, ‘업데이트할 때 영향을 받는 범위가 어디까지인지’ 같은 부분이 점점 더 신경 쓰이게 됩니다.

Docker Compose는 여러 컨테이너 서비스를 하나의 애플리케이션 단위로 정의하고 관리하는 도구입니다. 공식 Compose 파일 구조에서도 services, networks, volumes 같은 요소를 활용해 서비스 구성을 좀 더 선언적으로 관리할 수 있도록 안내했습니다. 이번 글에서는 이 구조를 Intel N100 홈서버 환경에 맞게 어떻게 정리하면 효과적인지, 직접 운영해 보며 느낀 점과 함께 정리해 보려고 합니다.

Intel N100 홈서버에서 Docker Compose 서비스 그룹, 환경 변수, volume, 업데이트 흐름을 운영 기준으로 정리한 구조입니다.

※ 다이어그램은 운영 환경 설계를 바탕으로 AI 도구를 활용해 제작했으며, 최종 구성과 내용은 운영자가 직접 검수했습니다.
출처: 디지털 장난감

본문

서비스가 늘어나면 Compose 파일도 운영 문서가 된다

Docker Compose를 처음 접하면 그저 여러 컨테이너를 한꺼번에 띄워주는 도구라고 생각하기 쉽습니다. 하지만 며칠 이상 홈서버를 직접 운영해 보면, Compose 파일이 단순히 실행만을 위한 것이 아니라, 전체 서비스 구조를 한눈에 보여주는 일종의 운영 매뉴얼이 된다는 사실을 알게 됩니다.

예를 들어 services에는 실행할 컨테이너의 이미지, 포트, 볼륨, 환경 변수, 재시작 정책 등을 미리 정해두면, 나중에 장애가 발생했을 때도 어떤 서비스가 어떤 경로를 사용하는지 쉽게 파악할 수 있습니다. 이렇게 구성이 명확하게 되어 있으면 문제 해결이 훨씬 수월해집니다.

services:
  portainer:
    image: portainer/portainer-ce:latest
    restart: unless-stopped
    ports:
      - "9443:9443"
    volumes:
      - portainer_data:/data
      - /var/run/docker.sock:/var/run/docker.sock

volumes:
  portainer_data:

위 예시는 구조 설명을 위해 간단히 든 것뿐입니다. 실제로 시스템을 운영할 때는 포트 개방 범위나 볼륨 위치, 관리자 계정, 네트워크 접근 범위 등을 사용하는 장비 환경에 맞춰 별도로 꼼꼼히 점검해야 합니다. 특히 /var/run/docker.sock 가 Docker를 제어하는 권한과 연결된 부분이기 때문에, 꼭 필요한지와 어느 정도까지 접근을 허용할지 충분히 고민해야 합니다.

하나의 compose.yml 에 몰아넣는 방식은 처음에는 편했다

처음에는 모든 서비스를 하나의 Compose 파일에 넣는 방식이 가장 단순했습니다. 파일 하나만 열면 전체 구조가 보이고, docker compose up -d 한 번으로 여러 서비스를 올릴 수 있었기 때문입니다.

# 현재 디렉터리의 compose 파일 기준으로 서비스 실행
docker compose up -d

# 서비스 상태 확인
docker compose ps

# 최근 로그 확인
docker compose logs --tail=100

docker compose up은 Compose 파일에 정의된 서비스를 생성하고 시작하는 명령입니다. -d 옵션을 사용하면 컨테이너를 백그라운드에서 실행할 수 있습니다. 이 방식은 초기 테스트 단계에서는 상당히 편했습니다.

하지만 홈서버를 운영할 때 모든 서비스를 반드시 하나의 관리 단위로 묶을 필요는 없었습니다. 예를 들어, Reverse Proxy는 외부 접속을 담당하는 핵심적인 계층이고, n8n은 자동화 작업을 처리하는 역할을 하며, Jellyfin은 미디어를 스캔할 때 시스템에 부담을 줄 수 있는 서비스입니다. 이런 다양한 특성을 가진 서비스들을 하나의 파일에서 모두 관리하게 되면, 업데이트나 장애가 발생했을 때 영향을 받는 범위가 불필요하게 넓어질 수 있습니다.

현재 구성에서는 서비스 그룹화가 더 관리하기 쉬웠다

Intel N100처럼 자원이 한정된 홈서버 환경에서는, 무작정 많은 서비스를 올리는 것보다 관리하기 쉬운 단위로 나누는 것이 더 중요하다고 느꼈습니다. 그래서 지금은 각 기능별로 Compose 디렉터리를 따로 구성하는 방법을 고민하고 있습니다.

/opt/docker/
├─ proxy/
│  ├─ compose.yml
│  └─ .env
├─ automation/
│  ├─ compose.yml
│  └─ .env
├─ media/
│  ├─ compose.yml
│  └─ .env
└─ test/
   ├─ compose.yml
   └─ .env

이 방법이 모든 상황에 꼭 맞는 정답이라고 할 수는 없습니다. 그래도 제가 홈서버를 운영하면서 경험한 바로는, 서비스별로 디렉터리를 나눠 관리하면 업데이트나 로그를 확인할 때 한결 수월했습니다. 서비스 성격이 다를 때 이렇게 구분해두면 필요한 작업 범위가 자연스럽게 좁혀지더라고요.

• proxy: Reverse Proxy, SSL, 외부 접속 관련 서비스
• automation: n8n 등 자동화 워크플로 서비스
• media: Jellyfin처럼 부하 변동이 있는 서비스
• test: 새 컨테이너를 시험하는 실험 영역

.env 파일은 편하지만 관리 책임도 함께 생긴다

Compose 환경에서는 환경 변수를 사용해 포트, 경로, 계정명, 도메인처럼 자주 바뀌거나 민감한 값을 따로 관리할 수 있습니다. 덕분에 Compose 파일에 이런 값들을 직접 입력할 필요가 없어, 보안 면에서도 더 안전하고, 설정을 변경할 때도 훨씬 편리해집니다.

# .env 예시
N8N_PORT=5678
TZ=Asia/Seoul
DATA_PATH=/opt/docker/automation/data

services:
  n8n:
    image: n8nio/n8n:latest
    restart: unless-stopped
    ports:
      - "${N8N_PORT}:5678"
    environment:
      - TZ=${TZ}
    volumes:
      - ${DATA_PATH}:/home/node/.n8n

다만 .env 파일은 편리한 만큼 관리에 주의가 필요합니다. 실제 서비스 계정이나 토큰, 비밀번호 등은 외부에 노출될 수 있으니 공개 저장소에는 올리지 않는 게 안전합니다. 백업에는 해당 파일을 포함하더라도, 외부에 공유할 때는 민감한 정보가 빠진 예시 파일을 따로 만들어 사용하는 것이 좋습니다.

Volume은 컨테이너보다 더 중요하게 봐야 했다

Docker 컨테이너는 언제든지 삭제하고 새로 만들 수 있지만, 서비스 데이터가 저장된 볼륨은 훨씬 더 신중하게 다뤄야 합니다. 특히 n8n 워크플로우, 리버스 프록시 설정, Portainer 데이터, 미디어 서버 설정 같은 경우에는 컨테이너 자체보다 데이터가 저장된 경로가 훨씬 더 중요했습니다. 이 데이터를 잃어버리면 서비스 전체를 다시 설정해야 할 수도 있어, 관리에 더욱 주의가 필요하다고 느꼈습니다.

# Docker 전체 사용량 확인
docker system df

# 볼륨 목록 확인
docker volume ls

# 특정 볼륨 정보 확인
docker volume inspect 볼륨이름

운영 환경에서는 docker system prune --volumes 같은 명령을 바로 실행하기보다, 어떤 볼륨이 실제 서비스 데이터인지 먼저 확인하는 편이 안전했습니다. 용량 정리보다 데이터 보존이 우선인 경우가 많기 때문입니다.

업데이트는 서비스 그룹별로 나누는 편이 안정적이었다

Docker 이미지를 업데이트하는 일은 겉으로 보기엔 쉬워 보여도, 실제 서비스 환경에서는 여러 가지를 신경 써야 합니다. 예를 들어, 서비스가 잠시 멈출 수 있고 설정이 바뀔 위험도 있습니다. 특히 자동화된 서비스나 외부에서 들어오는 연결이 있는 경우, 무작정 바로 업데이트하기보다는 먼저 현재 상태를 점검하고, 순서대로 천천히 진행하는 게 훨씬 안정적이었습니다.

# 현재 서비스 상태 확인
docker compose ps

# 이미지 업데이트 확인 및 다운로드
docker compose pull

# 변경된 이미지로 재생성
docker compose up -d

# 최근 로그 확인
docker compose logs --tail=100

docker compose pull은 서비스 이미지 다운로드에 사용하고, docker compose up -d는 필요한 컨테이너를 백그라운드로 생성 또는 재생성하는 흐름으로 이해했습니다. 중요한 것은 명령어를 외우는 것이 아니라, 실행 전후에 상태와 로그를 확인하는 습관이었습니다.

운영 명령어는 짧게, 확인 순서는 고정했다

홈서버를 운영하다 보면 명령어가 많아질수록 실수하기 쉬워집니다. 그래서 자주 쓰는 명령어는 되도록 짧게 만들고, 확인하는 순서도 항상 정해두는 것이 훨씬 실용적이었어요.

단계	명령어	확인 목적
상태 확인	docker compose ps	서비스 실행 상태 확인
로그 확인	docker compose logs --tail=100	최근 오류 흐름 확인
이미지 갱신	docker compose pull	최신 이미지 다운로드
서비스 반영	docker compose up -d	백그라운드 실행 및 재생성
용량 확인	docker system df	이미지·볼륨 누적 확인

운영 로그

아래 표는 3주차 월요일을 기준으로 Docker Compose의 운영 구조 점검 항목을 정리한 것입니다. 실제 디렉터리 구조와 서비스 분리 방식은 사용하는 장비의 성능이나 운영 목적, 그리고 백업 방법에 따라 다를 수 있습니다.

점검 항목	확인 기준	운영 판단
Compose 파일	서비스별 설정이 한눈에 보이는가	기능별 디렉터리 분리 검토
.env 파일	포트·경로·시간대 값이 분리되어 있는가	민감한 값은 공개 금지
Volume	서비스 데이터 위치가 명확한가	삭제 명령 전 반드시 확인
업데이트	서비스 그룹별로 반영 가능한가	전체 동시 업데이트보다 순차 적용
로그	서비스별 최근 로그 확인이 가능한가	장애 추적 기준 유지

에디터의 해석 노트 (Editor's Lab Note)

• Docker Compose는 단순 실행 도구가 아니라 홈서버 서비스 구조를 기록하는 운영 문서처럼 느껴졌습니다.
• Intel N100 환경에서는 서비스를 무조건 많이 올리는 것보다 관리 가능한 단위로 나누는 편이 더 현실적이었습니다.
• .env 파일과 volume은 편리하지만, 백업과 보안 측면에서 별도 관리 기준이 필요했습니다.
• 업데이트는 빠르게 진행하는 것보다 상태 확인, pull, up, 로그 확인 순서로 천천히 진행하는 쪽이 안정적이었습니다.

참고 링크 (References)

1. Docker Compose file reference
2. Docker Compose services reference
3. docker compose up reference
4. docker compose ps reference
5. docker compose logs reference

트러블슈팅

문제: Docker 서비스가 늘어나면서 어느 서비스가 어떤 설정과 데이터를 사용하는지 헷갈리기 시작함

홈서버를 처음 시작할 때는 Compose 파일 하나만으로도 충분했습니다. 그런데 서비스가 점점 늘어나면서 포트나 볼륨, 환경 변수, 로그 위치 등이 여기저기 섞이게 되었고, 덕분에 장애가 발생하면 어디서 문제가 생겼는지 확인해야 할 부분도 많아졌습니다.

확인: 서비스 그룹, Compose 파일, .env, volume 경로를 함께 점검

# 서비스 상태 확인
docker compose ps

# 최근 로그 확인
docker compose logs --tail=100

# Docker 용량 확인
docker system df

# 볼륨 목록 확인
docker volume ls

원인: 서비스 수가 늘었지만 Compose 구조와 데이터 경로를 운영 단위로 정리하지 않음

해결: proxy, automation, media, test처럼 서비스 성격에 따라 디렉터리와 Compose 파일을 분리하고, .env와 volume 경로를 명확히 기록

현재 방식에서는 각 서비스를 완전히 분리하기보다는, 장애를 확인하고 업데이트가 필요한 부분만 따로 관리할 수 있을 정도로만 나누는 게 더 현실적이고 효율적이었습니다.

마무리

Intel N100 홈서버에서 Docker Compose를 사용할 때는 처음에는 “서비스 실행”에 초점을 두게 마련이지만, 시간이 흐르면 “구조 정리”의 중요성이 점점 커집니다. 각 서비스가 어떤 파일과 볼륨, 환경 변수를 사용하는지 확실하게 정리해 두면, 나중에 문제가 생겼을 때나 업데이트할 때 훨씬 더 쉽게 대응할 수 있습니다. 이런 기록이 쌓이면 서버 관리가 한결 편해집니다.

이번 3주차 월요일의 결론은 아주 간단합니다. Compose 파일은 단순히 명령어를 실행하는 용도가 아니라, 홈서버의 서비스 구조를 기록하고 운영 흐름을 정리하는 데 쓰는 것이 훨씬 더 안정적이었습니다.

화요일에는 이 구조를 기반으로 홈서버 백업 자동화 과정을 정리해볼 생각입니다. 특히 Compose 파일, .env, 볼륨, 그리고 서비스 데이터 디렉터리를 어떤 기준으로 백업할지에 대해서도 이어서 다뤄보겠습니다.