AI 를 활용해 생성된 프로젝트입니다.
The Heritage Collection은 단순한 미디어 서버를 넘어선 **'프라이빗 라이브러리 큐레이션(Private Library Curation)'**의 완성을 목표로 하는 고급 미디어 아카이빙 및 큐레이션 시스템입니다.
이 시스템은 미디어의 전체 수명주기를 관리합니다: 발견(Discovery) → 획득(Acquisition) → 정리(Organization) → 아카이빙(Archive) → 시어터(Theater)
The Heritage Collection은 Tailscale을 통해 외부에서 안전하게 접근할 수 있는 컨테이너화된 미디어 큐레이션 시스템입니다.
graph TB
Internet["🌐 Internet"] --> TS_Network[Tailscale Network<br/>MagicDNS]
TS_Network --> Host["Tailscale Host<br/>walle.bun-bull.ts.net"]
TS_Network -->|HTTPS :443| TS[Tailscale Sidecar<br/>heritage.bun-bull.ts.net]
TS -->|:9091| Caddy[Caddy<br/>Reverse Proxy<br/>:9091]
Caddy -->|/| Homepage[Homepage<br/>:3000]
Caddy -->|/beszel| Beszel[Beszel Hub<br/>:8090]
Caddy -->|/prowlarr| Prowlarr[Prowlarr<br/>:9696]
Caddy -->|/whisparr| Whisparr[Whisparr<br/>:6969]
Caddy -->|/stash| Stash[Stash<br/>:9999]
Caddy -->|/jellyfin| Jellyfin[Jellyfin<br/>:8096]
Host -->|:8080| Torrent
Host -->|:5800| JDownloader
Host -->|:8088| Gatus[Gatus<br/>:8088]
Host -->|:20211| NetAlertX[NetAlertX<br/>:20211]
Host -->|:45876| BeszelAgent[Beszel Agent<br/>:45876]
Beszel -->|Collect Metrics| BeszelAgent
Prowlarr -->|Proxy via| FlareSolverr
FlareSolverr -->|Outbound| Internet
subgraph Storage[External Storage]
Data1["/mnt/data1<br/>Inbound Staging"]
Data2["/mnt/data2<br/>The Vault"]
end
Torrent --> Data1
Torrent --> Data2
JDownloader --> Data1
Whisparr --> Data2
Stash --> Data2
Jellyfin --> Data2
- 외부 접속 (대부분 서비스): Tailscale MagicDNS (
heritage.bun-bull.ts.net) → HTTPS(443) - TLS 종료: Tailscale 사이드카 컨테이너
- 내부 포워딩: Tailscale → Caddy(:9091)
- 경로 라우팅: Caddy → 각 서비스 (경로 기반)
- JDownloader 예외: my.jdownloader.org 웹 인터페이스를 통한 원격 접속 (Caddy 미경유)
| Category | Services | Role |
|---|---|---|
| Gateway | Tailscale, Caddy | 외부 HTTPS 접속 및 내부 라우팅 |
| Infrastructure | Homepage, Beszel, Beszel-agent, Gatus, NetAlertX | 서비스 북마크, 서버 메트릭, 헬스 상태, 네트워크 탐지 |
| Acquisition | Prowlarr, ruTorrent, JDownloader, FlareSolverr | 콘텐츠 검색 및 다운로드 |
| Curatorial | Whisparr, Stash | 메타데이터 관리 및 아카이빙 |
| Streaming | Jellyfin | 미디어 스트리밍 |
현재 구축되어 운영 중인 서비스 목록입니다. 통합 대시보드(Homepage)를 통해 모든 서비스에 접근할 수 있습니다.
| Service | Role | Port | HTTP URL | HTTPS URL | API Docs |
|---|---|---|---|---|---|
| Homepage | Dashboard & Monitoring | 3000 | http://walle:3000 |
https://heritage.bun-bull.ts.net/ |
N/A |
| FlareSolverr | Cloudflare Bypass Proxy | 8191 | http://walle:8191 |
- | /v1 |
| Prowlarr | Search Gateway (Indexers) | 9696 | http://walle:9696 |
https://heritage.bun-bull.ts.net/prowlarr/ |
/swagger |
| ruTorrent | Acquisition (Direct) | 8080 | http://walle:8080 |
- | XML-RPC |
| JDownloader | Acquisition (Web) | 5800 | http://walle:5800 |
- | MyJD API |
| Whisparr | Content Librarian | 6969 | http://walle:6969 |
https://heritage.bun-bull.ts.net/whisparr/ |
/api/v3 |
| Stash | Archive Vault (DB) | 9999 | http://walle:9999 |
https://heritage.bun-bull.ts.net/stash/ |
/graphql |
| Jellyfin | Digital Theater | 8096 | http://walle:8096 |
https://heritage.bun-bull.ts.net/jellyfin/ |
/api-docs |
| Beszel | Server Monitoring Hub | 8090 | http://walle:8090 |
https://heritage.bun-bull.ts.net/beszel/ |
N/A |
| Beszel-agent | Server Monitoring Agent | 45876 | http://walle:45876 |
- | N/A |
| Gatus | Health Status Monitor | 8088 | http://walle:8088 |
- | /api |
| NetAlertX | Network Device Discovery | 20211 | http://walle:20211 |
- | /docs |
Caddy 리버스 프록시와 Tailscale 인증서를 통해 5개 서비스에 HTTPS로 접속할 수 있습니다.
| 서비스 | HTTPS URL | Base URL 설정 |
|---|---|---|
| Homepage | https://heritage.bun-bull.ts.net/ |
- |
| Beszel | https://heritage.bun-bull.ts.net/beszel/ |
APP_URL 환경변수 설정 |
| Prowlarr | https://heritage.bun-bull.ts.net/prowlarr/ |
Settings → General → Base URL: /prowlarr |
| Whisparr | https://heritage.bun-bull.ts.net/whisparr/ |
Settings → General → Base URL: /whisparr |
| Jellyfin | https://heritage.bun-bull.ts.net/jellyfin/web/#/home |
Dashboard → Networking → Base URL: /jellyfin |
| Stash | https://heritage.bun-bull.ts.net/stash/ |
config.yml: external_host: https://heritage.bun-bull.ts.net |
Tailscale (443) → Caddy (9091)
├── / → Homepage (3000)
├── /beszel* → Beszel (8090)
├── /prowlarr* → Prowlarr (9696)
├── /whisparr* → Whisparr (6969)
├── /jellyfin* → Jellyfin (8096)
└── /stash* → Stash (9999)
다음 서비스는 Base URL을 지원하지 않아 HTTP로만 접속 가능합니다:
- JDownloader:
http://walle:5800(VNC GUI) - ruTorrent:
http://walle:8080(PHP 웹 인터페이스) - FlareSolverr:
http://walle:8191(내부용 프록시) - Gatus:
http://walle:8088(헬스 모니터) - NetAlertX:
http://walle:20211(네트워크 탐지)
이 시스템은 마이크로서비스 아키텍처를 채택하여 각 서비스가 독립적으로 배포되고 관리됩니다.
- 런타임: Podman 5.7.1 (Rootless, Daemonless) - Docker Compose 문법 사용
- 네트워크:
media-net오버레이 네트워크로 서비스 간 통신 - 스토리지 전략: 3티어 계층 구조
- SSD (nvme0n1): OS, 설정, DB (
/home/crong/git/heritage) - HDD 1 (data1): 획득 구역 (Acquisition Area,
/mnt/data1) - HDD 2 (data2): 보관고 (The Vault,
/mnt/data2)
- SSD (nvme0n1): OS, 설정, DB (
FlareSolverr (Port 8191) - Cloudflare 우회 프록시
- Cloudflare 보호된 인덱서 접근 지원
- 헤드리스 Chrome으로 자동 챌린지 해결
- 태그 기반 인덱서 라우팅 (Prowlarr 프록시)
Homepage (Port 3000) - 서비스 북마크 및 대시보드
- 모든 서비스 링크 통합
- 실시간 서비스 위젯
- Tailscale 장치 상태
- 날씨 위젯 (Open-Meteo API)
Beszel (Port 8090) - 서버 메트릭 모니터링
- CPU, 메모리, 디스크, 네트워크 실시간 추적
- Podman 컨테이너별 리소스 사용량
- 다중 서버 모니터링 지원 (Agent 방식)
Prowlarr (Port 9696) - 토런트 검색 게이트웨이
- 30+ 토런트 인덱서와 통합
- 자동화된 검색 및 발견
- API를 통한 Whisparr와 통신
ruTorrent (Port 8080) - P2P 자동 획득
- Whisparr에서 트리거로 자동 시작
- Autotools 기반 자동화
- RSS 피드 모니터링
JDownloader 2 (Port 5800) - 웹 기반 수동 획득
- 직접 링크/웹사이트 입력 지원
- 파일호스트 분해 지원
- 크롬링 지원
Whisparr (Port 6969) - 콘텐츠 라이브러니안
- 자동 메타데이터 관리
- 아티스트 매핑 및 태깅
- 퀄리티 지정 및 포맷 관리
- 하드링크 최적화로 중복 저장 방지
Stash (Port 9999) - 아카이브 볼트
- PostgreSQL 기반 데이터베이스
- 포괄, 스튜디오, 아티스트 정리
- 고급 탐색 및 필터링
- Jellyfin과 통합
Jellyfin (Port 8096) - 그랜 시네마
- 4K/HDR 콘텐츠 지원
- Intel QSV 하드웨어 가속으로 트랜스코딩
- 다양한 디바이스 지원
- 가족 계정 및 접근 제어
Homepage 대시보드의 실시간 위젯 기능을 활성화하려면 각 서비스에서 API Key를 발급받아 설정 파일에 등록해야 합니다.
- 키 발급: 위 엔드포인트에 접속하여
Settings > General > Security > API Key에서 키를 복사합니다. - 설정 적용:
homepage/config/services.yaml파일을 열어 해당 서비스의key:필드에 붙여넣습니다. - 재시작:
podman restart homepage
Homepage 대시보드는 .env 파일을 통해 시스템 전체 환경변수를 관리합니다.
| 환경변수 | 설명 | 대상 서비스 |
|---|---|---|
HOMEPAGE_VAR_NAS_IP |
NAS 내부 IP 주소 | 전체 서비스 |
HOMEPAGE_VAR_KEY_PROWLARR |
Prowlarr API Key | Prowlarr 위젯 |
HOMEPAGE_VAR_KEY_WHISPARR |
Whisparr API Key | Whisparr 위젯 |
HOMEPAGE_VAR_KEY_STASH |
Stash API Key | Stash 위젯 |
HOMEPAGE_VAR_KEY_JELLYFIN |
Jellyfin API Key | Jellyfin 위젯 |
HOMEPAGE_VAR_KEY_NETALERTX |
NetAlertX API Key | NetAlertX 위젯 |
HOMEPAGE_VAR_KEY_NEXTDNS |
NextDNS API Key | NextDNS 위젯 |
HOMEPAGE_VAR_NEXTDNS_PROFILE |
NextDNS Profile ID | NextDNS 위젯 |
HOMEPAGE_VAR_BESZEL_USERNAME |
Beszel 로그인 이메일 | Beszel 위젯 |
HOMEPAGE_VAR_BESZEL_PASSWORD |
Beszel 로그인 비밀번호 | Beszel 위젯 |
HOMEPAGE_VAR_KEY_TAILSCALE |
Tailscale API Key | Tailscale 위젯 |
HOMEPAGE_VAR_DEVICEID_DENEB |
Tailscale 장치 ID (Deneb) | Tailscale 위젯 |
HOMEPAGE_VAR_DEVICEID_AGRIAS |
Tailscale 장치 ID (Agrias) | Tailscale 위젯 |
HOMEPAGE_VAR_DEVICEID_DECK |
Tailscale 장치 ID (Deck) | Tailscale 위젯 |
HOMEPAGE_VAR_DEVICEID_MINI |
Tailscale 장치 ID (Mini) | Tailscale 위젯 |
HOMEPAGE_VAR_LATITUDE |
날씨 위젯 위도 | Open-Meteo 위젯 |
HOMEPAGE_VAR_LONGITUDE |
날씨 위젯 경도 | Open-Meteo 위젯 |
BESZEL_APP_URL |
Beszel Hub 외부 URL | Beszel |
BESZEL_AGENT_HUB_URL |
Agent가 연결할 Hub URL | Beszel Agent |
BESZEL_AGENT_TOKEN |
Agent 인증 토큰 | Beszel Agent |
BESZEL_AGENT_KEY |
Agent SSH 공개 키 | Beszel Agent |
- .env 파일 생성:
.env파일은.gitignore에 포함되어 있으므로 수동으로 생성합니다. - 변수 등록: 위 표의 환경변수와 실제 값을
.env파일에KEY=VALUE형식으로 등록합니다. - 적용 확인:
podman restart homepage명령어로 컨테이너를 재시작합니다.
- Prowlarr 통합: 30+ 토런트 인덱서를 중앙 관리
- FlareSolverr 지원: Cloudflare 보호된 인덱서 자동 우회
- 자동 검색: Whisparr와 연동하여 콘텐츠 자동 발견
- RSS 피드: 인덱서별 업데이트 자동 수집
- 자동 모드: Whisparr → ruTorrent (토런트)
- 수동 모드: 직접 링크 → JDownloader (웹 다운로드)
- 파일호스트 지원: RAR, ZIP, 7z 등 자동 분해
- 메타데이터 자동 관리: 포스터, 배우, 아티스트 정보
- 하드링크 최적화: 중복 파일 하드링크로 저장공간 절약
- 자동 태깅 및 포맷 정리
- 데이터베이스: PostgreSQL (Stash), SQLite (Whisparr, Prowlarr)
- 고급 탐색: 배우, 포괄, 스튜디오, 아티스트 기반 필터링
- GraphQL API: Stash를 통한 고급 쿼리 가능
- Intel QSV: Quick Sync Video 하드웨어 인코딩
- 4K/HDR 지원: 고화질 미디어 재생
- 트랜스코딩: 클라이언트 사이드 트랜스코딩
- 다중 디바이스: 웹, 모바일, 스마트 TV, 캐스틱
- Beszel 메트릭: 서버 CPU, 메모리, 디스크, 네트워크 실시간 추적
- 컨테이너 모니터링: Podman 컨테이너별 리소스 사용량
- Homepage 북마크: 모든 서비스 링크 통합 + Tailscale 장치 상태
- 날씨 위젯: 위치 기반 날씨 정보 표시
| 서비스 | 데이터베이스 | 용도 |
|---|---|---|
| Prowlarr | SQLite | 설정 및 인덱서 정보 |
| Whisparr | SQLite | 콘텐츠 라이브러리 |
| Stash | PostgreSQL | 아카이브 메타데이터 |
| Jellyfin | SQLite | 사용자 및 미디어 데이터 |
- FlareSolverr: Cloudflare 우회 프록시 (Prowlarr 인덱서 프록시)
- Open-Meteo API: 날씨 위젯 (위도/경도 기반)
- Tailscale API: 디바이스 모니터링 및 네트워크 관리
- 토런트 인덱서: 30+ 커스텀 인덱서 정의
/prowlarr/Definitions/디렉토리에 정의 파일 저장
- Hotio 이미지: Prowlarr, Whisparr, ruTorrent (최적화됨)
- 공식 이미지: Jellyfin, Stash, JDownloader
- FlareSolverr: GitHub Container Registry (ghcr.io/flaresolverr/flaresolverr)
- OS: Fedora 43
- Runtime: Podman 5.7.1 (Rootless, Daemonless)
- Hardware: Intel N100 (Chatreey R1)
- Storage Strategy:
- SSD (nvme0n1): OS, 설정, DB 저장소 (
/home/crong/heritage) - HDD 1 (data1): Acquisition Area (수집 구역, 신규 다운로드)
- HDD 2 (data2): The Vault (저장고, 최종 아카이브)
- SSD (nvme0n1): OS, 설정, DB 저장소 (
/home/crong/git/heritage/
├── compose.yml # 전체 인프라 정의
├── .env # 환경변수 (Git 추적 제외)
├── .env.example # 환경변수 템플릿
├── .gitignore # Git 추적 제외 설정
├── README.md # 이 파일
│
├── caddy/ # HTTPS Gateway (Caddy)
│ ├── Caddyfile # 리버스 프록시 설정
│ ├── data/ # SSL 인증서 저장소
│ └── logs/ # 접근 로그
│
├── homepage/ # 대시보드 & 모니터링
│ └── config/
│ ├── services.yaml # 서비스 위젯 설정
│ ├── settings.yaml # Homepage 설정
│ └── widgets.yaml # 위젯 설정
│
├── beszel/ # 서버 메트릭 모니터링
│ ├── data/ # Beszel Hub 데이터
│ └── agent_data/ # Beszel Agent 데이터
│
├── gatus/ # 헬스 상태 모니터링
│ ├── config.yaml # Gatus 설정
│ └── data/ # 상태 데이터
│
├── netalertx/ # 네트워크 장치 탐지
│ ├── config/ # NetAlertX 설정
│ └── db/ # 장치 DB
│
├── prowlarr/ # 검색 게이트웨이
│ └── Definitions/ # 인덱서 정의 파일
│
├── flaresolverr/ # Cloudflare 우회 프록시 (관리 불필요)
│
├── torrent/ # P2P 자동 획득
│ ├── config/ # ruTorrent 설정
│ └── data/ # 토렌트 데이터
│
├── jdownloader-2/ # 웹 수동 획득
│ └── cfg/ # JDownloader 설정
│
├── whisparr/ # 콘텐츠 라이브러니안
│ └── config/ # Whisparr 설정
│
├── stash/ # 아카이브 볼트
│ ├── config/ # Stash 설정
│ ├── cache/ # 캐시
│ └── generated/ # 생성된 파일
│
├── jellyfin/ # 미디어 시어터
│ ├── config/ # Jellyfin 설정
│ └── cache/ # 트랜스코딩 캐시
│
└── .ai/ # AI 어시스턴트 설정
├── AGENTS.md # AI 상호작용 가이드라인
├── CONTEXT.md # 기술 명세 (SSoT)
└── AI.ignore # 무시 패턴
이 프로젝트는 "Config as Code" 원칙을 따릅니다:
-
Git 추적: 설정 파일만 버전 관리 (YAML, XML, CFG)
-
제외 항목:
- 미디어 파일 (비디오, 이미지)
- 데이터베이스 파일 (.db, .sqlite)
- 캐시 파일
- 로그 파일
- 바이너리
-
심볼릭 링크: AI 설정 파일을 루트에 링크로 생성
GEMINI.md→.ai/RULES.md.clinerules→.ai/RULES.md.github/copilot-instructions.md→.ai/RULES.md
# .env 파일 복사
cp .env.example .env
# 편집기로 환경변수 입력
vim .env# 네트워크 생성
podman network create media-net
# 컨테이너 시작
podman-compose up -dHomepage의 서비스 위젯을 활성화하려면 각 서비스의 API Key가 필요합니다:
- 서비스 엔드포인트 접속
Settings > General > Security > API Key에서 키 복사homepage/config/services.yaml의key:필드에 입력podman restart homepage
HTTPS 접속 (권장):
- Homepage: https://sub.example.com/
- Prowlarr: https://sub.example.com/prowlarr/
- Whisparr: https://sub.example.com/whisparr/
- Jellyfin: https://sub.example.com/jellyfin/web/#/home
- Stash: https://sub.example.com/stash/
HTTP 접속 (내부 네트워크):
- Homepage: http://walle:3000
- Prowlarr: http://walle:9696
- Whisparr: http://walle:6969
- Stash: http://walle:9999
- Jellyfin: http://walle:8096
- Beszel: http://walle:8090
- Gatus: http://walle:8088
- NetAlertX: http://walle:20211
# 상태 확인
podman-compose ps
# 로그 확인
podman-compose logs -f [service]
# 재시작
podman-compose restart [service]
# 업데이트
podman-compose pull
podman-compose up -d주의: Git은 설정 파일만 추적하므로 백업은 별도로 해야 합니다.
# SSD 백업 (설정, DB)
rsync -av /home/crong/heritage/ /backup/location/
# HDD 백업 (미디어)
rsync -av /mnt/data1/ /backup/data1/
rsync -av /mnt/data2/ /backup/data2/Stash는 PostgreSQL을 사용하므로 정규 백업이 권장됩니다:
# 컨테이너 안에서
podman exec -it stash pg_dump -U stash -d stash > backup.sqlHomepage의 Docker 컨테이너 상태 모니터링 기능을 사용하려면 Podman 소켓 권한이 필요합니다.
임시 적용 (재부팅 후 초기화됨):
chmod 666 /run/user/1000/podman/podman.sock영구 적용 (systemd override):
# systemd override 디렉토리 생성
mkdir -p ~/.config/systemd/user/podman.socket.d
# 예제 파일 복사
cp docs/examples/podman.socket.override.conf ~/.config/systemd/user/podman.socket.d/override.conf
# systemd 재로드 및 Podman 소켓 재시작
systemctl --user daemon-reload
systemctl --user restart podman.socket참고: ~/.config/systemd/user/podman.socket.d/override.conf 파일은 git 저장소 밖에 있어서 자동으로 추적되지 않습니다. 새로운 시스템 설정 시 위 명령어를 다시 실행해야 합니다.
- Tailscale: VPN 및 HTTPS 인증서
- Caddy: HTTPS 리버스 프록시 (Tailscale 인증서)
- Homepage: 시스템 관제 및 리소스 모니터링
- Beszel: 경량 서버 메트릭 모니터링 (컨테이너별 추적)
- Gatus: 서비스 헬스 상태 모니터링
- NetAlertX: 네트워크 장치 탐지 및 추적
- FlareSolverr: Cloudflare 우회 프록시 (헤드리스 Chrome)
- Prowlarr: 인덱서 통합 관리
- ruTorrent: 메인 수집 엔진 (Autotools 활용)
- JDownloader 2: 직접 다운로드 도구 (JVM 최적화)
- Whisparr: 콘텐츠 자동 정리 (Content Librarian)
- Stash: 프라이빗 DB 관리 (Archive Vault)
- Jellyfin: 4K 스트리밍 (The Grand Cinema, Intel QSV 가속)
- IaC (Infrastructure as Code): 모든 인프라는
podman-compose와 Git으로 관리합니다. - Config as Code:
.gitignore를 통해 런타임 캐시, 바이너리, 로그를 엄격히 제외하고 순수 설정 파일(Config)만 추적합니다. - Gentlemanly Terminology: 품격 있는 용어 사용 (예: '프라이빗 큐레이션', '시네마틱 아카이브').
- Performance: I/O Wait 최소화 및 하드링크 우선 적용.
프로젝트는 다양한 AI 어시스턴트(GEMINI, Cline, GitHub Copilot)와 함께 작동하도록 구성되어 있습니다.
.ai/
├── AI.ignore # 공통 파일 무시 패턴
├── CONTEXT.md # 프로젝트 기술 사양 및 문맥 (SSoT)
└── RULES.md # 공통 AI 가이드라인 (최상위 지침)
# 루트 디렉토리 Symbolic Links
GEMINI.md → .ai/RULES.md (공통 AI 가이드라인)
.clinerules → .ai/RULES.md (Cline 규칙)
.clineignore → .ai/AI.ignore (Cline 무시 패턴)
.geminiignore → .ai/AI.ignore (GEMINI 무시 패턴)
.github/copilot-instructions.md → .ai/RULES.md (GitHub Copilot 규칙)
- GEMINI:
GEMINI.md→.ai/RULES.md+.ai/CONTEXT.md - Cline:
.clinerules→.ai/RULES.md,.clineignore→.ai/AI.ignore+.ai/CONTEXT.md - Z-AI:
.ai/RULES.md+.ai/CONTEXT.md(별도 설정 파일 없음)
- .ai/RULES.md: 모든 AI가 따르는 최상위 운영 지침
- .ai/CONTEXT.md: 프로젝트 기술 명세 및 구성 (단일 진실 공급원)
- .ai/AI.ignore: AI가 무시해야 할 파일 패턴
MIT License - 자세한 내용은 LICENSE 파일을 참조하세요
