신기한 개발 경험: 파이썬 venv 가상환경과 도커(Docker) DB의 기막힌 동거

최근 소규모 공장 라인에 적용할 제조실행시스템(MES) 인프라를 한창 설계하고 있습니다. 가볍고 빠른 백엔드를 구축하기 위해 FastAPI를 선택했고, 데이터베이스로는 안정적인 PostgreSQL을 염두에 두고 개발을 진행 중인데요.

 

이 과정에서 꽤나 신기하고 흥미로운 기술적 경험을 하게 되어 기록으로 남겨봅니다. 바로 파이썬의 가상환경(venv)과 도커(Docker) 컨테이너라는 두 가지 서로 다른 '가상 공간'을 융합해 무적의 개발 인프라를 구축한 이야기입니다.

 

저처럼 현장 시스템 이관이나 백업, 환경 변수 꼬임으로 밤을 지새워본 경험이 있는 엔지니어 분들에게 좋은 인사이트가 되길 바랍니다.

 

AI협업: Docker와 AI에이전트 관계

1. 전역 변수(PATH)의 서열을 깨부수는 파이썬 venv의 마법

처음 파이썬을 설치할 때 보통 어디서나 실행할 수 있도록 'Add Python to PATH' 옵션을 체크해 환경 변수(전역 변수)를 설정하곤 합니다. 그런데 프로젝트마다 사용하는 라이브러리 버전이 다를 때 쓰는 가상환경(venv)을 켜면 이 전역 변수와 어떤 관계가 되는지 문득 궁금해졌습니다.

 

결론부터 말하면 가상환경을 활성화(Activate)하는 순간, 전역 변수는 완전히 무시되고 가상환경이 최우선 순위를 가집니다.

 

윈도우 시스템 내부적으로 activate.bat 스크립트가 실행되는 순간, 환경 변수 목록 맨 앞에 현재 가상환경의 주소를 강제로 끼워 넣는(Prepend) 원리더군요.

 

윈도우는 맨 앞에서부터 실행 파일을 찾기 때문에 전역 파이썬까지 내려가지 않고 가상환경 방 안의 파이썬을 먼저 실행하게 됩니다. deactivate를 치면 다시 원래 전역 경로가 1순위로 복귀합니다.

 

단, 가상환경은 무에서 유를 창조하는 게 아니라 '원본 파이썬 폴더'에서 핵심 엔진만 복사해 쓰는 방식이기 때문에, PC에 원본 파이썬 설치는 최초에 딱 한 번 무조건 필수라는 점도 다시금 정리하게 되었습니다.

2. 타 서버 이관과 복제의 종착지: .exe 빌드와 DB 가두기

가상환경의 진짜 위력은 시스템을 다른 서버로 이관할 때 나타납니다.

 

pip freeze > requirements.txt 명령어로 패키지 명세서만 달랑 들고 가면 새 서버에서 1분 만에 똑같은 환경을 재현할 수 있죠. (※ 주의: 가상환경 폴더째 복사하면 내부 절대 경로가 꼬여 에러가 납니다!)

 

하지만 여기서 한 걸음 더 나아가, 아예 PyInstaller를 통해 단일 실행 파일(.exe)로 빌드해 버리면 타 서버 이관 단계가 차원이 달라집니다.

 

새 PC에 파이썬을 깔 필요도, 가상환경을 잡을 필요도 없이 더블클릭 한 번으로 백엔드 API 서버가 구동되는 '설치가 필요 없는 시스템'이 완성되는 것이죠.

 

이렇게 인프라 껍데기를 가볍게 만들고 나니, 결국 진짜 보호해야 할 알맹이는 "DB(데이터베이스) 안의 생산 데이터"뿐이라는 결론에 도달했습니다. 그리고 이 DB를 완벽하게 관리하기 위해 만난 치트키가 바로 '도커(Docker)'였습니다.

3. "따로 설치 안 해도 된다고?" 윈도우 Pro와 도커의 신세계

윈도우 환경에 PostgreSQL이나 MS SQL을 직접 인스톨하면 제어판과 레지스트리가 지저분해지고, 이관할 때 백업도 번거롭습니다.

 

그런데 윈도우 Pro 위에 Docker Desktop을 깔고, docker-compose.yml이라는 메모장 명세서 한 장을 던져준 뒤 docker-compose up -d 명령어 한 줄을 쳤더니 신기한 일이 벌어졌습니다.

 

제가 직접 DB 설치 파일을 다운로드해서 인스톨하는 과정 자체가 완전히 사라진 것입니다.

 

