개요

MONGO-EXPRESS는 Node.js 기반의 웹 인터페이스를 통해 MongoDB 데이터베이스를 시각적으로 관리할 수 있는 오픈소스 도구입니다. Express.js와 Bootstrap을 활용하여 개발되었으며, 쿼리 실행, 컬렉션 관리, 문서 조작 등의 작업을 브라우저에서 간편하게 수행할 수 있어 개발 및 테스트 환경에 적합합니다.

본 문서에서는 MONGO-EXPRESS를 Docker를 이용해 컨테이너 형태로 배포하는 절차를 단계별로 설명합니다. 국내 네트워크 환경에서도 안정적인 이미지 다운로드를 위해 'xuanyuan.run' 미러 서비스를 활용하며, 기본 배포부터 Compose 기반 통합 구성, 보안 강화까지 포괄합니다.

사전 준비

Docker 엔진이 설치된 리눅스 서버가 필요합니다. 아래 명령어로 자동 설치 스크립트를 실행할 수 있습니다.

bash <(wget -qO- https://xuanyuan.cloud/docker.sh)

설치 후 버전 확인:

docker --version
docker compose version

이미지 다운로드

국내 접근성을 고려해 미러 주소를 사용하여 이미지를 가져옵니다.

docker pull xxx.xuanyuan.run/library/mongo-express:latest

다른 태그가 필요할 경우 latest 대신 1.0.0-alpha.4 등으로 변경 가능합니다. 정상 다운로드 여부는 다음 명령어로 확인합니다.

docker images | grep mongo-express

컨테이너 실행 방식

MONGO-EXPRESS는 오직 MongoDB 인스턴스에 연결하여 동작하므로, 백엔드 DB 설정과 연계해야 합니다.

기존 MongoDB에 연결

호스트 또는 원격 서버에 실행 중인 MongoDB가 있다면, 해당 정보를 환경 변수로 전달합니다.

docker run -d \
  --name me-container \
  -p 8081:8081 \
  -e ME_CONFIG_MONGODB_SERVER="your-mongodb-host" \
  -e ME_CONFIG_MONGODB_PORT="27017" \
  -e ME_CONFIG_MONGODB_AUTH_DATABASE="admin" \
  -e ME_CONFIG_MONGODB_AUTH_USERNAME="admin" \
  -e ME_CONFIG_MONGODB_AUTH_PASSWORD="securePass123" \
  xxx.xuanyuan.run/library/mongo-express:latest

Docker 네트워크를 통한 통합 배포

보안을 강화하기 위해 별도의 브리지 네트워크를 생성하고 두 컨테이너를 내부망에서 통신하도록 구성합니다.

1. 네트워크 생성:

docker network create db-tier

2. MongoDB 컨테이너 실행:

docker run -d \
    --name mongodb-server \
    --network db-tier \
    -e MONGO_INITDB_ROOT_USERNAME=rootuser \
    -e MONGO_INITDB_ROOT_PASSWORD=rootpass \
    xxx.xuanyuan.run/library/mongo:latest

3. MONGO-EXPRESS 컨테이너 실행 (동일 네트워크):

docker run -d \
    --name mongo-express-ui \
    --network db-tier \
    -p 8081:8081 \
    -e ME_CONFIG_MONGODB_SERVER=mongodb-server \
    -e ME_CONFIG_MONGODB_ENABLE_ADMIN=true \
    -e ME_CONFIG_MONGODB_ADMINUSERNAME=rootuser \
    -e ME_CONFIG_MONGODB_ADMINPASSWORD=rootpass \
    -e ME_CONFIG_BASICAUTH_USERNAME=uiuser \
    -e ME_CONFIG_BASICAUTH_PASSWORD=uipass123 \
    xxx.xuanyuan.run/library/mongo-express:latest

주요 환경 변수 목록

변수명	기본값	설명
ME_CONFIG_BASICAUTH_USERNAME	''	웹 UI 로그인 ID (비워두면 인증 비활성)
ME_CONFIG_BASICAUTH_PASSWORD	''	웹 UI 로그인 PW
ME_CONFIG_MONGODB_SERVER	mongo	MongoDB 호스트 주소 (여러 대일 경우 쉼표 구분)
ME_CONFIG_MONGODB_PORT	27017	접속 포트
ME_CONFIG_OPTIONS_EDITORTHEME	default	에디터 테마 (예: dracula, ambiance)
ME_CONFIG_SITE_SSL_ENABLED	false	HTTPS 활성화 여부

Docker Compose 활용 (권장)

서비스 간 의존성과 상태 관리를 쉽게 하기 위해 docker-compose.yml 파일로 통합 관리합니다.

version: '3.9'

services:
  mongodb:
    image: xxx.xuanyuan.run/library/mongo:latest
    container_name: app-mongodb
    environment:
      MONGO_INITDB_ROOT_USERNAME: rootuser
      MONGO_INITDB_ROOT_PASSWORD: rootpass
    volumes:
      - dbdata:/data/db
    networks:
      - internal-net
    healthcheck:
      test: ["CMD", "mongosh", "--eval", "db.ping()"]
      interval: 10s
      timeout: 5s
      retries: 10

  mongo-express:
    image: xxx.xuanyuan.run/library/mongo-express:latest
    container_name: app-me-ui
    depends_on:
      mongodb:
        condition: service_healthy
    ports:
      - "8081:8081"
    environment:
      ME_CONFIG_MONGODB_SERVER: mongodb
      ME_CONFIG_MONGODB_ADMINUSERNAME: rootuser
      ME_CONFIG_MONGODB_ADMINPASSWORD: rootpass
      ME_CONFIG_BASICAUTH_USERNAME: admin
      ME_CONFIG_BASICAUTH_PASSWORD: secure2024
      ME_CONFIG_OPTIONS_EDITORTHEME: dracula
    networks:
      - internal-net

volumes:
  dbdata:

networks:
  internal-net:
    driver: bridge

배포 명령:

docker compose up -d

기능 검증

1. 웹 접속 테스트: http://[서버IP]:8081 접속 후 인증 창에서 지정된 계정으로 로그인
2. 데이터베이스 목록 확인: 좌측 패널에 MongoDB 내 모든 DB가 표시되어야 함
3. 컬렉션 생성: 임의 DB 선택 후 새 컬렉션 생성 시도
4. 문서 조작: JSON 형식의 문서 삽입, 수정, 삭제 기능 확인
5. 인덱스 관리: 필드 기반 인덱스 생성 및 삭제 테스트

프로덕션 환경 적용 시 고려사항

MONGO-EXPRESS는 본래 개발용으로 설계되었으므로 프로덕션 사용은 권장되지 않지만, 불가피한 경우 다음 조치를 취해야 합니다.

• 외부 접근 제한: 방화벽 규칙으로 특정 IP 그룹만 허용

ufw allow from 10.0.1.0/24 to any port 8081

• SSL/TLS 적용: HTTPS를 강제하고 인증서 마운트

docker run ... \
    -p 8443:8081 \
    -e ME_CONFIG_SITE_SSL_ENABLED=true \
    -e ME_CONFIG_SITE_SSL_CRT_PATH="/certs/app.crt" \
    -e ME_CONFIG_SITE_SSL_KEY_PATH="/certs/app.key" \
    -v ./ssl:/certs \
    ...

• 최소 권한 원칙: 전용 MongoDB 사용자 생성 후 readWrite 권한만 부여
• 자동 재시작 및 모니터링: restart: unless-stopped 설정 및 Prometheus 연동
• 로그 외부 저장: 볼륨 마운트나 로깅 드라이버로 stdout 로그 수집

대체 도구 권장

운영 환경에서는 다음 도구 사용을 추천합니다:

• MongoDB Compass: 공식 GUI 클라이언트 (로컬 설치형)
• Studio 3T: 고급 쿼리 및 스케줄링 지원
• DBeaver: 오픈소스 멀티 DB 관리 도구

문제 해결

DB 연결 실패

• 네트워크 확인: docker exec me-container ping mongodb-server
• 환경 변수 검토: docker inspect me-container | grep MONGODB
• MongoDB 인증 상태 확인: --auth 옵션 활성화 여부

UI 접근 불가

• 컨테이너 상태 확인: docker ps, docker logs mongo-express-ui
• 포트 매핑 점검: docker port mongo-express-ui
• 방화벽 여부: ufw status 또는 iptables 확인

권한 거부 오류

MongoDB 내에서 사용자에게 충분한 역할(role)을 할당하세요.

use admin
db.grantRolesToUser("rootuser", [
  { role: "readWriteAnyDatabase", db: "admin" }
])