Docker Compose .env 파일 관리하기 : Intel N100 홈서버 환경 변수 운영 기준 정리

 

 

※ 이 글은 운영자가 직접 홈서버를 운영하면서 겪은 실험 경험과 Docker 공식 문서를 참고해 작성한 것입니다. 문장 정리와 구성에는 AI 보조 도구를 일부 사용했지만, 모든 내용은 운영자가 최종적으로 확인하고 검토했습니다.

Docker Compose .env 파일 관리하기 : Intel N100 홈서버 환경 변수 운영 기준 정리

도입

4주차 월요일에는 Docker 네트워크 구조를 정리했습니다. Bridge 네트워크, Host 네트워크, 그리고 Reverse Proxy가 각각 어떤 식으로 연결되는지 흐름을 직접 보면서, 서비스들이 어떤 경로로 서로 통신하는지 살펴봤습니다. 화요일에는 Docker Volume과 Bind Mount의 차이점을 비교해 보면서, 컨테이너 데이터가 실제로 어디에 저장되는지 확인해 볼 수 있었습니다.

수요일에는 Docker Compose에서 자주 사용하는 .env 파일과 환경 변수 관리 기준을 정리해보려 합니다. 네트워크가 서비스의 연결 구조이고, Volume과 Bind Mount가 데이터 저장 구조라면, .env 파일은 서비스 설정값을 관리하는 구조에 가깝습니다.

처음에는 Compose 파일에 포트나 경로, 시간대, 계정 정보 같은 설정을 직접 입력해도 큰 불편함을 느끼지 않았습니다. 그런데 서비스가 점점 늘어나고, 백업이나 복구까지 고민하게 되면, 이런 설정값들을 어디에 보관하고 어떻게 관리할지가 운영에서 정말 중요한 문제가 됩니다.

Intel N100 홈서버에서 Docker Compose .env 파일의 역할, 환경 변수 관리 기준, 백업 대상, 운영 구조를 정리한 다이어그램입니다.

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

본문

설정값이 Compose 파일 안에 흩어지기 시작했다

Docker Compose를 처음 사용할 때는 하나의 compose.yml 파일 안에 대부분의 설정을 직접 적어도 괜찮았습니다. 포트 번호, 시간대, 데이터 경로, 관리자 계정 같은 값이 많지 않다면 파일 하나로 전체 구조를 확인할 수 있기 때문입니다.

services:
  app:
    image: example/app:latest
    ports:
      - "8080:80"
    environment:
      - TZ=Asia/Seoul
      - APP_PORT=8080

하지만 서비스가 많아지면 이야기가 달라집니다. 포트와 데이터 경로, 도메인 같은 것들이 달라지고, API 토큰이나 비밀번호처럼 신경 써야 할 값도 하나둘 늘어납니다. 이런 값들이 Compose 파일 여기저기에 흩어져 있으면, 나중에 수정이나 백업할 때 챙겨야 할 부분이 많아져서 관리가 어려워집니다.

그래서 현재 Intel N100 홈서버 운영에서는 서비스 구조와 설정값을 분리하는 편이 더 관리하기 쉬웠습니다. Compose 파일은 서비스 구조를 설명하고, .env 파일은 바뀔 수 있는 설정값을 모아두는 역할로 보는 방식입니다.

.env 파일은 설정값을 모아두는 작은 운영 문서였다

.env 파일은 Compose에서 사용할 환경 변수 값을 정의하는 파일입니다. 예를 들어 시간대, 포트, 데이터 경로, 도메인 이름 같은 값을 별도 파일로 분리할 수 있습니다.

# .env 예시
TZ=Asia/Seoul
APP_PORT=8080
DATA_PATH=/opt/docker/app/data
DOMAIN=app.example.com

Compose 파일에서는 이 값을 변수 형태로 불러올 수 있습니다.

services:
  app:
    image: example/app:latest
    ports:
      - "${APP_PORT}:80"
    environment:
      - TZ=${TZ}
    volumes:
      - ${DATA_PATH}:/app/data

이렇게 하면 Compose 파일을 열었을 때는 서비스 구조를 보고, .env 파일을 열었을 때는 실제 운영 설정값을 확인할 수 있습니다. 이 구분은 서비스가 1~2개일 때보다 여러 개로 늘어났을 때 더 중요해졌습니다.

.env는 보안 도구가 아니라 설정 분리 도구였다

여기서 주의할 점이 있습니다. .env 파일에 비밀번호, API Key, 토큰 같은 민감한 값이 들어갈 수 있지만, .env 파일 자체가 보안을 제공하는 것은 아닙니다. 단순히 설정값을 분리해두는 파일이기 때문입니다.

