Docker 입문 (환경 차이, 컨테이너, 온보딩)

Docker 입문

Docker가 "내 컴퓨터에서는 됐는데요" 문제를 완전히 해결해준다고 믿었습니다. 실제로 팀에 도입해보니 그 믿음은 절반만 맞았습니다. 환경 차이로 신규 팀원 온보딩에 하루를 꼬박 쓰던 팀이 한 시간 이내로 줄어든 건 사실이지만, Docker가 만들어낸 새로운 문제도 만만치 않았거든요.

환경 차이, 왜 이렇게 잡기 어려운 걸까

개발팀에서 가장 흔하게 듣는 말 중 하나가 "제 로컬에서는 분명히 됐는데요"입니다. 처음 몇 번은 그냥 웃어넘겼는데, 이게 반복되면 진짜 지칩니다. 저도 겪었고, 결국 그게 Docker를 직접 써보게 된 이유였습니다.

이 문제의 본질은 OS 버전, 라이브러리 버전, 환경변수처럼 눈에 잘 안 띄는 차이들이 쌓여서 터진다는 점입니다. A 개발자 맥북에는 Python 3.10이 깔려 있고, B 개발자 윈도우에는 3.9가 깔려 있으면, 분명히 같은 코드인데 한쪽에서만 패키지 의존성 오류가 납니다. 라이브러리 버전(library version)이란 특정 소프트웨어가 의존하는 외부 패키지의 세부 번호를 가리키는데, 이게 0.1만 달라져도 동작이 달라지는 일이 생각보다 흔합니다.

Docker는 이 문제를 컨테이너 이미지(container image)로 접근합니다. 컨테이너 이미지란 애플리케이션과 그 실행에 필요한 런타임, 라이브러리, 설정을 하나의 패키지로 묶은 것입니다. 어느 머신에서 실행하든 이미지 안의 환경은 동일하게 유지되니, 환경 차이로 생기는 문제를 원천적으로 줄일 수 있다는 논리입니다. Docker 공식 "Get Started" 가이드에서도 이 점을 컨테이너 기술의 핵심 가치로 내세웁니다(출처: Docker 공식 문서).

다만 "줄인다"와 "없앤다"는 다릅니다. 이 차이가 생각보다 큽니다.

요약: 환경 차이 문제의 핵심은 OS·라이브러리 버전 불일치이며, Docker의 컨테이너 이미지는 이를 줄여주는 접근이지 완전히 없애주는 해법은 아닙니다.

 

컨테이너 도입기 — 알파인에서 슬림 데비안으로

제가 직접 Dockerfile과 docker-compose.yml을 처음 작성할 때 가장 막막했던 건 베이스 이미지 선택이었습니다. 검색해보면 "가벼운 이미지를 쓰라"는 말이 많아서, 처음에는 알파인 리눅스(Alpine Linux) 기반 이미지를 골랐습니다. 알파인 리눅스란 약 5MB 수준의 초경량 리눅스 배포판으로, Docker 이미지 크기를 줄이는 데 자주 활용됩니다.

그런데 이게 예상 밖이었습니다. 일부 Python 패키지가 컴파일 단계에서 계속 실패하는 겁니다. 알파인은 표준 C 라이브러리(glibc) 대신 musl libc를 사용하는데, 이 차이 때문에 네이티브 확장이 필요한 패키지들이 제대로 빌드되지 않는 경우가 있습니다. 결국 슬림 데비안(slim Debian) 기반 이미지로 바꾸고 나서야 안정적으로 돌아갔습니다. 슬림 데비안이란 데비안 리눅스에서 불필요한 패키지를 제거한 경량 버전으로, 알파인보다는 크지만 일반 Python 패키지와의 호환성이 훨씬 좋습니다.

Dockerfile을 잡고 나서는 docker-compose.yml로 DB, Redis, 백엔드 서버를 한 파일에 정의했습니다. docker-compose란 여러 컨테이너를 하나의 YAML 파일로 선언하고 함께 실행·관리하는 도구입니다(출처: Docker Compose 공식 문서). 이렇게 구성하니 신규 팀원은 저장소를 클론하고 터미널에서 딱 한 줄만 치면 됐습니다.

docker compose up 한 줄이 바꾼 것들

온보딩 시간이 하루에서 한 시간 이내로 줄어든 건 수치로도 체감이 됐습니다. 그 전까지는 신규 팀원마다 "어떤 버전을 설치해야 하나요?", "DB 설정은 어디서 바꾸나요?" 질문이 슬랙에 수십 개씩 올라왔는데, compose 파일 하나로 그 질문들이 거의 사라졌습니다.

아래는 compose 파일에 묶어둔 서비스 구성입니다.

• PostgreSQL DB 컨테이너 — 버전 고정, 초기화 스크립트 포함
• Redis 캐시 컨테이너 — 메모리 제한 설정 포함
• Python 백엔드 서버 컨테이너 — 슬림 데비안 기반 이미지 사용
• .env 파일로 환경변수 주입 — 민감 정보는 이미지에 포함하지 않음

요약: 알파인 대신 슬림 데비안 이미지를 선택하고, docker-compose로 서비스를 묶으면 온보딩 시간을 하루에서 한 시간 이내로 줄일 수 있었습니다.

 

온보딩은 빨라졌는데, 새 문제가 생겼다

Docker가 환경 차이 문제를 없애준다는 의견도 있는데, 저는 조금 다르게 봅니다. 정확히는 기존 문제를 줄여주는 대신 새로운 종류의 문제를 몇 가지 만들어냅니다.