도커가 알아서 인터넷 매장에서 정품 DB 상자를 배달 받아 내 PC 위에 격리된 가상의 방(컨테이너)을 만들고 DB 엔진을 즉시 구동해 주었습니다. 윈도우 제어판에는 흔적도 없는데 DB 서버가 완벽하게 살아 움직이는 것이죠.

 

심지어 DB 관리 툴인 pgAdmin 마저도 도커 안에 세트로 가두어 묶어버릴 수 있습니다. 이렇게 세트로 묶어두면 내 PC에 따로 프로그램을 깔지 않아도 크롬 브라우저에서 localhost:8080을 치는 것만으로 완벽한 DB 관리 창이 열립니다.

4. 종이 벽과 콘크리트 벽: 두 가상환경은 어떻게 통신할까?

여기서 가장 신기했던 점은, "내 PC의 파이썬 venv 가상환경"과 "도커 상자 안의 가상 DB 서버"라는 두 격리된 공간이 어떻게 서로 데이터를 주고받느냐는 것이었습니다.

 

원리는 윈도우 OS가 제공하는 네트워크 다리(Port)에 있었습니다.

• 파이썬 venv는 '종이 벽'입니다. 패키지 버전만 격리했을 뿐이라 윈도우 OS의 네트워크 기능을 그대로 씁니다.
• 도커(Docker)는 '콘크리트 벽'입니다. 완전히 가두어버리기 때문에 명세서에 ports: - "5432:5432"처럼 명시적으로 문(Port)을 열어주어야 합니다.

결국 파이썬 코드가 윈도우 OS를 향해 *"localhost:5432로 데이터 보내줘!"*라고 던지면, 윈도우 5432 포트 앞에 마중 나와 있던 도커 가상 네트워크가 이 신호를 낚아채 도커 상자 안의 PostgreSQL로 밀어 넣어 주는 메커니즘입니다.

 

덕분에 파이썬 코드에서는 DB가 도커 안에 있든 외부에 있든 코드를 단 한 줄도 바꿀 필요가 없습니다. .env 파일에 IP와 포트 주소록만 바꿔 끼우면 끝나는 유연함을 얻게 됩니다.

💡 경험을 통해 얻은 소규모 MES 구축 마스터 플랜

이번 경험을 통해 소규모 공장 현장에서 안심하고 발 뻗고 잘 수 있는 무적의 안정적인 인프라 설계도가 완성되었습니다.

1. 설계도 중심 개발: docker-compose.yml에 고정 버전(postgres:16)과 restart: always 옵션을 줘서 정전 시 자동 부활하는 짱짱한 DB 명세서를 잘 짜둔다.
2. AI 에이전트 활용: 안티그라비티(Anti-gravity)나 클로드 같은 AI에게 이 도커 명세서를 쥐여주고, 이에 딱 맞는 파이썬 venv 환경과 비동기 FastAPI 연결 코드를 짜달라고 리드한다. (Vibe Coding의 극대화)
3. 완벽한 이관 및 백업: 실제 데이터 창고를 윈도우 폴더(C:\mes\db_data)에 매핑(volumes)해두고, 하루 한 번 자동 추출 스크립트를 돌려 외부 NAS나 USB로 2중 백업한다.

인프라의 복잡한 구조를 소스코드가 몰라도 되게끔 딱 격리해 두니, 공장 서버가 통째로 고장 나도 "새 PC에 .exe 파일 하나 던지고 도커 폴더 복사해서 켜기"만 하면 10분 만에 완벽 복구되는 시스템을 설계할 수 있게 되었습니다.

 

5. 실전 docker-compose.yml 작성 시 꼭 넣어야 할 3대 필수 설정

1. restart: always (정전 및 윈도우 재부팅 대비)

공장 현장은 예기치 못한 정전이나 윈도우 업데이트로 인해 서버 PC가 꺼졌다가 켜지는 일이 종종 발생합니다.

• 명세서에 restart: always를 적어두면, 윈도우가 켜지면서 도커 데스크톱이 실행될 때 상자 안의 DB 서버도 사람 손을 타지 않고 자동으로 알아서 다시 구동됩니다. 현장 관리자가 출근해서 일일이 서버를 켜야 하는 번거로움을 원천 차단해 줍니다.

2. 고정된 버전 사용하기 (예: postgres:16 vs postgres:latest)

버전을 적을 때 latest(최신 버전)로 적어두면, 나중에 다른 PC에서 새로 구동할 때 도커가 그 시점의 가장 최신 버전(예: 미래의 버전 18 등)을 받아옵니다.