• .env는 설정값을 한곳에 모아두는 데 유용합니다.
• 하지만 파일 접근 권한이 열려 있으면 민감정보가 노출될 수 있습니다.
• 공개 Git 저장소에 올리면 안 됩니다.
• 백업에는 포함하되, 백업 위치와 접근 권한을 따로 관리해야 합니다.
• 공유용 예시는 .env.example처럼 민감정보를 제거한 파일로 분리하는 편이 좋습니다.

따라서 운영 관점에서는 .env를 “비밀을 안전하게 숨기는 도구”가 아니라, “설정값을 분리하고 추적하기 쉽게 만드는 운영 파일”로 이해하는 편이 정확했습니다.

Compose와 .env의 역할을 나누니 구조가 보이기 시작했다

4주차의 흐름을 연결해보면 Docker 운영 구조는 조금 더 명확해졌습니다. 월요일에 정리한 network는 서비스의 연결 구조였고, 화요일에 정리한 volume과 bind mount는 데이터 저장 구조였습니다. 수요일의 .env는 설정값 관리 구조였습니다.

compose.yml
↓
서비스 구조

.env
↓
설정값

volume / bind mount
↓
데이터

network
↓
연결

이 역할 분리가 되면 나중에 문제가 생겼을 때 어디를 확인해야 할지 좁히기 쉬워집니다. 서비스가 실행되지 않으면 Compose 구조와 로그를 보고, 데이터가 사라진 것처럼 보이면 volume과 bind mount를 보고, 포트나 경로가 이상하면 .env 값을 확인하는 식입니다.

환경 변수 적용 여부는 docker compose config로 확인했다

.env 파일을 수정했는데 실제 Compose 구성에 반영되었는지 헷갈릴 때가 있습니다. 이때는 docker compose config 명령으로 Compose 파일이 최종적으로 어떻게 해석되는지 확인할 수 있습니다.

# Compose 설정 최종 해석 결과 확인
docker compose config

# 서비스 상태 확인
docker compose ps

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

docker compose config는 변수 치환 결과를 확인하는 데 도움이 됩니다. 예를 들어 ${APP_PORT}가 실제로 어떤 값으로 들어갔는지, ${DATA_PATH}가 어느 경로로 해석되었는지 확인할 수 있습니다.

운영 환경에서는 .env 수정 후 바로 서비스를 재시작하기보다, 먼저 config 결과를 확인하는 편이 더 안전했습니다. 특히 포트, 데이터 경로, 볼륨 연결 값이 들어 있는 경우에는 이 확인 과정이 중요했습니다.

.env 파일 위치와 이름도 운영 기준에 포함했다

Compose는 기본적으로 현재 작업 디렉터리의 .env 파일을 참조하는 흐름으로 사용되는 경우가 많습니다. 따라서 어느 디렉터리에서 명령을 실행하는지, Compose 파일과 .env 파일이 같은 기준으로 관리되는지가 중요했습니다.

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

위 구조처럼 서비스 그룹별로 Compose 파일과 .env 파일을 함께 두면, 해당 서비스의 구조와 설정값을 한 디렉터리 안에서 확인할 수 있습니다. 다만 동일한 변수명을 여러 디렉터리에서 사용할 경우에는 어느 서비스의 값인지 헷갈리지 않도록 문서화가 필요했습니다.

백업할 때 .env 파일은 빠지면 안 됐다

3주차 백업 정리와 연결해보면, .env 파일은 반드시 백업 기준에 포함해야 할 운영 파일이었습니다. Compose 파일만 백업하고 .env 파일을 빠뜨리면, 나중에 복구할 때 포트, 경로, 시간대, 계정 관련 값이 누락될 수 있습니다.

# Compose 파일과 .env 파일 확인
ls -la /opt/docker/automation

# 백업 대상 예시
compose.yml
.env
data/
backup-script.sh

하지만 .env 파일에 민감정보가 포함될 수 있으므로, 백업 위치와 접근 권한은 더 조심해야 했습니다. 백업에는 포함하되 공개 저장소나 공유 폴더에는 그대로 두지 않는 방향이 안전했습니다.

현재 Intel N100 홈서버 운영 기준

현재 Intel N100 홈서버에서는 .env 파일을 단순한 편의 기능으로 보기보다, 서비스 설정값을 모아두는 작은 운영 문서로 보고 있습니다. 특히 포트, 경로, 시간대, 도메인, 토큰처럼 바뀔 수 있는 값은 Compose 파일 내부에 흩어두기보다 분리하는 편이 관리하기 쉬웠습니다.