가장 먼저 부딪힌 건 윈도우 팀원의 줄바꿈 문자 문제였습니다. 윈도우는 줄바꿈에 CRLF(캐리지 리턴 + 라인 피드)를 쓰고, 리눅스 컨테이너는 LF(라인 피드)만 인식합니다. CRLF란 윈도우 시스템에서 텍스트 파일의 줄 끝을 표시하는 두 문자 조합(\r\n)으로, 리눅스 환경에서 실행되는 셸 스크립트가 이 문자를 그대로 읽으면 명령어로 인식하지 못하고 오류를 냅니다. 이걸 잡는 데 생각보다 시간이 많이 들었고, 결국 .gitattributes 파일에 줄바꿈 정책을 명시하는 방식으로 해결했습니다.

또 하나는 M1/M2 맥 팀원이 들어오면서 터진 아키텍처 충돌이었습니다. 인텔 CPU 기준으로 빌드된 이미지가 ARM 기반의 애플 실리콘에서 그대로 안 돌아가는 경우가 있었습니다. 멀티 플랫폼 빌드(multi-platform build)로 해결이 가능하긴 한데, 이걸 설정하는 것 자체가 Docker를 처음 쓰는 팀원한테는 진입 장벽이 됩니다. 이렇게 보면 Docker는 기존 "내 컴퓨터에서는 됐는데요" 문제를 줄이는 대신, 볼륨 마운트 권한, 네트워크 설정, 아키텍처 차이 같은 새로운 층위의 문제를 만들어내기도 합니다.

솔직히 이건 예상 밖이었습니다. Docker를 도입하기 전에 팀 규모와 사용 환경을 먼저 따져보는 게 맞다고 생각합니다. 1인 개발이거나 배포 구조가 단순한 작은 프로젝트라면, Docker는 오히려 오버엔지니어링(over-engineering)이 될 수 있습니다. 오버엔지니어링이란 문제의 복잡도에 비해 과도한 기술적 해결책을 적용하는 것을 가리키는데, 설정 비용과 학습 곡선이 실제 효익을 넘어서는 순간 역효과가 납니다.

요약: Docker는 기존 환경 문제를 줄이지만, CRLF 충돌·아키텍처 차이 같은 새로운 문제를 만들기도 하며, 작은 프로젝트에서는 오버엔지니어링이 될 수 있습니다.

 

자주 묻는 질문

Q. Docker 쓰면 진짜 "내 컴퓨터에서는 됐는데요" 문제가 없어지나요?

A. 완전히 없어진다고 보기는 어렵습니다. OS 수준의 환경 차이는 크게 줄어들지만, 호스트 아키텍처(M1 vs 인텔), 볼륨 마운트 권한, 줄바꿈 문자 같은 새로운 층위의 문제가 생길 수 있습니다. "없애준다"보다는 "줄여준다"는 표현이 더 정확합니다.

 

Q. 알파인 리눅스 이미지랑 슬림 데비안 이미지 중에 뭘 써야 하나요?

A. Python처럼 네이티브 확장이 필요한 패키지를 쓰는 프로젝트라면 슬림 데비안 쪽이 안정적입니다. 알파인은 이미지 크기는 작지만 musl libc 호환성 문제로 특정 패키지가 빌드에 실패하는 경우가 생길 수 있습니다. 제 경험상 이 차이를 먼저 확인하고 선택하는 게 낫습니다.

 

Q. docker-compose는 언제 쓰는 게 좋을까요?

A. DB, 캐시, 백엔드처럼 서비스가 두 개 이상 엮이는 구조일 때 효과가 분명합니다. 단일 서버 하나만 돌리는 상황이라면 Dockerfile 하나로도 충분하고, compose를 굳이 쓰면 오히려 복잡도만 올라갈 수 있습니다.

 

Q. 윈도우 팀원이 있을 때 Docker 쓰면 꼭 문제가 생기나요?

A. 줄바꿈 문자(CRLF/LF) 문제는 꽤 자주 등장합니다. 미리 .gitattributes 파일에 줄바꿈 정책을 설정해두면 대부분 예방이 됩니다. 사전에 팀 공통 Git 설정을 맞춰두는 게 나중에 디버깅 시간을 아끼는 가장 빠른 방법입니다.

 

결론

Docker는 분명히 쓸 만한 도구입니다. 제가 직접 써봤을 때 온보딩 시간이 하루에서 한 시간 이내로 줄어든 건 수치로 확인된 효과였고, 팀 규모가 어느 정도 이상이면 도입 효과가 명확하게 느껴집니다. 다만 "쓰면 모든 환경 문제가 사라진다"는 기대는 조금 내려놓는 게 좋습니다.

컨테이너 이미지 선택, 아키텍처 호환성, 줄바꿈 문자 처리처럼 새롭게 신경 써야 할 부분이 생기고, 이걸 처음 접하는 팀원에게는 학습 곡선이 분명히 존재합니다. 결국 Docker가 적합한지는 프로젝트 복잡도와 팀 규모를 먼저 따져보고 결정하는 것이 맞다고 봅니다. 작게 시작하고 싶다면 docker-compose로 로컬 개발 환경만 먼저 통일해보는 것이 좋은 첫 걸음이 될 수 있습니다.

참고: Docker 공식 문서 "Get Started" 가이드 (docs.docker.com) / Docker Compose 공식 문서 (docs.docker.com/compose)