# WORKS Drive Docker Image Archive

## 목적

WORKS Drive는 Docker Registry HTTP API v2 backend로 직접 사용하지 않는다. 대신 프로덕션 배포용 Docker 이미지를 `docker save` 결과물로 내보내고, zstd 압축 archive와 검증 파일을 WORKS Shared Drive에 보관하는 CLI 기반 보조 저장소로 사용한다.

이 방식은 다음 상황을 목표로 한다.

- Harbor 또는 공용 Registry 장애 시 수동 복구용 이미지 보관
- 작은 규모의 프로덕션 배포 이미지 이관
- `docker load` 기반 오프라인 배포

## 저장 구조

기본 최상위 디렉터리는 다음 환경 변수로 지정한다.

```dotenv
WORKS_SHAREDRIVE_DOCKER_IMAGE_DIR=docker-build-image
```

이미지는 WORKS Shared Drive에서 다음 구조로 저장한다.

```text
docker-build-image/<repository-path>/<tag>/
  image.tar.zst
  image.tar.zst.sha256
  manifest.json
```

예시:

```text
docker-build-image/baron_sso/backend/v1.2606.ab12/
  image.tar.zst
  image.tar.zst.sha256
  manifest.json
```

Registry hostname은 저장 경로에서 제외한다. 예를 들어 `registry.example/baron_sso/backend:v1.2606.ab12`는 `baron_sso/backend/v1.2606.ab12` 아래에 저장한다.

## Manifest

`manifest.json`에는 다음 정보를 기록한다.

- archive format: `docker-save-zstd`
- 원본 `image_ref`
- repository path
- tag
- Docker image id
- Git commit
- archive 파일명, 크기, sha256
- WORKS Drive remote path
- 복원 명령 예시

복원은 다음 흐름으로 처리한다.

```bash
sha256sum -c image.tar.zst.sha256
zstd -d -c image.tar.zst | docker load
```

## 업로드 CLI

로컬 컨테이너를 먼저 이미지로 commit한 뒤 업로드하려면 다음처럼 실행한다.

```bash
WORKS_SHAREDRIVE_DOCKER_IMAGE_DIR=docker-build-image \
WORKS_DOCKER_COMMIT_CONTAINER=baron_backend \
DOCKER_IMAGE_REF=registry.example/baron_sso/backend:v1.2606.ab12 \
scripts/docker-image/upload_works_drive.sh
```

이미지가 이미 로컬에 있으면 `WORKS_DOCKER_COMMIT_CONTAINER`를 생략한다.

```bash
DOCKER_IMAGE_REF=registry.example/baron_sso/backend:v1.2606.ab12 \
scripts/docker-image/upload_works_drive.sh
```

실제 업로드에는 기존 백업 업로드와 같은 WORKS Drive 인증 변수를 사용한다.

- `WORKS_DRIVE_TARGET=sharedrive`
- `WORKS_DRIVE_SHARED_DRIVE_ID` 또는 `WORKS_SHAREDRIVE_ID`
- 선택: `WORKS_DRIVE_PARENT_FILE_ID`
- `WORKS_DRIVE_ACCESS_TOKEN`, `WORKS_DRIVE_ACCESS_TOKEN_FILE`, `WORKS_DRIVE_ACCESS_TOKEN_CMD`, `WORKS_DRIVE_OAUTH_REFRESH_TOKEN`, 또는 서비스 계정 OAuth 변수

업로드 전 packaging만 확인하려면 다음을 사용한다.

```bash
WORKS_DRIVE_DRY_RUN=true \
DOCKER_IMAGE_REF=registry.example/baron_sso/backend:v1.2606.ab12 \
scripts/docker-image/upload_works_drive.sh
```

smoke 검증에는 Alpine 계열보다 운영 환경과 libc/패키지 계열 차이가 적은 Debian slim 계열을 사용한다.

```bash
docker create --name baron-works-image-smoke debian:trixie-slim \
  sh -c 'printf works-drive-docker-image-smoke >/works-smoke.txt'
docker start -a baron-works-image-smoke
WORKS_DOCKER_COMMIT_CONTAINER=baron-works-image-smoke \
DOCKER_IMAGE_REF=registry.example/baron_sso/works-smoke:works-test-ab12 \
scripts/docker-image/upload_works_drive.sh
```

## Staging/Production 계약

Action에서 `dev` 브랜치를 checkout한 뒤 한 번만 이미지를 빌드하고 immutable `image_tag`를 계산한다. staging과 production은 같은 image_tag를 입력받아 같은 registry image를 pull한다.

```text
dev branch -> publish image tag vX.YYMM.<commit4> -> staging deploy -> production deploy
```

WORKS Drive archive도 Action에서 push된 이미지를 다시 pull한 뒤 `docker save`로 만든다. 따라서 WORKS archive, staging, production은 모두 같은 registry image tag를 기준으로 한다.

## 제한

- 이 구조는 `docker push`/`docker pull`과 호환되는 Registry backend가 아니다.
- layer deduplication이 없으므로 같은 기반 이미지가 반복 저장된다.
- 배포 전에는 반드시 `image.tar.zst.sha256` 검증 후 `docker load`를 수행해야 한다.
- tag 없는 image ref와 digest-only image ref는 지원하지 않는다.