• compose.yml : 서비스 구조와 의존 관계 기록
• .env : 포트, 경로, 시간대, 도메인, 계정 관련 설정값 관리
• volume / bind mount : 실제 데이터 저장 위치 관리
• network : 서비스 연결 흐름 관리
• backup : compose.yml, .env, data 경로를 함께 보존

이 기준이 모든 상황에 꼭 들어맞는 정답은 아니에요. 그렇지만 작은 홈랩 환경에서 서비스를 하나씩 추가해 나갈 때는, 각 설정값을 분리해서 따로 기록하는 방법이 오랜 기간 운영하는 데 더 잘 맞았어요.

운영 로그

아래 표는 4주차 수요일 기준으로 정리한 Docker Compose .env 파일 점검 항목입니다. 실제 운영 기준은 서비스 종류, 보안 수준, 백업 방식, 저장소 구성에 따라 달라질 수 있습니다.

점검 항목	확인 방법	운영 판단
환경 변수 적용	docker compose config	변수 치환 결과 확인
.env 위치	Compose 실행 디렉터리 확인	서비스별 설정 파일 위치 문서화
민감정보	API Key, 토큰, 비밀번호 포함 여부	공개 저장소 업로드 금지
백업 대상	compose.yml + .env 함께 확인	복구 가능성을 위해 동시 보존
예시 파일	.env.example	공유용 파일에는 실제 민감값 제거

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

• Docker 서비스를 운영하다 보면 컨테이너보다 어떤 설정값으로 운영되는지가 중요해지는 순간이 왔습니다.
• .env 파일은 보안 도구가 아니라 설정값을 분리하고 추적하기 쉽게 만드는 운영 파일에 가까웠습니다.
• Compose 파일은 구조를 설명하고, .env 파일은 바뀔 수 있는 설정값을 관리하는 역할로 나누는 편이 좋았습니다.
• 백업과 복구를 생각하면 compose.yml과 .env 파일은 항상 함께 관리해야 했습니다.

참고 링크 (References)

1. Docker Compose environment variables
2. Docker Compose variable interpolation
3. docker compose config reference
4. Environment variables precedence in Docker Compose
5. Docker Compose services reference

트러블슈팅

문제: 컨테이너는 실행되지만 .env 파일에 적은 값이 적용되지 않는 것처럼 보임

Docker Compose에서 환경 변수가 적용되지 않는 것처럼 보일 때는 Compose 파일 문법만 볼 것이 아니라 .env 파일 위치, 변수명, 실행 디렉터리, 재적용 여부를 함께 확인해야 합니다.

확인: 변수명, 파일 위치, Compose 해석 결과, 서비스 재시작 여부를 순서대로 점검

# .env 파일 확인
cat .env

# Compose 설정 최종 결과 확인
docker compose config

# 서비스 상태 확인
docker compose ps

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

원인: .env 파일 위치가 다르거나, 변수명 오타가 있거나, Compose 설정을 변경한 뒤 서비스에 다시 반영하지 않음

해결: docker compose config로 최종 설정값을 확인하고, 필요한 경우 서비스를 재생성하거나 재시작

현재 구성에서는 .env를 수정한 뒤 바로 실행하기보다, 먼저 docker compose config로 해석 결과를 확인하는 편이 더 안정적이었습니다.

마무리

Docker Compose의 .env 파일을 정리하면서 느낀 점은, 설정값도 운영 자산이라는 것이었습니다. 컨테이너 이미지나 Compose 구조만 있어도 서비스가 완전히 복구되는 것은 아닙니다. 포트, 경로, 도메인, 시간대, 토큰 같은 값이 함께 있어야 실제 운영 상태를 다시 만들 수 있습니다.

.env 파일은 보안을 자동으로 보장해주는 도구는 아닙니다. 하지만 설정값을 분리하고, 기록하고, 백업 기준에 포함시키는 데는 매우 유용했습니다. 중요한 것은 편리함과 관리 책임을 함께 보는 것이었습니다.

이번 수요일의 결론은 단순합니다. 네트워크는 서비스의 연결 구조였고, Volume과 Bind Mount는 데이터 저장 구조였습니다. 그리고 .env 파일은 서비스 운영 규칙을 기록하는 설정 구조에 가까웠습니다.

목요일에는 이 흐름을 이어 받아 Docker 컨테이너의 업데이트 정책과, 이미지가 갱신되기 전과 후에 확인해야 할 기준들을 정리해볼 예정입니다.