CaseBender 업그레이드

개요

CaseBender는 버전이 지정된 컨테이너 이미지 세트로 제공됩니다. 업그레이드는 최신 이미지를 가져와 컨테이너를 다시 만드는 것을 의미합니다. 데이터, 라이선스, 구성은 이름이 지정된 Docker 볼륨 과 .env 파일 에 저장되며, 둘 다 업그레이드 시 보존됩니다. 따라서 이를 유지하는 한 업그레이드가 케이스, 사용자, 자격 증명, 라이선스를 건드리는 일은 없습니다.

데이터베이스 마이그레이션과 기본 데이터 시딩은 업그레이드 후 시작 시 자동으로 실행됩니다. 마이그레이션 명령을 수동으로 실행할 필요가 없습니다.

업그레이드 시 보존되는 항목

항목	저장 위치	보존 방법
케이스, 알림, 사용자, 설정	PostgreSQL	`pgdata` 볼륨
라이선스 시크릿 키 + 블롭	`/app/apps/web/app/secret`	`casebender_secret` 볼륨
업로드된 파일 / 첨부	MinIO	`miniodata` 볼륨
큐 / 캐시 상태	Redis	`redis_data` 볼륨
환경 구성	`.env`	사용자의 `.env` 파일

프로덕션 시스템에서 절대 docker compose down -v 를 실행하지 마세요. -v 옵션은 모든 이름이 지정된 볼륨(데이터베이스, 라이선스, 파일)을 삭제합니다. 이러한 볼륨이 없으면 다음 시작 시 새 데이터베이스가 생성되어 관리자 비밀번호가 기본값으로 재설정되고 라이선스가 재생성됩니다.

업그레이드 절차 (Docker Compose)

데이터베이스와 .env 백업

# PostgreSQL 백업
docker compose exec -T db pg_dump -U superadmin casebender > casebender-backup-$(date +%F).sql

# 구성 파일 사본 보관
cp .env .env.backup

최신 이미지 가져오기

docker compose pull

컨테이너 다시 생성

docker compose up -d

Compose는 이미지가 변경된 서비스만 다시 만들고 볼륨은 유지합니다.

로그 확인

docker compose logs -f app

마이그레이션과 시딩은 시작 시 실행됩니다 — 앱이 정상(healthy) 상태가 될 때까지 기다리세요.

업그레이드 후 확인

로그인하여 기존 케이스, 알림, 사용자가 있는지 확인합니다.
로그인이 여전히 작동하는지 확인합니다(관리자 비밀번호는 변경되지 않습니다).
worker가 작업을 처리하고 있는지 확인합니다.

docker compose logs worker | tail

롤백

문제가 발생하면 이전 이미지 태그를 고정하고 백업을 복원하세요.

# 안정적으로 확인된 버전을 docker-compose.yml에 고정합니다. 예:
#   image: casebender/casebender:vX.Y.Z
docker compose pull
docker compose up -d

# 필요한 경우 데이터베이스 백업 복원
cat casebender-backup-YYYY-MM-DD.sql | docker compose exec -T db psql -U superadmin casebender

항상 스테이징 환경을 먼저 업그레이드하고, 프로덕션 업그레이드 직전에 최신 데이터베이스 백업을 수행하세요.

흔한 업그레이드 실수

가장 흔한 두 가지 문제는 모두 상태 손실에서 비롯됩니다.

Compose 프로젝트 이름 또는 디렉터리 변경. Docker는 프로젝트에서 볼륨 이름을 파생합니다. 폴더 이름을 바꾸거나 다른 -p 프로젝트 이름을 사용하면 Compose가 새로운 빈 볼륨을 가리키게 됩니다. 기존 볼륨을 재사용하려면 항상 동일한 디렉터리/프로젝트에서 업그레이드하세요.
LICENSE_SECRET_KEY 누락 및 casebender_secret 볼륨 없음. 영구 시크릿 볼륨이 없는 이전 배포에서는 라이선스가 유지되도록 .env에 LICENSE_SECRET_KEY를 설정하세요(또는 볼륨 추가). 현재 배포는 자동으로 보존합니다.

데스크톱 설치 프로그램

데스크톱 설치 프로그램으로 배포한 경우, 앱에 내장된 업데이트 흐름을 사용하세요 — 데이터 디렉터리, .env, 라이선스 키를 보존하면서 최신 이미지를 가져와 서비스를 다시 만듭니다.

Google Cloud Run

Cloud Run 업그레이드는 새 리비전을 배포합니다. Cloud Run은 파일 시스템이 휘발성(ephemeral)이므로 라이선스 시크릿은 리비전 간에 유지되도록 Secret Manager를 통해 LICENSE_SECRET_KEY로 제공해야 합니다. 기존 Cloud SQL 인스턴스와 시크릿을 사용하여 다시 배포하세요.

gcloud run deploy casebender-web --image <새-이미지> --region <리전>

마이그레이션은 새 리비전에서 자동으로 실행됩니다.

​개요

​업그레이드 시 보존되는 항목

​업그레이드 절차 (Docker Compose)

​업그레이드 후 확인

​롤백

​흔한 업그레이드 실수

​데스크톱 설치 프로그램

​Google Cloud Run

개요

업그레이드 시 보존되는 항목

업그레이드 절차 (Docker Compose)

업그레이드 후 확인

롤백

흔한 업그레이드 실수

데스크톱 설치 프로그램

Google Cloud Run