NetBox Docker: 공식 커뮤니티 컨테이너 프로젝트를 사용하면 NetBox 애플리케이션, worker, housekeeping, PostgreSQL, 캐시를 Docker Compose로 일관되게 배포할 수 있습니다. 그러나 예제 구성을 그대로 인터넷에 노출하거나 latest 태그, admin/admin 계정, ALLOWED_HOSTS=*를 사용하면 재현성과 보안이 크게 약해집니다.

이 가이드는 2026년 7월 기준 NetBox Docker 5.0.1과 NetBox 4.6 계열의 호환 조합을 예로 듭니다. 운영 배포는 검증한 저장소 태그와 이미지 태그를 함께 고정하고, TLS 리버스 프록시·secret 관리·PostgreSQL 및 미디어 백업·복원 테스트·단계적 업그레이드를 하나의 운영 절차로 다뤄야 합니다.

NetBox Docker 보안 배포: 애플리케이션, 작업자, 데이터베이스, 캐시, TLS와 백업 구성
외부 접근, NetBox 서비스 계층, 영구 데이터와 암호화 백업을 분리한 Compose 운영 구조

NetBox Docker 구성 요소와 데이터 경계

구성 요소 역할 영속성·노출 원칙
netbox 웹 UI·REST API 애플리케이션 리버스 프록시 뒤에서만 접근
netbox-worker 백그라운드 작업 처리 외부 포트 불필요
netbox-housekeeping 정리·주기 작업 외부 포트 불필요
PostgreSQL NetBox의 정본 데이터 전용 volume, 외부 미노출, 일관된 백업 필수
Valkey/Redis 계열 캐시·작업 큐 외부 미노출, 비밀번호·네트워크 제한
media volume 업로드 이미지·첨부 파일 DB와 같은 복구 시점으로 백업
TLS reverse proxy HTTPS 종료·접근 제어 공개가 필요한 유일한 진입점
NetBox Docker는 NetBox Community의 공식 설치 프로그램 자체가 아니라 커뮤니티가 관리하는 별도 프로젝트입니다. 운영팀이 Docker·Compose·PostgreSQL 복구와 릴리스 노트를 책임질 수 있을 때 선택하십시오.

NetBox Docker 버전 호환과 고정

NetBox Docker 5.0.1 릴리스는 NetBox 4.6.x 이상과 호환된다고 명시돼 있습니다. 저장소의 지원 파일과 컨테이너 이미지 태그가 서로 맞아야 하므로 저장소만 업데이트하거나 이미지만 latest로 당겨서는 안 됩니다. 공식 프로젝트도 운영 환경에 NetBox 버전과 지원 파일 버전이 함께 포함된 태그를 권장합니다.

호스트 도구 버전 확인

docker --version
docker compose version
git --version
openssl version

검증할 저장소 릴리스 고정

sudo install -d -o "$USER" -g "$USER" -m 0750 /opt/netbox
cd /opt/netbox
git clone --branch 5.0.1 --depth 1   https://github.com/netbox-community/netbox-docker.git netbox-docker-5.0.1
cd netbox-docker-5.0.1
git describe --tags --always
git status --short

설치 시점의 공식 릴리스 페이지에서 태그와 호환 범위를 다시 확인합니다. 장기 운영에서는 테스트한 NetBox 패치 버전까지 포함한 이미지 태그 또는 이미지 digest를 고정하고 변경 관리 문서에 기록합니다.

NetBox Docker 배포 전 안전 설계

  • CentOS 7은 지원 종료됐으므로 새 운영 배포의 기반으로 사용하지 않습니다.
  • DB·캐시 포트는 호스트나 외부 네트워크에 publish하지 않습니다.
  • NetBox 포트는 우선 127.0.0.1에만 바인딩하고 HTTPS 프록시를 통해 제공합니다.
  • 실제 FQDN만 ALLOWED_HOSTS에 넣고 와일드카드 별표를 사용하지 않습니다.
  • 관리자 계정은 대화형으로 만들며 비밀번호를 compose 파일이나 Git에 넣지 않습니다.
  • DB와 media를 같은 복구 시점으로 되돌릴 수 있는 백업·복원 runbook을 먼저 만듭니다.

배포 디렉터리 권한

cd /opt/netbox/netbox-docker-5.0.1
umask 077
cp docker-compose.override.yml.example docker-compose.override.yml
chmod 0600 docker-compose.override.yml
find env -type f -exec chmod 0600 {} \;

강한 secret 생성

umask 077
openssl rand -base64 48
openssl rand -base64 32

# 출력값은 승인된 비밀 저장소 또는 Compose secrets 파일에 저장하고
# 셸 기록·Git·티켓 본문에는 남기지 않습니다.