• 만약 버전이 대대적으로 업데이트되면 기존에 잘 돌아가던 파이썬 FastAPI 코드와 호환성이 깨져 에러가 날 수 있습니다.
• 따라서 명세서에는 반드시 postgres:16 이나 mssql/server:2022-latest 처럼 메이저 버전을 명확히 고정해 두어야 언제 어디서 띄우든 항상 똑같은 환경이 보장됩니다.

3. 명확한 외부 볼륨(volumes) 경로 지정

앞서 말씀드린 대로 도커 상자 안의 데이터 창고를 내 진짜 윈도우 폴더(C:\mes\db_data)로 연결해 두는 설정입니다.

• 이때 윈도우의 경로를 바탕화면이나 임시 폴더 같은 곳으로 잡지 마시고, 아예 C:\mes_system\ 처럼 MES 전용 루트 폴더를 하나 파서 깔끔하게 관리하시는 것이 백업 배치 파일을 짤 때나 나중에 폴더를 복사해서 이관할 때 백배 편해집니다.

 

앞으로 AI에게 명세서(.yml)를 짜달라고 할 때 꿀팁

이제 AI(클로드 등)에게 도커 설정을 요구하실 때, 그냥 "DB 도커 설정 짜줘"라고 하지 마시고 아래처럼 명확하게 조건을 던지시면 완벽한 코드를 한 방에 뽑아낼 수 있습니다.

"윈도우 Pro 환경에서 쓸 거고, PostgreSQL 16 버전이랑 웹 pgAdmin을 한 세트로 묶은 docker-compose.yml 짜줘. 실제 데이터는 C:\mes\db_data 폴더에 쌓이게 볼륨 설정해 주고, PC 재부팅 시 자동 시작되게 restart 옵션도 꼭 넣어줘."

 

 이렇게 하고, 명세서가 잘 만들어지면, 그것을 가지고 또 아래와 같이 AI 에이전트에게 지시를 하면 됩니다.

 

안티그라비티에게 던질 실전 지시문

내가 이번에 Windows Pro 환경에서 Nginx + FastAPI + PostgreSQL 조합으로 소규모 MES를 서비스하려고 해. DB는 도커로 띄울 거고, 설계해 둔 docker-compose.yml 내용은 아래와 같아. (여기에 아까 만든 docker-compose.yml 내용 붙여넣기) 이 명세서를 바탕으로 다음 작업을 진행해 줘. 파이썬 가상환경(venv)에서 사용할 requirements.txt 파일을 만들어줘. (FastAPI, Uvicorn, 그리고 도커 안의 PostgreSQL 16 버전과 비동기로 깔끔하게 통신할 수 있는 DB 라이브러리인 SQLAlchemy와 asyncpg를 꼭 포함해 줘.) 위의 도커 DB 주소록 환경변수를 안전하게 분리해서 읽어올 수 있도록 .env 파일 예시를 만들어줘. FastAPI 백엔드에서 이 도커 DB와 비동기로 연결 테스트(Ping)를 해볼 수 있는 가장 기초적인 main.py 샘플 코드를 짜줘."

 

이렇게 지시했을 때 얻는 효과

이렇게 도커 명세서를 먼저 주고 베뉴(가상환경) 세팅을 요구하면, AI가 다음과 같이 지능적으로 판단해서 코드를 짭니다.

• 정확한 라이브러리 매칭: 포스트그레스(PostgreSQL)에 붙어야 하니까, 파이썬 패키지를 엉뚱한 MySQL이나 Oracle 용으로 추천하지 않고 정확히 asyncpg나 psycopg2 같은 포스트그레스 전용 커넥터를 requirements.txt에 넣어줍니다.
  
  
• 배달 주소록 자동 일치: .env 파일이나 데이터베이스 연결 코드(DATABASE_URL)를 작성할 때, 내가 명세서에 적어둔 ID(mes_admin), 비밀번호(*************), 기본 포트(5432)를 귀신같이 읽어와서 파이썬 코드에 주소록을 그대로 자동 연동해 줍니다. 내가 일일이 숫자를 매칭할 필요가 없어집니다.

결국 여러분은 도커로 DB 서버 켜두고 ➔ 안티그라비티가 짜준 대로 베뉴 활성화해서 파이썬 코드 실행하면, 앉은 자리에서 단 5분 만에 '가상환경 백엔드'와 '가상환경 DB'가 서로 알아서 척척 신호를 주고받는 감동적인 순간을 보시게 될 겁니다.

