"제 컴퓨터에서는 됐는데요." PART 01에서 만난 이 문제가, 배포 단계에서 다시 찾아옵니다. 개발 PC에서 잘 돌던 시스템이 서버에서는 라이브러리 버전이 달라 멈추는 것입니다. 이 장에서는 환경을 통째로 박제해 어디서나 똑같이 돌게 만드는 세 단계, environment.yml·conda-lock·Docker를 다룹니다.
1단계 — environment.yml
PART 01 Ch05에서 만든 그 파일입니다. 이 책의 실습 환경 전체가 한 파일에 담겨 있습니다.
# 파일: environment.yml (이 책의 실제 환경)name: facechannels: - conda-forgedependencies: - python=3.11 - "opencv=4.*" - "dlib>=20" - pip - pip: - face_recognition - deepface - insightface - onnxruntime - mediapipe - ultralytics - tf-keras받는 쪽은 한 줄로 같은 환경을 복원합니다.
conda env create -f environment.ymlconda activate faceconda로 깐 것(opencv·dlib)과 pip으로 깐 것이 한 파일에 모두 담겨 있어, 이 파일만 있으면 개발·서버·동료 PC가 같은 출발선에 섭니다. 이 책 전체를 관통한 "conda 먼저, pip 나중"의 원칙이 이 파일에 그대로 박혀 있습니다.
2단계 — conda-lock으로 못 박기
environment.yml은 "무엇을 원하는가"를 적지만, 설치 시점에 호환되는 최신 버전을 가져오므로 시점에 따라 미세하게 달라질 수 있습니다. 운영 서버처럼 완전히 동일한 버전이 필요하면 conda-lock으로 못 박습니다(PART 01 Ch05).
pip install conda-lockconda-lock -f environment.yml # 모든 버전을 고정한 잠금 파일 생성conda-lock install -n face conda-lock.yml잠금 파일은 모든 패키지의 정확한 버전을 OS별로 고정합니다. 몇 달 뒤에 깔아도 글자 하나 다르지 않은 환경이 재현되어, "어제는 됐는데 오늘 갑자기" 같은 사고를 막습니다.
3단계 — Docker로 통째로 담기
가장 확실한 재현은 운영체제까지 포함해 통째로 담는 Docker입니다. 환경을 이미지 하나로 만들어, 도커가 도는 곳이면 어디서나 동일하게 실행합니다.
# 파일: DockerfileFROM continuumio/miniconda3WORKDIR /appCOPY environment.yml .RUN conda env create -f environment.yml # 환경 구성# 모델 가중치를 빌드 단계에 미리 받아 둔다(오프라인 서버 대비)RUN conda run -n face python -c "from insightface.app import FaceAnalysis; \ FaceAnalysis(name='buffalo_l').prepare(ctx_id=-1)"COPY . .# face 환경 안에서 서버 실행 (PART 10의 FastAPI)CMD ["conda", "run", "--no-capture-output", "-n", "face", \ "uvicorn", "access_api:app", "--host", "0.0.0.0", "--port", "8000"]빌드 단계의 RUN 한 줄이 핵심입니다. InsightFace buffalo_l 가중치를 이미지에 미리 받아 두면, 인터넷이 차단된 서버에서도 첫 요청이 멈추지 않습니다. DeepFace 등 다른 가중치도 같은 방식으로 미리 받아 둘 수 있습니다.
빌드와 실행은 다음과 같습니다.
docker build -t face-system .docker run -p 8000:8000 face-systemcontinuumio/miniconda3 베이스 이미지로 시작해 environment.yml로 환경을 만들고, PART 10의 FastAPI 서버를 띄웁니다. 이 이미지를 그대로 다른 서버로 옮기면, conda·pip 설치 과정 없이 즉시 동일하게 돕니다.
세 단계의 선택
| 방법 | 재현 강도 | 적합 |
|---|---|---|
| environment.yml | 보통 | 개발·협업 공유 |
| conda-lock | 강함 | 버전 고정이 중요한 운영 |
| Docker | 가장 강함 | 서버 배포·여러 환경 |
학습·협업이라면 environment.yml로 충분하고, 운영 서버 배포라면 Docker가 가장 안전합니다. 셋은 단계적으로 강해지므로, 필요에 따라 위로 올라가면 됩니다.
실무 팁. 얼굴 시스템 배포에서 자주 빠뜨리는 것이 모델 가중치입니다. environment.yml·Docker는 라이브러리는 담지만, InsightFace의 buffalo_l이나 DeepFace 가중치 같은 모델 파일은 첫 실행에 다운로드됩니다(PART 06·07). 인터넷이 차단된 서버라면 이미지에 모델까지 미리 포함하거나,
~/.insightface·~/.deepface폴더를 함께 복사해야 합니다. 라이브러리만 챙기고 모델을 잊으면 배포 후 첫 요청에서 멈춥니다.
이 장에서 기억할 것
재현 가능한 배포는 environment.yml(원하는 패키지)·conda-lock(버전 고정)·Docker(OS까지 통째로)의 세 단계로 강해집니다. 이 책의 environment.yml은 conda+pip 환경 전체를 한 파일에 담아 conda env create로 복원하고, Docker는 miniconda 베이스에 그 환경과 FastAPI 서버를 담아 어디서나 동일하게 실행합니다. 단, 모델 가중치는 별도로 챙겨야 오프라인에서도 동작합니다. 다음 장에서는 직접 만드는 대신 완성된 서비스를 셀프호스트하는 배포 옵션, CompreFace를 살펴봅니다.