로컬에서 프로젝트(PDFMASK) 서비스를 Docker로 실행하는 방법

https://github.com/newkimjiwon/PDF_MASK_V2

GitHub - newkimjiwon/PDF_MASK_V2

 

Django · Celery · Redis 기반 멀티컨테이너 환경 설명

PDFmask 프로젝트는 PDF 마스킹, OCR 기반 텍스트 분석, PPT·DOCX 변환 등의 기능을 제공하는 Django 기반 웹 서비스입니다.
이 서비스는 단순한 Django 서버만으로 동작하지 않고, Celery Worker(백그라운드 연산 처리기) 와 Redis 메시지 브로커가 함께 실행되어야 전체 기능이 완성됩니다.

아래에서는 PDFmask의 로컬 개발 환경을 Docker로 구성한 docker-compose.yml 파일을 설명하고, 실제로 어떻게 동작하는지 정리하였습니다.

추가로, PDFmask를 실행하기 위해서는 .env 파일이 반드시 필요하며, 이 파일이 저장소(GitHub)에는 포함되어 있지 않기 때문에 외부 사용자가 소스 코드를 내려받더라도 그대로는 실행할 수 없다는 점을 명확히 알려드립니다.

 

1. PDFmask Docker 구성 개요

PDFmask는 총 3개의 주요 서비스가 함께 동작해야 정상적으로 기능을 수행합니다.

• Django Web Server(Gunicorn)
• Redis (Celery 메시지 큐)
• Celery Worker (PDF/OCR 비동기 처리)

Docker Compose를 사용하면 이 세 가지 서비스를 한 번의 명령으로 실행할 수 있습니다.

 

서비스 구성 흐름도

         web (Django + Gunicorn)
                │
                │  Celery Task
                ▼
              Redis
                │
                ▼
       celery_worker (PDF/OCR 처리)

Django는 사용자 요청을 받아 처리하고, 시간이 오래 걸리는 연산 작업은 Celery로 전달하여 Redis 큐를 거쳐 Worker가 실행하는 구조입니다.

 

2. docker-compose.yml 파일 설명

아래는 실제 PDFmask의 docker-compose.yml 전체 코드입니다.

version: '3.8'

services:
  # 1. Django Web Service (HTTP 요청 처리)
  web:
    build: .
    env_file:
      - .env
    # Gunicorn Timeout 5분 설정 유지
    command: gunicorn pdfuploader.wsgi:application --bind 0.0.0.0:8000 --timeout 300
    volumes:
      - .:/app
      - shared_data:/tmp/celery_jobs
    ports:
      - "127.0.0.1:8000:8000"
    # Web 서비스에 restart 정책 추가
    restart: on-failure
    depends_on:
      redis:
        condition: service_healthy
    networks:
      - default
    environment:
      - JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64


  # 2. Redis Message Broker Service (Celery Broker)
  redis:
    image: redis:6-alpine
    container_name: redis
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 1s
      timeout: 3s
      retries: 5
      start_period: 5s
    ports:
      - "6379:6379"
    networks:
      default:
        aliases:
          - redis_host
          - redis_master

  # 3. Celery Worker Service (OCR/PDF 연산 수행)
  celery_worker:
    build: .
    env_file:
      - .env
    command: celery -A pdfuploader worker -l debug
    volumes:
      - .:/app
      - shared_data:/tmp/celery_jobs
    depends_on:
      redis:
        condition: service_healthy
    networks:
      - default
    environment:
      - JAVA_HOME=/usr/lib/jvm/java-17-openjdk-amd64
networks:
  default:
    name: pdf_mask_v2_default_net
volumes:
  shared_data:

여러분이 GitHub 저장소에서 이 파일을 내려받더라도, .env 파일이 없으면 Django 서버와 Celery는 환경 변수를 읽을 수 없기 때문에 정상적으로 실행되지 않습니다.
즉, 개발자가 별도로 .env 파일을 만들어야만 이 Docker 환경을 실제로 구동할 수 있습니다.

 

3. 서비스별 상세 설명

1) web (Django + Gunicorn)

Django 프로젝트를 Gunicorn 서버로 실행하며, 사용자의 웹 요청을 처리합니다.

주요 특징은 다음과 같습니다.

• Gunicorn 실행 방식으로 운영 환경과 동일하게 작동
• Redis가 정상적으로 실행되어야 컨테이너 시작
• shared volume을 통해 Celery Worker와 파일 공유
• PPT·DOCX → PDF 변환을 위해 JAVA_HOME 설정 필수
• 포트를 127.0.0.1로 바인딩하여 로컬 외부에서는 접근 불가

2) redis (메시지 브로커)

Redis는 Celery 작업 큐 역할을 담당합니다.

• Celery가 보낸 작업을 저장하고 Worker에게 전달
• ping 기반의 healthcheck로 정상 상태 확인
• Django와 Worker가 “redis_host”라는 이름으로 접근 가능

3) celery_worker (PDF/OCR 연산 처리)

Celery Worker는 오래 걸리는 작업을 대신 처리합니다.

• PDF 마스킹
• OCR 분석
• PDF 이미지 변환
• 대용량 파일 처리

Django의 /tmp/celery_jobs 디렉터리와 공유되어 파일을 읽고 저장할 수 있습니다.

 

4. Volume(볼륨) 구조

shared_data:/tmp/celery_jobs

이 볼륨은 Django와 Celery Worker가 PDF 파일을 공유하기 위해 사용됩니다.

예시 흐름은 다음과 같습니다.

1. 사용자가 PDF 업로드
2. Django가 /tmp/celery_jobs에 저장
3. Celery Worker가 같은 경로에서 파일을 읽고 처리
4. 처리된 파일을 Django가 다시 사용자에게 반환

이 구조가 없으면 서로 파일을 공유할 수 없어 PDF 마스킹 기능이 동작하지 않습니다.

 

5. 네트워크 구성

pdf_mask_v2_default_net

모든 서비스가 동일 네트워크에 있어 다음과 같이 이름으로 서로 접근할 수 있습니다.

• Django → redis:6379
• Worker → redis:6379
• Django → worker(간접적으로 Celery를 통해 호출)

네트워크 문제 없이 안정적인 통신이 가능해집니다.

 

6. 실행과 종료 방법

실행(저는 구버전을 사용해서 -가 붙어 있습니다. 신버전은 -이게 없을 겁니당)

docker-compose up -d

 

실행 중인 컨테이너 확인

docker ps

 

로그 확인

docker compose logs -f web
docker compose logs -f celery_worker
docker compose logs -f redis

 

정상 종료

docker-compose down

 

재시작

docker-compose up -d

 

7. 이 Docker Compose의 의미

이 docker-compose.yml 파일은 PDFmask 서비스를 로컬 환경에서 운영 환경과 유사하게 구성하여 테스트할 수 있도록 만든 개발용 환경입니다.

• Django, Redis, Celery Worker가 자동 연결
• 파일 공유와 백그라운드 작업 흐름을 완전 재현
• 운영 배포 전 기능 검증 가능

단, 외부 사용자는 .env 파일이 없으면 서비스를 실행할 수 없기 때문에 보안상 안전하게 공개해도 문제 없습니다.

필요하시면 운영 배포용 구성(docker-compose.prod.yml) 또는 Nginx/HTTPS 기반 구성도 추가로 정리해 드리겠습니다.