> ## Documentation Index
> Fetch the complete documentation index at: https://docs.casebender.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CaseBender 업그레이드

> 데이터, 라이선스, 자격 증명을 잃지 않고 CaseBender 배포를 최신 버전으로 안전하게 업그레이드합니다.

## 개요

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

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

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

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

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

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

<Steps>
  <Step title="데이터베이스와 .env 백업">
    ```bash theme={null}
    # PostgreSQL 백업
    docker compose exec -T db pg_dump -U superadmin casebender > casebender-backup-$(date +%F).sql

    # 구성 파일 사본 보관
    cp .env .env.backup
    ```
  </Step>

  <Step title="최신 이미지 가져오기">
    ```bash theme={null}
    docker compose pull
    ```
  </Step>

  <Step title="컨테이너 다시 생성">
    ```bash theme={null}
    docker compose up -d
    ```

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

  <Step title="로그 확인">
    ```bash theme={null}
    docker compose logs -f app
    ```

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

## 업그레이드 후 확인

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

```bash theme={null}
docker compose logs worker | tail
```

## 롤백

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

```bash theme={null}
# 안정적으로 확인된 버전을 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
```

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

## 흔한 업그레이드 실수

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

* **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 인스턴스와 시크릿을
사용하여 다시 배포하세요.

```bash theme={null}
gcloud run deploy casebender-web --image <새-이미지> --region <리전>
```

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