프로젝트에서 제공하는 예제 환경 파일의 변수명과 secrets 지원 방식을 해당 릴리스 문서에서 확인하십시오. 서로 다른 용도의 SECRET_KEY, PostgreSQL 비밀번호, 캐시 비밀번호를 재사용하지 않습니다.

NetBox Docker: Compose override와 네트워크 노출

초기 검증에서는 웹 포트를 loopback에만 바인딩합니다. 아래 override는 개념 예시이므로 5.0.1 저장소에 포함된 example 파일과 병합 결과를 비교한 뒤 사용합니다. 데이터베이스와 캐시에는 ports 항목을 추가하지 않습니다.

services:
  netbox:
    ports:
      - "127.0.0.1:8000:8080"
    restart: unless-stopped

Compose 병합 결과와 이미지 확인

docker compose config --quiet
docker compose config --images
docker compose config > /tmp/netbox-compose.rendered.yml

# 출력에 latest, 0.0.0.0 공개 포트, DB·캐시 포트가 없는지 검토
grep -nE 'latest|0\.0\.0\.0|5432:|6379:' /tmp/netbox-compose.rendered.yml
렌더링된 Compose 파일에는 secret 값이 포함될 수 있습니다. 검토 파일은 권한 0600으로 만들고 확인 후 안전하게 삭제하며, CI 로그나 이슈에 첨부하지 마십시오.

NetBox Docker 이미지 수집과 첫 실행

이미지를 먼저 받고 digest 기록

docker compose pull
docker compose images
docker image ls --digests | grep -E 'netbox|postgres|valkey'
docker compose config --images > deployed-images.txt
chmod 0600 deployed-images.txt

서비스 시작과 상태 점검

docker compose up -d
docker compose ps
docker compose logs --tail=200 netbox
docker compose logs --tail=100 netbox-worker
curl -fsS http://127.0.0.1:8000/ >/dev/null

컨테이너가 running이라는 사실만으로 애플리케이션이 준비됐다고 판단하지 않습니다. 마이그레이션 완료, PostgreSQL 연결, worker 시작, HTTP 응답, 로그인과 대표 API 조회를 모두 확인합니다.

NetBox Docker: 초기 관리자와 ALLOWED_HOSTS

원문처럼 SUPERUSER_PASSWORD=admin을 환경 파일에 저장하면 컨테이너 검사, 백업, Git 이력, 로그에서 비밀번호가 노출될 수 있습니다. 첫 실행 뒤 공식 관리 명령으로 관리자를 대화형 생성하고, 임시 SUPERUSER_* 변수를 사용했다면 즉시 제거합니다.

docker compose exec netbox   /opt/netbox/netbox/manage.py createsuperuser

ALLOWED_HOSTS에는 실제 서비스 FQDN을 명시하고 TLS 리버스 프록시가 전달하는 Host 헤더와 일치시킵니다. 외부에 노출하기 전 HTTPS, 신뢰할 수 있는 proxy 헤더, 접근 제어, 세션 쿠키 정책과 관리자 MFA/SSO를 검토합니다.

NetBox Docker: PostgreSQL과 media 백업

NetBox의 핵심 정본은 PostgreSQL이지만 업로드 파일은 media volume에 있습니다. DB 덤프만 있으면 이미지·첨부가 누락되고, volume 스냅샷만 있으면 PostgreSQL 일관성을 보장하기 어렵습니다. 동일한 변경 창에서 두 자산과 설정·이미지 목록을 묶어 암호화 보관합니다.

PostgreSQL 논리 백업

BACKUP_DIR="/var/backups/netbox/$(date +%F-%H%M%S)"
sudo install -d -m 0700 "$BACKUP_DIR"
sudo chown "$USER":"$USER" "$BACKUP_DIR"

docker compose exec -T postgres   pg_dump -U netbox -d netbox -Fc   > "$BACKUP_DIR/netbox.pgdump"

pg_restore --list "$BACKUP_DIR/netbox.pgdump" | head

실제 volume 이름과 마운트 지점 확인

docker compose volumes
docker volume ls
docker inspect "$(docker compose ps -q netbox)"   --format '{{json .Mounts}}' | jq .

media volume은 사용 중인 스토리지 드라이버에 맞는 스냅샷 또는 승인된 백업 도구로 보관합니다. 파일 복사 방식이라면 쓰기 중 변경을 제어하고 권한·소유권·심볼릭 링크를 보존하십시오. 백업은 별도 호스트에 암호화 전송하고 체크섬을 기록합니다.

백업 무결성 파일 생성

cp docker-compose.override.yml "$BACKUP_DIR/"
cp deployed-images.txt "$BACKUP_DIR/"
find "$BACKUP_DIR" -type f -print0 | sort -z |   xargs -0 sha256sum > "$BACKUP_DIR/SHA256SUMS"