인프라 설계도가 완벽하니 AI와의 협업 속도도 엄청나게 빨라질 것입니다. 아주 훌륭한 마스터 플랜입니다!

 

6. [초강추] 실전에서 무조건 쓰는 프로젝트 디렉토리(폴더) 구조

여러 가지 서비스를 한 대의 PC에서 개발하고 운영할 때, 폴더를 어떻게 짜야 나중에 유지보수와 백업, 서버 이관이 편할까요?

실전에서 99% 사용하는 정석 구조는 "상위 프로젝트 폴더 하나를 두고, 그 아래에 도커용과 베뉴(파이썬)용 폴더를 나란히 쪼개는 방식"입니다.

📂 가장 실질적인 MES 프로젝트 폴더 구조 예시

D:/mes/ (★ 프로젝트 전체를 아우르는 최상위 폴더) │ ├── 🐳 db/                              ➔ [도커/DB 구역] │   ├── docker-compose.yml       ➔ DB와 pgAdmin을 실행하는 명세서 파일 │   └── (db_data/)                   ➔ 실제 물리 데이터 파일이 쌓이는 곳 (자동 생성) │ ├── 🐍 backend/                    ➔ [파이썬 백엔드/베뉴 구역] │   ├── venv/                          ➔ 파이썬 가상환경 폴더 │   ├── requirements.txt         ➔ 파이썬 패키지 명세서 (FastAPI 등) │   ├── .env                            ➔ DB 접속 주소록 설정 파일 │   └── main.py                       ➔ FastAPI 실행 메인 코드 │ └── 🌐 frontend/                     ➔ [웹 화면 구역]     └── index.html                    ➔ 메인 화면 파일

 

🎯 왜 이렇게 나누는 게 좋을까?

1. AP(서비스)별 완벽한 독립: 나중에 다른 서비스(예: 재고관리 등)를 추가할 때도 D:/inventory/ 폴더를 따로 파서 똑같은 구조로 쪼개면 됩니다. 서로 절대 간섭하지 않아 안전합니다.
   
   
2. 배포와 이관의 초간단화: 나중에 개발이 끝나고 현장 서버 PC로 시스템을 통째로 옮길 때, 데이터가 쌓인 db_data/ 폴더만 쏙 빼고 이 껍데기 폴더 구조만 압축해서 새 PC로 들고 가면 이관이 단 10분 만에 끝납니다.
   
   
3. AI 에이전트(Claude 등) 활용 극대화: 최근 유행하는 AI 기반 '바이브 코딩(Vibe Coding)'을 할 때도 이 최상위 폴더를 AI에게 통째로 쥐여주면, AI가 구조를 직관적으로 이해하고 도커 설정과 파이썬 코드를 알아서 오차 없이 매칭해 줍니다.

🛠️ 개발 시작 전, 딱 한 번만 직접 준비할 것!

요즘 AI 에이전트(코워크 등)가 워낙 똑똑해서 권한만 주면 파이썬도 지가 알아서 다운받아 전역에 깔아주지만, 완벽한 자동화를 위해 주인님이 딱 한 번 마중물로 준비해 줘야 하는 것이 있습니다.

1. Docker Desktop 설치: 가상화 아파트 단지를 짓는 일입니다. 공식 홈페이지에서 다운받아 설치 후 컴퓨터를 꼭 재부팅해 주세요.
   
   
2. Python 엔진 설치 시 'PATH 추가' 체크: 만약 파이썬을 직접 까신다면, 설치 창 맨 밑에 있는 [ ] Add python.exe to PATH 체크박스를 무조건 체크하셔야 합니다. 그래야 AI가 윈도우 명령어를 내려 가상환경을 만들 수 있습니다.

이 두 가지만 딱 갖춰놓고 최상위 폴더 안에서 개발을 시작하면, 인프라나 환경 설정 때문에 스트레스받을 일이 99% 사라집니다.

 

이번에 Docker 라는 것을 알게되어, 예전에는 운영 서버를 꾸미려면, 윈도우에 각종 툴도 깔아주고, 환경 변수도 그 서버 환경에 맞게 변경해 줘야 하던 귀찮은 작업들을 가상화 환경에서 깔끔하게 마무리 할 수 있게 되었다. 

 

가상화 기술이 주는 이 깔끔함과 편리함, 정말 알면 알수록 신기하고 매력적입니다. 다음 포스팅에서는 안티그라비티와 협업해 실제로 FastAPI와 도커 DB를 엮는 실전 코딩 과정을 공유해 보겠습니다!