Docker 설치¶

Channel Vault NAS를 실행하는 가장 빠른 방법입니다. 여기서는 두 가지 Docker 경로를 다룹니다:

60초 만에 시작 — 공개 이미지를 받습니다 (빌드 없음).
소스에서 빌드 — 이 저장소에서 이미지를 빌드합니다.

두 경로 모두 아카이브 데이터를 바인드 마운트된 호스트 폴더(./metadata, ./downfolder, ./runtime)에 저장합니다.

60초 만에 시작 (공개 이미지)¶

Channel Vault NAS는 컨테이너 두 개(channel-vault-nas-api 백엔드 + channel-vault-nas-web UI)로 동작합니다. 하나로 합친 이미지는 없으므로 릴리스 Compose 파일을 사용하세요. 두 이미지를 모두 내려받고, 웹 포트만 공개하며 API는 Compose 내부 네트워크에 둡니다:

mkdir channel-vault-nas && cd channel-vault-nas
curl -fsSLO https://raw.githubusercontent.com/hyeonsangjeon/channel-vault-nas/main/compose.release.yml
docker compose -f compose.release.yml up -d

구형 Synology Docker 패키지에서는 docker compose 대신 docker-compose를 사용하세요. 같은 릴리스 파일을 Compose v2와 레거시 Compose 1.28.5에서 모두 검증했습니다.

NAS에 설치했다면 컴퓨터 브라우저에서 http://<NAS-IP>:5173/ 을 여세요. Docker와 브라우저가 같은 컴퓨터에 있을 때만 http://127.0.0.1:5173/ 을 사용합니다. CVN_WEB_PORT를 바꿨다면 해당 포트로 접속하고, 채널 백업 시작으로 이동하세요.

GHCR 이미지를 선호하나요?

compose.release.yml 옆에 .env를 만들고 두 이미지 오버라이드를 지정하세요:

CVN_API_IMAGE=ghcr.io/hyeonsangjeon/channel-vault-nas-api:0.3.1
CVN_WEB_IMAGE=ghcr.io/hyeonsangjeon/channel-vault-nas-web:0.3.1

CVN_API_IMAGE와 CVN_WEB_IMAGE는 항상 함께 설정하세요. GHCR 미러와 기본 Docker Hub 이미지 모두 로그인 없이 받을 수 있습니다.

기존 설치 업그레이드¶

먼저 메타데이터, 아카이브 사이드카, 런타임 설정을 백업하세요 (백업 절차). 기존 .env, 액세스 토큰, 호스트 경로, Compose 프로젝트 이름은 유지합니다. .env에서 두 이미지를 함께 바꾸세요:

CVN_API_IMAGE=modenaf360/channel-vault-nas-api:0.3.1
CVN_WEB_IMAGE=modenaf360/channel-vault-nas-web:0.3.1

GHCR을 사용한다면 위에 안내한 GHCR 이미지 이름 두 개를 쓰세요. 기존 설치 디렉터리에서 이미지를 받고 두 컨테이너를 갱신합니다:

docker compose -f compose.release.yml pull api web
docker compose -f compose.release.yml up -d api web
docker compose -f compose.release.yml ps
curl -fsS http://127.0.0.1:5173/api/health

헬스 체크에는 실제 웹 포트를 사용하세요. 버전은 0.3.1이어야 합니다. 호스트 폴더를 지우거나 down -v를 실행하지 마세요. 이미지가 게시되어도 실행 중인 설치는 자동 갱신되지 않습니다. 메타데이터 DB 하나에는 API 프로세스·복제본 하나만 실행하세요. 재시작으로 중단된 다운로드는 실패로 표시됩니다. 명시적으로 재시도하면 남아 있는 부분 파일에서 이어받기를 시도합니다.

소스에서 빌드¶

최신 main이나 브랜치를 평가하기에 가장 좋습니다:

git clone https://github.com/hyeonsangjeon/channel-vault-nas.git
cd channel-vault-nas
cp .env.example .env
mkdir -p metadata downfolder runtime
docker compose up --build

Compose 스택은 다음을 실행합니다:

api — yt-dlp, ffmpeg, ffprobe를 포함한 FastAPI 백엔드
web — nginx로 서빙되는 React 앱
./metadata — SQLite DB와 시작 시 백업
./downfolder — 아카이브된 미디어와 사이드카
./runtime/.env.runtime — Settings 탭 런타임 오버라이드

실제 아카이브를 건드리지 않고 검증하기

포트와 호스트 폴더를 바꿔 일회용 점검을 실행하세요:

mkdir -p /tmp/channel-vault-compose/{metadata,downfolder,runtime}
CVN_WEB_PORT=15173 \
CVN_API_PORT=18000 \
CVN_METADATA_HOST_DIR=/tmp/channel-vault-compose/metadata \
CVN_DOWNLOAD_HOST_DIR=/tmp/channel-vault-compose/downfolder \
CVN_RUNTIME_HOST_DIR=/tmp/channel-vault-compose/runtime \
docker compose up --build

직접 `docker run` (레지스트리 스모크 테스트)¶

포트, 볼륨, 헬스 체크, 재시작 정책을 한 파일에 담기 때문에 Compose를 권장합니다. 하지만 두 컨테이너를 하나의 Docker 네트워크에서 직접 실행할 수도 있습니다. 웹 이미지가 /api와 /ws를 http://api:8000으로 프록시하므로 api 네트워크 별칭이 필요합니다.

export CVN_API_IMAGE=modenaf360/channel-vault-nas-api:0.3.1
export CVN_WEB_IMAGE=modenaf360/channel-vault-nas-web:0.3.1

mkdir -p metadata downfolder runtime
docker network create channel-vault-nas 2>/dev/null || true

docker run -d \
  --name channel-vault-nas-api \
  --network channel-vault-nas \
  --network-alias api \
  -p 8000:8000 \
  -e CVN_DATABASE_URL='sqlite+aiosqlite:///./metadata/app.db' \
  -e CVN_METADATA_DIR='./metadata' \
  -e CVN_DOWNLOAD_DIR='./downfolder' \
  -e CVN_RUNTIME_ENV_FILE='/app/runtime/.env.runtime' \
  -e CVN_DB_MIGRATE_ON_STARTUP=true \
  -v "$PWD/metadata:/app/metadata" \
  -v "$PWD/downfolder:/app/downfolder" \
  -v "$PWD/runtime:/app/runtime" \
  "$CVN_API_IMAGE"

docker run -d \
  --name channel-vault-nas-web \
  --network channel-vault-nas \
  -p 5173:80 \
  "$CVN_WEB_IMAGE"

http://127.0.0.1:5173/ 을 엽니다. 정리는 다음과 같이 합니다:

docker rm -f channel-vault-nas-web channel-vault-nas-api
docker network rm channel-vault-nas

localhost를 넘어설 때¶

로컬 시험 이상을 하려면 시작 전에 .env를 편집하세요:

CVN_AUTH_TOKEN을 길고 무작위한 값으로 설정하세요 — 액세스 토큰 참고.
리버스 프록시 뒤에서는 웹 포트만 공개하고 API는 loopback에 바인딩하세요:
```
CVN_API_PORT=127.0.0.1:8000
CVN_WEB_PORT=5173
```

그런 다음 호스트 폴더 분리와 리버스 프록시 레시피는 NAS 설치 가이드로 이어가세요.

API 포트가 아니라 웹 포트를 여세요

{"detail":"Not Found"} 만 보인다면 원시 API 포트를 연 것입니다. 웹 포트(CVN_WEB_PORT, 기본 5173)를 여세요. NAS 문제 해결 참고.