(cd "$BACKUP_DIR" && sha256sum -c SHA256SUMS)
백업 성공은 명령의 종료 코드가 0인 것만으로 증명되지 않습니다. 격리된 스테이징 Compose 프로젝트에 DB와 media를 복원하고 로그인, 객체 수, 첨부 파일, API 조회까지 정기적으로 검증하십시오.

NetBox Docker 안전한 업그레이드

업그레이드는 git pull과 latest 이미지 교체가 아닙니다. 릴리스 노트에서 NetBox, NetBox Docker, PostgreSQL, Valkey의 호환성과 중간 버전 요구사항을 확인해야 합니다. 특히 NetBox Docker 4.0.0은 애플리케이션 서버를 Granian으로 바꾸고 PostgreSQL 18·Valkey 9로 올린 큰 변경이므로 오래된 설치에서 단순 재시작해서는 안 됩니다.

  1. 현재 저장소 tag, 이미지 digest, NetBox 버전, DB 버전을 기록합니다.
  2. DB·media·설정 백업을 만들고 격리 환경에서 복원합니다.
  3. 목표 릴리스 노트와 공식 업데이트 문서에서 지원되는 버전 경로를 확인합니다.
  4. 새 디렉터리에 목표 저장소 tag를 준비하고 로컬 override만 검토해 이식합니다.
  5. Compose 병합·이미지·secret·포트를 검증한 뒤 스테이징에서 마이그레이션을 실행합니다.
  6. 운영 변경 창에서 배포하고 UI·API·worker·로그·데이터를 확인합니다.

현재 버전과 데이터베이스 기록

git describe --tags --always
docker compose images
docker compose exec -T netbox   /opt/netbox/venv/bin/python /opt/netbox/netbox/manage.py version
docker compose exec -T postgres psql -U netbox -d netbox   -Atc 'select version();'

새 릴리스의 변경 전 검증

docker compose config --quiet
docker compose pull
docker compose up -d
docker compose ps
docker compose logs --since=10m | grep -Ei 'error|traceback|failed'
스키마 마이그레이션 뒤에는 이전 이미지로만 되돌리는 롤백이 안전하지 않을 수 있습니다. 롤백이 필요하면 문서화된 역방향 경로가 없는 한 변경 전 DB·media·설정 세트를 함께 복원합니다.

장애 진단 순서

증상 우선 확인 자주 놓치는 원인
웹 접속 불가 프록시, loopback 포트, netbox 로그 포트 공개보다 프록시 upstream·방화벽·Host 헤더
netbox unhealthy 마이그레이션, DB·캐시 연결, secret 호환되지 않는 저장소와 이미지 버전
worker 작업 정체 worker 로그와 캐시 상태 웹만 정상이고 worker가 재시작 반복
업그레이드 후 오류 릴리스 노트, DB 마이그레이션, 플러그인 플러그인 호환성·PostgreSQL 큰 버전 변경
첨부 이미지 누락 media volume 마운트와 권한 DB만 복원하고 media를 복원하지 않음 
docker compose ps --all
docker compose logs --tail=300
docker compose config --images
docker compose exec -T netbox   /opt/netbox/netbox/manage.py check
docker stats --no-stream

운영 체크리스트

  • 저장소 tag와 모든 이미지 버전 또는 digest를 변경 관리 문서에 고정했습니다.
  • ALLOWED_HOSTS에 실제 FQDN만 있으며 DB·캐시 포트를 공개하지 않았습니다.
  • 관리자 비밀번호와 SECRET_KEY를 Git·Compose 렌더링 파일·로그 밖에서 관리합니다.
  • TLS 프록시, 접근 제어, 시간 동기화와 정기 보안 업데이트를 운영합니다.
  • PostgreSQL, media, 설정, 이미지 목록을 같은 복구 세트로 백업합니다.
  • 격리 환경에서 복원과 NetBox 로그인·API·첨부 파일을 정기 검증합니다.
  • 업그레이드 전 릴리스 노트, 중간 버전, PostgreSQL·Valkey·플러그인 호환성을 확인합니다.

공식 문서와 관련 글

정리

NetBox Docker: 성공적인 운영의 기준은 컨테이너가 뜨는 것이 아니라 같은 버전을 재현하고 데이터를 복구할 수 있는가입니다. 저장소와 이미지를 함께 고정하고, 최소 노출·secret 분리·대화형 관리자 생성·TLS·DB와 media의 통합 백업을 적용하십시오. 업그레이드는 복원 테스트와 릴리스별 호환 검증을 통과한 뒤 진행해야 합니다.