Skip to main content

JunkBox 개발 환경·운영 배포 가이드

1. 문서 범위​

  • 이 문서는 JunkBox의 설정·환경 파일, 로컬 개발 실행과 접속 경로, 신규 앱 생성 계약, 운영 컨테이너 포트 규칙, 운영 배포, 개발 문서 벡터 캐시를 다룸.
  • 앱·개발 포트 목록은 docs/junkbox/common/guide-jb-overview.md의 앱 표가 단일 기준임.
  • 구조 원칙과 날짜·DB·인증 공통 계약은 docs/junkbox/common/guide-jb-core.md가 소유함.

2. 설정 구조​

2.1 Settings 원칙​

  • 설정은 pydantic-settings 기반으로 로딩함.
  • 기본 ENV_FILE 값은 .env.local임.
  • ENV_FILE 기준 환경 파일과 같은 디렉터리의 .env.shared를 함께 로드함.
  • ENV_FILE 기준 환경 파일과 같은 디렉터리의 .env.chess를 함께 로드함. Chess OAuth와 Stockfish 설정은 이 파일에서 관리함.
  • ENV_FILE이 base profile env 파일명 뒤에 앱 suffix를 붙인 형태이면 같은 디렉터리의 .env.local 또는 .env.prod를 base profile env로 함께 로드할 수 있음.
  • 설정 우선순위는 명시적 초기화 값, .env.chess, 선택된 ENV_FILE, base profile env, .env.shared, 셸 환경 변수, file secret 순서임.
  • import 시점부터 실행 환경 오염을 최소화하는 방향을 사용함.
  • 설정 객체는 app, database, auth, server, modules, masterdata, dashboard, rename, wow, lichess, hub_tools, ai 중첩 모델 구조를 사용함.
  • 앱 코드는 중첩 모델 접근을 기준으로 구현하며, 일부 flat alias는 호환 목적에 한해 유지함.

2.2 주요 설정 범주​

  • 앱별 SQLite DSN과 DB_ECHO
  • HUB_DATABASE_URL
  • CHESS_DATABASE_URL
  • HEALTH_DATABASE_URL
  • MESSAGE_DATABASE_URL
  • MESSAGE_APPRISE_DEFAULT_CONFIG_KEY: Apprise 요청에 설정 키가 없을 때 사용할 기본 설정 키이며 현재 값은 apprise임.
  • WOW_DATABASE_URL
  • JWT_SECRET_KEY, JWT 알고리즘
  • apps/hub-api/var/auth-policy.yml 기반 사용자 세션 만료 시간과 슬라이딩 갱신 임계 시간
  • apps/hub-api/var/dashboard-policy.yml 기반 hub 대시보드 HTTP 수집 타임아웃, 캐시 TTL, Glances 호출 타임아웃
  • DASHBOARD_OPENROUTER_MANAGEMENT_API_KEY 기반 hub 대시보드 OpenRouter credits/API key 사용량 조회 설정
  • 쿠키 이름, 도메인, secure, same_site
  • CORS 허용 원본
  • 공통 로깅 정책인 LOG_ROTATION_LIMIT, LOG_RETENTION_DAYS, LOG_COMPRESSION_TYPE
  • profile별 로깅 동작인 LOG_LEVEL, LOG_DIAGNOSE_TOGGLE
  • MASTER_DATA_DIR
  • AI_ROUTING_YAML_PATH
  • HUB_BASE_URL, HEALTH_BASE_URL, WOW_BASE_URL
  • CHESS_BASE_URL
  • HUB_INTERNAL_BASE_URL, HUB_API_INTERNAL_TOKEN, HUB_API_INTERNAL_TOKEN_HEADER
  • MASTERDATA_CODES_TTL_SECONDS, MASTERDATA_METAS_TTL_SECONDS, MASTERDATA_HTTP_TIMEOUT_SECONDS
  • AI_ACCESS_TOKEN, FASTAPI_BASE_URL
  • ASITE_BASE_URL, ASITE_LOGIN_URL, ASITE_USERNAME, ASITE_PASSWORD
  • RENAME_BASE_DIR, RENAME_TARGET_DIR_NAME
  • WCL_API_URL, WCL_TOKEN_URL, WCL_CLIENT_ID, WCL_CLIENT_SECRET, WCL_MAX_CONCURRENCY
  • LITELLM_API_KEY, LITELLM_BASE_URL, AI_HTTP_TIMEOUT_SECONDS
  • LICHESS_BASE_URL, LICHESS_OAUTH_CLIENT_ID, LICHESS_OAUTH_REDIRECT_URI, CHESS_STOCKFISH_PATH, CHESS_STOCKFISH_TIME_LIMIT_SECONDS, CHESS_STOCKFISH_DEPTH, CHESS_STOCKFISH_MULTIPV, JUNKBOX_CHESS_RESTART_POLICY
  • VAULT_GITHUB_TOKEN, VAULT_GITHUB_OWNER, VAULT_GITHUB_REPO, VAULT_GITHUB_BRANCH, VAULT_GITHUB_DEFAULT_DOCS_PATH
  • LINKDING_BASE_URL, LINKDING_API_TOKEN
  • 그 밖의 앱도 같은 형식의 {APP}_DATABASE_URL과 {APP}_BASE_URL을 사용함.

2.3 AI 개발 지식 동기화 설정​

  • 개발 문서 벡터 캐시 동기화와 검색 스크립트는 애플리케이션 런타임 설정을 사용하지 않음.
  • 수동 빌드/인프라 타임 및 AI 에이전트 전용 설정은 scripts/.env.ai만 사용함.
  • 공유 가능한 설정 예시는 scripts/.env.ai.template에 둠.
  • scripts/.env.ai는 Git 추적 대상이 아니며 로컬 또는 운영 작업자별 비밀값을 담음.
  • FASTAPI_BASE_URL은 AI 에이전트가 hub-api 통합 snapshot API를 호출할 때 사용하는 base URL임.
  • AI_ACCESS_TOKEN은 ROLE_AI claim을 가진 AI 에이전트 전용 JWT이며 scripts/fetch_master_data.py가 Bearer 토큰으로 사용함.
  • VAULT_DATABASE_URL은 jb_ai 계정 기준 PostgreSQL 접속 문자열임.
  • AI_EMBEDDING_API_KEY는 개발 문서 chunk와 검색 query를 임베딩하기 위한 API 키임.
  • AI_EMBEDDING_BASE_URL은 LiteLLM proxy 같은 OpenAI 호환 embeddings API base URL임.
  • VAULT_EMBEDDING_MODEL은 개발 문서 벡터 캐시와 검색 query가 공유하는 임베딩 모델 식별자이며 LiteLLM에 등록된 embedding model id 또는 alias를 사용함.

2.4 AI 라우팅 설정 원칙​

  • 로컬 Git 관리 기준 AI 라우팅 기본 파일은 apps/hub-api/var/master-data/ai-routing.yml임.
  • 컨테이너 런타임 기본 경로는 /app/var/master-data/ai-routing.yml임.
  • 운영 Compose의 AI 소비 앱은 호스트 공통 파일 /sorc001/junkbox/master-data/ai-routing.yml을 컨테이너 기본 경로에 읽기 전용으로 마운트함. 개발 Compose에서는 저장소의 apps/hub-api/var/master-data 디렉터리를 읽기 전용으로 마운트함.
  • APP_PROFILE 값이 있으면 ai-routing.{profile}.yml을 우선 사용함.
  • profile별 파일이 없으면 기본 ai-routing.yml을 fallback으로 사용함.
  • provider 선택과 model 선택은 라우팅 YAML이 결정하고, API 키와 base URL은 profile env와 ENV_FILE 조합이 결정함.
  • 어떤 provider 구현이 선택되는지는 provider 값이 결정하고, model 값은 선택된 provider 내부에서 실제 원격 모델 식별자로 사용됨.

2.5 환경 파일 분류 원칙​

  • 환경 파일 원본은 workspace의 .env·.env.*이며 운영 환경 디렉터리는 이관된 사본임. AI의 등록·수정·이관 절차와 승인 범위는 JunkBox AGENTS.md가 소유함.
  • 앱 실행용 환경 파일은 workspace의 .env.shared, .env.chess, .env.local, .env.prod와 공용 템플릿 .env.local.template로 구성함. 운영 env 디렉터리는 .env.shared, .env.chess, .env.prod를 사용함.
  • AI 문서 검색·마스터데이터 조회용 scripts/.env.ai와 템플릿 scripts/.env.ai.template은 앱 실행 env와 별도로 관리함.
  • .env.shared에는 프로필과 무관한 공통 인프라 정책을 둠.
  • .env.local, .env.prod에는 프로필별로 달라지는 값과 운영 민감도가 높은 값을 둠.
  • RENAME_BASE_DIR와 RENAME_TARGET_DIR_NAME은 모든 프로필에서 같은 비민감 파일 시스템 작업 기준값이므로 .env.shared에 둠.
  • HUB_AUDIOBOOK_EPUB_ROOT, HUB_AUDIOBOOK_WORK_DIR는 모든 프로필에서 같은 비민감 값이므로 .env.shared에 둠. 월 상한·미리듣기 길이·기본 음성은 환경 파일이 아니라 Hub 메타가 소유하며 의미는 docs/junkbox/apps/guide-apps-hub-api.md 7.10절을 따름.
  • 오디오북 음성 합성은 LiteLLM을 거치므로 Google 인증 키를 환경 파일에 두지 않고 LITELLM_BASE_URL·LITELLM_API_KEY를 사용함.
  • AUTOMATION_BASE_URL은 프로필별 서비스 연결 값임. .env.local은 http://localhost:18007, Docker Compose 기반 .env.prod는 http://junkbox-automation-api:8080을 사용함.
  • .env.chess에는 Lichess OAuth, Stockfish, Chess 서비스 재시작 정책처럼 Chess 전용으로 공유되는 설정을 둠.
  • .env.local.template은 local/prod env 파일이 공유하는 단일 템플릿으로 사용함.
  • .env.local과 .env.prod는 같은 변수 항목과 같은 주석 구조를 유지하여 프로필별 값 비교가 가능해야 함.
  • 현재 공통 로깅 정책인 LOG_ROTATION_LIMIT, LOG_RETENTION_DAYS, LOG_COMPRESSION_TYPE는 .env.shared에 위치함.
  • 현재 프로필별 로깅 동작인 LOG_LEVEL, LOG_DIAGNOSE_TOGGLE는 .env.local, .env.prod에 각각 위치함.
  • just env-copy-to-sorc001과 이를 호출하는 VS Code build task env:copy-to-sorc001은 프로젝트 루트의 .env.chess, .env.prod, .env.shared를 /sorc001/junkbox/env/로 덮어쓰기 복사하는 운영 보조 흐름임.
  • scripts/copy_env_files.sh는 복사 시작 전 Enter 확인, 대상 디렉터리 준비, 파일별 복사 진행 출력, 완료 후 Enter 대기 흐름을 제공함. 런타임에서 로드되는 프로젝트 루트 환경 파일을 새로 추가하면 ENV_FILES와 이 문서의 복사 대상 목록을 함께 갱신해야 함.

3. 로컬 개발 실행​

  • 프로젝트 루트의 justfile은 로컬 서버 실행, UI 빌드, 환경 파일 복사, 개발 문서 벡터 동기화 명령의 기준임. just 실행 파일은 개발 환경의 PATH에서 찾을 수 있어야 함.
  • scripts/local_dev.py는 서버와 worker의 전경·백그라운드 실행, 종료, 상태, 로그를 관리함. justfile의 backend recipe는 JunkBox 루트에서 uv run --package를 사용하고, frontend 및 UI build recipe는 대상 앱 디렉터리에서 fnm 환경을 초기화한 뒤 npm을 실행함.
  • 터미널에서 just hub-backend, just hub-frontend 같은 서버 recipe를 인자 없이 호출하면 백그라운드로 시작하고 프롬프트를 반환함. just hub-dev-all 같은 묶음 recipe는 해당 앱의 백엔드와 프런트엔드를 시작함. just stop <service-name>, just status, just logs <service-name>으로 백그라운드 서버를 관리함.
  • .vscode/tasks.json은 같은 recipe를 호출하는 VS Code 진입점임. 서버와 worker task는 foreground 인자를 전달하며, 기존 dev-all task는 개별 서버 task를 병렬로 실행하고 build task는 기존 의존 순서를 유지함. VS Code task 또는 터미널 종료 시 실행 프로세스 그룹을 정리하여 사용 포트를 해제함.
  • 백그라운드 실행 상태 파일은 var/run/local-dev, 출력 로그는 var/log/local-dev에 둠. 서버 시작 전에 포트 점유를 확인하며, 종료 명령은 기록된 서버 프로세스 그룹만 대상으로 함.
  • 개발 모드에서는 Vite dev server가 화면 엔트리와 HMR 자산을 제공하고, FastAPI는 서버 렌더링 HTML과 API를 제공함.
  • justfile의 backend recipe는 JunkBox 프로젝트 루트에서 uv run --package {package-name} uvicorn ... 형태로 실행하여 각 앱 패키지 의존성을 해석함. VS Code backend task는 해당 recipe를 전경 모드로 호출함.
  • .venv/bin/uvicorn을 직접 호출하는 방식은 workspace 앱별 런타임 의존성이 설치되지 않은 환경을 만들 수 있으므로 backend recipe의 표준 실행 방식으로 사용하지 않음.
  • 각 앱의 개발 서버 기본 진입 경로는 해당 앱 가이드를 따름.
  • 신규 앱의 실행·빌드 작업이 생기거나 기존 앱의 패키지명, 작업 디렉터리, 환경 변수, 개발 포트, 실행 명령, 서버 조합이 달라지면 justfile의 관련 recipe와 .vscode/tasks.json의 대응 task를 함께 갱신함. 기존 task label, dependsOn, 실행 순서, 터미널 표시 설정과 전경·백그라운드 동작을 유지함.
  • 변경 후 just --list, 관련 recipe의 just --dry-run, just --fmt --check, .vscode/tasks.json 파싱과 task-recipe 대응 관계를 확인함. 검증을 위해 실행한 서버는 종료하고 사용 포트가 비었는지 확인함.
  • 세션 마무리는 junkbox 루트의 just dev-finalize 또는 VS Code dev:finalize로 시작하며 절차는 junkbox-dev-finalize 스킬이 소유함.
  • 마무리 보조 recipe는 dev-finalize-status(두 저장소와 로컬 서비스 요약), dev-finalize-preview-docs(Vault 원본과 벡터 인덱스의 읽기 전용 비교), dev-finalize-sync-docs <토큰>(확인한 삭제 범위로 벡터 동기화), dev-finalize-release-check(앱 릴리스 태그·버전·대상 커밋 조회)임.
  • Vault 저장소의 Git 커밋·푸시는 vault-docs-update 스킬이 소유함. 원본은 vault/.agents/skills/vault-docs-update/에 있고 junkbox/.agents/skills/vault-docs-update는 해당 폴더를 가리키는 상대 심볼릭 링크임. junkbox-dev-finalize는 Vault를 직접 커밋하지 않고, Vault에 변경이 있으면 통합 질문에서 이 스킬의 실행 여부를 선택받아 호출함.

3.1 개발 서버 접속 경로​

  • UI 개발 서버는 apps/dev-server-origin.ts의 공통 설정으로 루프백에서 실행되고, 기본 경로의 사설 IPv4 인터페이스에는 같은 UI 포트의 TCP 전달기를 둠. 전달기는 같은 서브넷의 클라이언트만 루프백 Vite 서버로 연결하며 HTTP와 HMR WebSocket을 함께 전달함. FastAPI 개발 포트는 루프백에만 수신함.
  • Vite의 정규식 페이지 프록시 키는 devProxyPath로 구성함. 등록된 페이지 경로에 매칭하고 쿼리 문자열을 FastAPI에 전달해 직접 진입·새로고침과 로그인 복귀를 유지함.
  • 외부 Tailnet 접근은 tailscale serve가 각 UI 포트의 HTTPS 요청을 해당 루프백 Vite 포트로 전달함. just dev-tailnet-serve가 모든 UI 개발 포트를 등록하고 just dev-tailnet-status가 상태를 표시함. LAN의 직접 접속은 별도의 UFW 허용 규칙이 필요함.
  • 신규 UI 앱을 추가하거나 기존 UI 앱의 개발 포트·LAN 접근 설정을 바꾸면, AI는 실제 LAN 인터페이스·서버 주소·서브넷과 현재 UFW 규칙을 확인하고 해당 UI 포트만 내부망에서 접근 가능하도록 수신 설정과 방화벽 규칙을 맞춤.
    • UFW 규칙은 해당 LAN 인터페이스, 내부망 출발지, 서버의 내부망 목적지, 필요한 TCP UI 포트로 한정하며 FastAPI 개발 포트나 포트 범위 전체를 일괄 개방하지 않음.
    • AI가 관리자 권한으로 적용할 수 있으면 직접 반영하고, 권한이 없으면 사용자가 홈서버에서 실행할 수 있는 정확하고 복사 가능한 sudo ufw 명령을 안내함.
    • 적용 뒤에는 서버 자신의 LAN 주소로 접속하는 검사에 그치지 않고 다른 내부망 기기에서 직접 접속을 확인하며, 실패하면 방화벽 로그를 조사함.
  • 현재 Tailnet HTTPS 프록시는 just dev-tailnet-serve로 UI 포트별 등록함. 새 UI 포트가 생기면 apps/dev-server-origin.ts와 shared-core의 개발 UI 포트 허용 목록, Vite 설정, justfile의 Serve recipe, 필요한 UFW 규칙을 함께 확인함. tailscale serve 설정과 UFW 규칙은 개발 서버의 실행·종료와 별개로 유지됨.

3.2 테스트​

  • Python 테스트는 루트 pyproject.toml의 개발 의존성 그룹 dev(pytest, pytest-asyncio)와 [tool.pytest.ini_options](asyncio_mode=strict, --import-mode=importlib, testpaths=["apps","libs"])로 실행함.
    • just test는 전체를, just test apps/<앱>/tests는 해당 경로만 실행하며 내부적으로 uv run --all-packages --group dev python -m pytest를 사용함.
    • 비동기 테스트는 @pytest.mark.asyncio를, 기존 unittest 스타일 테스트도 같은 pytest 러너로 실행함.
    • dev 그룹은 운영 이미지의 uv sync --frozen --no-dev에 포함되지 않음.

4. 신규 앱 생성 필수 계약​

4.1 구성과 사전 조사​

  • 신규 앱은 apps/{app}-api와 화면이 필요한 경우 apps/{app}-ui를 독립 패키지로 구성하고, Python workspace·Vite TypeScript strict·공통 라이브러리 의존성을 기존 앱 구조에 맞춰 등록함.
  • 업무 날짜와 시각은 코어 가이드의 날짜와 시간 기준을 따름.
  • 구현 전에 scripts/search_dev_docs.py로 관련 개발 가이드를 의미 검색함. 공통코드, 메타, 포털 메뉴, 앱 아이콘 또는 Hub 설정이 관련되면 scripts/fetch_master_data.py snapshot을 먼저 조회함.

4.2 모바일 UX와 공통 UI​

  • 신규 웹앱의 본문 구성은 공통 UI 가이드 4.4절을 따름.
  • 모바일 전용 앱의 UX 기준 앱은 health-ui임. 서버 렌더링 공통 앱 셸, BrowserRouter, spa_navigation=true, junkbox:spa-navigate 이벤트 수신, SpaRouteTransition, useSpaRouteSettling, 모바일 고정 폭과 하단 고정 액션바를 공통 기준으로 사용함.
  • 화면 CSS는 반드시 shared-ui 빌드 자산으로 공급함. 앱·모듈·화면 전용 CSS 파일, <style> 태그, inline style과 앱별 font-family 선언을 추가하지 않음.
  • 한글·영문·숫자는 shared-ui의 PretendardVariable.woff2와 중앙 --jb-font-family 선언으로 렌더링함. 사용자 로컬 Pretendard, 유사 sans, 외부 폰트, 브라우저 기본 monospace가 우선하지 않는지 확인함.
  • 모바일 선택 UI는 네이티브 <select> 대신 jb-select 외형 버튼과 shared-ui BottomOptionPicker를 우선 사용함. 화면 전체를 관통하는 CUD 액션은 jb-mobile-bottom-bar 공통 하단 고정 액션바에 배치함.
  • 공통 앱 셸, 버튼, 입력창, 토스트, 아이콘, 바텀시트, SPA 유틸은 화면에서 복제하지 않고 @shared-ui/*와 공통 템플릿·클래스로 소비함. 새 공통 외형이 필요하면 앱 CSS가 아니라 shared-ui에 추가함.

4.3 개발 포트와 접속 경로​

  • 신규 API·UI 앱의 개발 포트는 기존 사용 포트를 Hub 포털 메뉴 데이터와 현재 서비스 구성에서 확인한 뒤 15001~15999 Vite와 18001~18999 FastAPI를 같은 오프셋의 포트 쌍(예: 15011·18011)으로 배정함.
    • 기존 포털·소스·Compose·수신 포트의 예약을 확인하고 두 포트가 모두 미배정인 가장 작은 쌍부터 순차 사용함.
    • 기존 배정은 유지하며 한쪽만 빈 쌍은 건너뜀.
    • 운영 컨테이너 내부 포트는 서비스별로 배정하지 않고 8080으로 통일하며, 호스트 ports:를 공개하지 않고 Cloudflare Tunnel은 http://<서비스명>:8080으로 연결함.
    • 세부 규칙과 신규·변경 시 갱신 대상은 5. 운영 컨테이너 포트 통일 규칙을 따름.
  • 신규 UI 앱에 개발 포트를 배정하면 3.1절의 로컬 개발 LAN 접근 절차와 Tailscale Serve HTTPS 등록 절차를 모두 수행함. UI 개발 서버는 홈서버의 내부망 주소에서 접근 가능하게 구성하고, FastAPI 개발 포트는 루프백 수신을 유지함. 신규 웹앱의 최초 구현 완료 보고에서는 4.7절에 따라 두 접속 경로의 실제 적용·검증 상태와 사용자가 수행할 추가 설정을 반드시 고지함.

4.4 Portal 메뉴, 앱 이름, 설치​

  • 신규 웹앱 추가 범위에는 기존 Portal APP 목록에 해당 앱 메뉴를 등록하는 작업이 포함됨. 포털 노출 범위와 DB 적용 방식은 junkbox/AGENTS.md를 따름.
    • 기존 snapshot·포털 메뉴·대상 Hub SQLite 파일 및 tb_portal_menu_m 컬럼을 확인하고 앱 목적에 맞는 menu_name, menu_type_code=APP, icon_type_code=APP_ICON, 앱 전용 icon_val slug, 운영 menu_url, 개발 local_menu_url, 표시 순서·활성 상태를 설정함.
    • 운영 URL·포트는 승인된 값과 일치시킴.
  • Hub를 제외한 웹앱의 상단 brand_title과 app_name은 JunkBox {Portal menu_name} 형식으로 통일함. Portal 메뉴는 짧은 앱 이름을 유지하고 그 대소문자를 그대로 사용함(예: Track → JunkBox Track, SipMon → JunkBox SipMon). 접두어를 중복하지 않으며 신규 앱 및 기존 앱 명칭 변경 시 메뉴/상단 표시 일치를 확인함. Hub와 화면별 제목·메뉴·모듈 코드·아이콘 slug·PWA 표시명은 이 규칙의 변경 대상이 아님.
  • 신규 웹앱의 Android Chrome 설치 기준: 설치 및 바로가기 만들기 → 설치에서 사용자가 앱 이름을 편집할 수 있도록 서버 렌더링 화면에 web manifest 링크를 연결하지 않음.
    • 공통 앱 셸의 브라우저 제목 page_title | app_name과 앱 전용 favicon을 제공해 설치 화면의 기본 이름·아이콘을 설정함.
    • 이는 바로가기 만들기 검증과 구분하며 실제 Android Chrome에서 이름 입력과 설치 후 독립 실행을 확인함.
    • 실기기에서 확인하지 못하면 미검증으로 보고함.
    • 이미 설치한 앱이 참조하는 manifest·service worker URL은 변경 영향을 검토한 뒤 유지하거나 이관함.
  • 해당 앱의 shared-ui 아이콘 자산이 없으면 기존 아이콘 체계에 적합한 아이콘 세트를 추가하고 Portal·favicon·PWA를 같은 slug로 연결함. 기존 앱 메뉴의 명확한 식별자를 재사용해 중복 없이 등록·갱신하고 다른 앱 메뉴·정렬은 보존함. 반영 뒤 DB 조회·스키마와 실제 Portal의 앱 이름·아이콘·순서·링크·앱 진입을 검증함.
  • 포털 APP 메뉴가 미적용이면 최초 완료 보고에 사유와 필요한 결정을 명시함. 수동 반영용 SQL을 작성한 경우 파일 경로와 적용 절차를 함께 안내함.

4.5 데이터와 인증​

  • 앱 도메인 데이터는 Hub SQLite에 섞지 않고 앱 전용 SQLite 파일과 앱 전용 *_DATABASE_URL을 사용함.
    • 모든 앱별 SQLite 업무 파일은 호스트 /sorc001/junkbox/db에 위치하며 로컬 비컨테이너 개발과 운영 컨테이너가 같은 파일을 사용함.
    • 컨테이너는 호스트 폴더를 /app/db에 마운트함.
    • 별도 개발용 업무 DB는 기본으로 만들지 않으며 자동 테스트의 격리 임시 DB만 예외임.
    • SQLite 파일과 스키마의 확인·반영·검증은 junkbox/AGENTS.md의 마스터데이터와 DB 변경 절을 따름.
  • 보호 웹 화면은 별도 인증 체계를 만들지 않고 Hub JWT Cookie/Header, required_module, allowed_modules, Hub 공통 로그인·복귀 흐름을 사용함. 외부 호출 API와 관리자 화면의 인증·권한 요구는 명시적으로 분리함.

4.6 배포, 검증, 문구​

  • 운영 배포 대상 앱은 앱 API Dockerfile, 개발 docker-compose.yml, 운영 docker-compose.prod.yml, 앱 DB·로그 볼륨, Hub 의존성, 환경 파일, docker-compose.prod.yml 서비스 포트와 재시작 정책을 함께 구성함.
  • 개발·운영 Compose 서비스는 모두 container_name을 명시함. 이름은 5.1 컨테이너 이름 통일 규칙을 따름.
  • Dockerfile은 해당 UI dist와 shared-ui 빌드 자산을 런타임 이미지에 포함함.
    • 각 UI의 Vite 설정이 참조하는 apps/dev-server-origin.ts는 각 UI의 frontend-builder 단계에서 /build/apps/dev-server-origin.ts로 복사함.
    • GitHub Actions selective build/deploy의 서비스 정의, 배포 정책, 변경 감지 경로, 수동 배포 선택지까지 같은 서비스명으로 등록함.
    • 서비스 정의의 triggerPaths는 Dockerfile이 COPY하는 경로를 모두 포함해야 하며, deploy_config.mjs validate가 서비스·정책·Compose·Dockerfile의 불일치를 검사함. 검사에 실패하면 파이프라인이 시작되지 않음.
    • 운영 Compose의 이미지 태그는 JUNKBOX_<서비스>_IMAGE_TAG 변수(기본 latest)로 지정하며 API 서비스는 /health 헬스체크를 가짐.
    • 신규 앱의 기본 배포 정책은 buildEnabled=true, deployEnabled=true, autoStartOnDeploy=true, restartPolicy=unless-stopped이며 사용자가 명시적으로 다른 정책을 요청한 경우에만 변경함.
    • 정책 등록과 실제 운영 배포 실행의 승인 범위는 구분함.
  • 신규 앱은 로컬 실행·빌드 명령을 justfile에 등록하고 같은 명령을 호출하는 .vscode/tasks.json 개발 작업을 제공함. Vite typecheck·build, 백엔드 컴파일 또는 테스트, Docker Compose config 검증, 웹 라우트·포털 진입·공통 CSS와 폰트 적용을 확인함. 검증을 위해 시작한 로컬 서버와 포트는 완료 전에 종료함.
  • 일반 UI 텍스트와 사용자 메시지는 한국어 소스 문구로 작성하며 DB 메시지 마스터를 만들지 않음. 문장형 노출 메시지는 하십시오체와 마침표를 사용함.
  • 기능 구현만으로 개발 가이드 문서를 자동 변경하지 않음. 문서 갱신과 벡터 캐시 동기화는 사용자가 세션 마무리를 요청했을 때 junkbox-dev-finalize 스킬 절차로 수행함.

4.7 신규 웹앱 최초 완료 보고와 추가 설정​

  • 신규 웹앱의 최초 구현 완료 보고에는 아래의 추가 설정 안내를 반드시 포함함. 사용자가 접속 실패를 보고하거나 별도 질문을 할 때까지 안내를 미루지 않음. 코드를 작성하거나 recipe에 명령을 추가한 사실과 실제 서버 설정을 적용한 사실을 구분함.
  • 각 항목을 적용 완료, 미적용, 미검증, 해당 없음으로 표시함. 설정 적용 여부와 접속 검증 여부가 다르면 각각 명시하고, 해당 없음에는 이유를 적음. 미적용 항목은 실행 위치·실제 주소와 포트가 반영된 복사 가능한 명령 또는 화면 조작 경로·미적용 사유를 함께 안내함.
확인 항목최초 완료 보고에 반드시 포함할 내용
내부망 UI 접속홈서버의 실제 LAN 인터페이스·주소·서브넷, UI 수신 및 forwarder 상태, http://192.168.0.202:<UI 포트>/<진입 경로> 형태의 실제 URL, UFW 허용 상태·필요 명령. 현재 주소를 무조건 고정값으로 추정하지 않고 조사함.
Hub 로그인 경로해당 내부망·Tailnet 방식으로 Hub UI에도 접근 가능한지, 필요한 경우 Hub UI 포트의 방화벽 허용 상태, 로그인 후 신규 앱의 원래 URL로 복귀하는지. FastAPI 포트는 외부에 개방하지 않음.
Tailnet HTTPS 접속실제 Tailnet 호스트명과 UI 포트의 HTTPS URL, tailscale serve status의 프록시 등록 상태, HTTPS 응답·로그인 복귀 결과, 필요한 sudo tailscale serve --bg --https=<UI 포트> http://127.0.0.1:<UI 포트> 명령. LAN UFW 허용과 Serve 등록은 별도 설정임.
포털·사용자 권한기본 작업인 Portal APP 메뉴의 실제 DB 등록 여부, 앱 이름·전용 APP_ICON slug·운영/개발 URL·표시 순서·활성 상태 및 Portal 표시/진입 검증 결과. Hub 이외 앱의 상단 이름이 JunkBox {Portal 앱 이름}인지도 확인함. 모듈 선택지 등록과 대상 사용자 권한 부여 주체도 명시함. 사용자가 직접 권한을 설정하기로 했다면 Hub 사용자 관리의 대상 사용자·앱 체크박스·저장 경로를 안내하며 AI가 임의 부여하지 않음.
DB·환경·운영 진입필요한 DB 스키마·초기화·환경 파일 및 인증 복귀 origin의 반영 상태, 운영 포트·도메인·DNS·HTTPS 프록시·배포 및 재시작 정책의 확정/미적용 상태. 수동 산출물이 있으면 경로와 적용 주체를 명시함.
실행·검증 범위API/UI 개발 포트, 서버 실행·종료·유지 상태, 서버 자체 확인과 다른 PC·휴대폰의 접속 검증을 구분함. PWA 앱은 HTTPS 및 대상 실기기의 설치·복귀 검증 여부도 명시함.
  • 권한 부족이나 sudo 암호 때문에 UFW·Tailscale Serve를 적용하거나 조회하지 못했으면, 적용/확인하지 못한 항목과 이유를 명확하게 알림. 실행하지 않은 명령을 완료로 표시하거나 미등록 HTTPS URL을 이미 접속 가능한 주소처럼 안내하지 않음. 방화벽은 확인된 LAN 인터페이스·출발지 서브넷·홈서버 목적지·필요 UI TCP 포트로 제한하며 포트 범위 전체를 일괄 허용하지 않음.
  • 아래는 현재 홈서버 eno1, 192.168.0.202/24와 sipmon UI 15011을 기준으로 한 사용자 실행 안내 예시임. 신규 앱에서는 재조회한 주소·서브넷·배정 UI 포트로 바꿔 안내하고, 기존 허용 규칙·Serve 등록이 있는지도 먼저 확인함. just dev-tailnet-serve recipe에 새 포트를 추가한 것만으로 실제 등록이 끝났다고 판단하지 않음.
# 홈서버에서 실행: 현재 허용 규칙 및 Tailnet 등록 확인
sudo ufw status numbered
tailscale serve status

# 미적용 항목만 실행: 내부망 UI 포트 허용 및 Tailnet HTTPS 등록
sudo ufw allow in on eno1 from 192.168.0.0/24 to 192.168.0.202 port 15011 proto tcp
sudo tailscale serve --bg --https=15011 http://127.0.0.1:15011

# 적용 후 설정 확인
sudo ufw status numbered
tailscale serve status
  • 설정 확인 후 실제 개인 PC·휴대폰에서 LAN URL과 Tailnet HTTPS URL의 접속 및 Hub 로그인 복귀를 검증함. 해당 기기에서 검증할 수 없으면 미검증으로 남기고 사용자 확인 방법을 안내함. 운영 배포와 사용자 앱 권한 부여는 별도 요청 범위에 따름.

5. 운영 컨테이너 포트 통일 규칙​

이 규칙은 기존 서비스 변경과 신규 서비스 추가에 모두 적용하며, 어긴 변경은 완료로 보지 않음.

  • 운영 Docker 서비스의 컨테이너 내부 포트는 모두 8080임. 서비스별 번호(8001~8013 등)를 새로 배정하거나 되살리지 않음.
  • Dockerfile은 EXPOSE 8080과 uvicorn ... --host 0.0.0.0 --port 8080을 사용하며 운영 Compose의 PORT도 8080임.
  • 운영 Compose는 호스트 ports:를 공개하지 않음. 외부 공개는 Cloudflare Tunnel이 같은 Docker 네트워크의 http://<서비스명>:8080으로 연결함.
  • 서비스 간 내부 호출 URL(*_BASE_URL, *_INTERNAL_BASE_URL)은 http://<서비스명>:8080 형식을 사용함. 이 값은 Compose 환경변수, 환경 파일(.env.prod, /sorc001/junkbox/env), 코드 기본값에 걸쳐 일치해야 함.
  • Automation API·워커가 호출하는 대상 모듈(MESSAGE·HEALTH·TRACK·CHESS·WOW)의 *_BASE_URL은 Compose 환경변수로 내부 주소를 지정함. 환경 파일의 공개 주소를 쓰면 Cloudflare의 약 100초 응답 제한에 걸려 오래 걸리는 작업이 524로 끊김.
  • 호스트 관리 도구·백업 스크립트가 호출하는 Hub와 Message는 loopback publish를 사용함. 새 loopback publish는 호출 주체와 사유를 이 절에 기록함.
  • 로컬 개발 포트는 이 규칙과 별개로 15xxx(Vite)·18xxx(FastAPI) 쌍을 유지함. 개발 Compose는 180xx:8080으로 매핑하며 로컬 uvicorn은 180xx를 직접 사용함.
  • GitHub Actions deploy-services.yml의 port는 컨테이너 내부 포트 8080을 뜻함. 호스트의 8080 포트를 프로세스 정리 대상으로 사용하지 않음.
  • Hub의 마스터데이터 캐시 갱신 대상은 컨테이너 내부 8080을 사용함.

서비스 변경·추가 시 갱신 체크리스트

  1. Dockerfile EXPOSE·CMD와 운영·개발 Compose의 PORT, ports:(운영은 공개하지 않음, 개발은 180xx:8080)를 규칙에 맞춤.
  2. 서비스 간 호출 URL과 환경 파일(.env.prod 및 /sorc001/junkbox/env의 대응 파일, .env.example 계열)의 :8080 일치를 확인함.
  3. .github/deploy/deploy-services.yml의 port와 배포 스크립트(deploy-server.sh)의 포트 의존 로직을 확인함.
  4. Cloudflare Tunnel 대상을 http://<서비스명>:8080으로 등록·변경함. 실제 Tunnel 반영은 별도 운영 작업임.
  5. 신규 앱 가이드에는 운영 포트를 번호로 적지 않고 이 절로 연결하며, 호스트 loopback publish가 필요하면 이 절의 예외 목록을 갱신함.
  6. 변경 뒤 rg '\b80(0[1-9]|1[0-9])\b'로 옛 서비스별 운영 포트 잔여 설명을 검색하고, Vault 가이드·AGENTS.md·앱 README를 함께 갱신함.

5.1 컨테이너 이름 통일 규칙​

이 규칙은 기존 서비스 변경과 신규 서비스 추가에 모두 적용하며, 어긴 변경은 완료로 보지 않음.

  • 모든 Compose 서비스는 container_name을 명시함. 명시하지 않으면 Compose가 <프로젝트>-<서비스명>-<번호>(예: junkbox-junkbox-knowbit-1)로 이름을 만들어 서비스 간 이름 형식이 갈라짐.
  • 운영 docker-compose.prod.yml의 container_name은 서비스명과 같은 junkbox-<서비스명>임. 서비스명이 이미 junkbox- 접두어를 가지므로 접두어를 다시 붙이지 않음.
  • 개발 docker-compose.yml의 container_name은 junkbox-<서비스명>-dev임. 운영 컨테이너와 이름이 겹치지 않게 하기 위함임.
  • 이름이 고정되어야 docker logs·docker exec·Hub 도커 상태 카드·알림에서 같은 이름으로 서비스를 찾을 수 있음.
  • 배포 스크립트(deploy-server.sh)와 서비스 간 호출은 Compose 서비스명을 사용하므로 컨테이너 이름에 의존하지 않음. 컨테이너 이름은 사람과 운영 도구가 식별하는 용도임.
  • .github/deploy/deploy_config.mjs validate가 운영 Compose 서비스의 container_name이 서비스명과 같은지 검사하며 실패하면 배포 파이프라인이 시작되지 않음. 개발 Compose는 검사 대상이 아니므로 변경할 때마다 직접 확인함.

서비스 변경·추가 시 갱신 체크리스트

  1. 운영·개발 Compose 모두에 container_name을 규칙대로 명시함.
  2. deploy_config.mjs validate를 실행해 운영 Compose 검사를 통과시킴.
  3. 개발 Compose는 rg -n "^ junkbox-|container_name" docker-compose.yml로 서비스마다 -dev 이름이 있는지 확인함.
  4. 기존 서비스에 container_name을 추가·변경하면 배포 때 컨테이너가 재생성되며 옛 이름의 컨테이너가 남지 않았는지 docker ps -a로 확인함.

6. 운영 배포와 환경​

6.1 배포 구조​

  • 각 UI 앱의 빌드 결과물 dist와 Vite manifest는 해당 백엔드 앱이 직접 서빙하는 운영 자산임.
  • 운영 배포는 docker-compose.prod.yml 기준 독립 컨테이너 구조를 사용하며, automation-api와 automation worker는 같은 junkbox-automation 이미지를 별도 서비스로 실행함.
  • 운영 배포 자동화는 GitHub Actions selective build/deploy 흐름을 사용하며, 각 앱은 독립 서비스 단위로 감지, 빌드, 배포됨. 트리거는 main push와 수동 실행(workflow_dispatch)뿐이며 pull_request는 사용하지 않음.
  • 배포 Job은 홈서버의 self-hosted runner(라벨 junkbox-prod)에서 실행하므로 공개 SSH를 거치지 않음. 이는 연결 불안정이 배포 중단으로 이어지지 않게 하기 위함임.
  • 실제 교체는 .github/deploy/deploy-server.sh가 담당하며 서버에서 직접 실행할 수도 있음.
    • 새 이미지 pull이 성공한 서비스만 up -d --wait로 교체하고, pull이 실패하면 기존 컨테이너를 유지한 채 나머지를 계속 배포한 뒤 마지막에 Job을 실패 처리함.
    • 변경 감지는 push의 before..sha 전체를 비교함. Compose·정책만 바뀌면 이미지 교체 없이 설정만 반영하고, 배포 스크립트·ops/backup만 바뀌면 서버 파일만 동기화함.
    • 배포한 커밋 SHA 태그는 서버 /sorc001/junkbox/deploy-images.env에 기록되며, 서버에서 Compose를 직접 실행할 때는 deploy-server.sh compose를 사용해야 이 태그가 적용됨.
    • 기동 확인에 실패해도 자동 롤백하지 않음. 이전 이미지는 <repo>:rollback 태그로 보존되며 deploy-server.sh rollback <서비스>로 수동 복구함. 상태와 이력은 deploy-server.sh status와 /sorc001/junkbox/deploy-state/에서 확인함.
    • 이미지 정리는 모든 서비스가 성공했을 때 JunkBox 이미지(ghcr.io/<owner>/junkbox-*)에 한해 수행함.
  • 운영 CDN이 고정 경로 정적 자산을 오래 캐시할 수 있으므로, 공통 shared-ui CSS/JS는 버전 쿼리 파라미터 링크를 기본 구조로 사용함.
  • 운영 배포 compose는 /sorc001/junkbox/db를 각 앱 컨테이너의 /app/db에 마운트함.
  • 운영 배포 compose는 automation-api=/logs001/junkbox/automation-api, automation-worker=/logs001/junkbox/automation-worker를 포함한 앱별 호스트 로그 경로를 각 컨테이너의 /app/logs에 마운트하는 구조를 사용함.
  • 각 백엔드 컨테이너의 공통 애플리케이션 로그 파일 경로는 /app/logs/app.log임.
  • 로컬 개발 로그는 프로젝트 루트의 var/log/{app-name} 하위에 생성되며 Git 추적 대상이 아님.
  • 로그 파일 rotation, retention, compression, diagnose 정책은 shared-core의 공통 로깅 초기화와 .env.shared 및 실행 앱별 profile env 파일 조합이 결정함.
  • rename-api는 ${RENAME_BASE_DIR}:${RENAME_BASE_DIR} 동일 경로 바인드 마운트를 전제로 동작하며, RENAME_TARGET_DIR_NAME은 마운트된 작업 루트 내부의 입력 작업 폴더를 지정함.

6.2 운영 환경 파일과 점검 값​

  • 운영 Chess 컨테이너는 /sorc001/junkbox/env/.env.chess, /sorc001/junkbox/env/.env.shared, /sorc001/junkbox/env/.env.prod를 참조하고, ENV_FILE=/app/env/.env.prod 기준으로 로딩함.
  • 프로젝트 루트의 .env.chess, .env.prod, .env.shared를 운영 env 디렉터리에 반영할 때는 just env-copy-to-sorc001 또는 이를 호출하는 VS Code build task env:copy-to-sorc001 흐름을 사용함. 두 경로 모두 scripts/copy_env_files.sh의 Enter 확인 절차를 유지함.
  • 로컬 AI 라우팅 Git 원본은 apps/hub-api/var/master-data를 사용하고, 운영 런타임은 /sorc001/junkbox/master-data/ai-routing.yml 공유 파일을 사용함.
  • 운영에서는 APP_PROFILE=prod, HUB_BASE_URL=https://hub.sleepzz.xyz, HUB_DATABASE_URL=sqlite+aiosqlite:////app/db/hub.sqlite3, CHESS_BASE_URL, CHESS_DATABASE_URL=sqlite+aiosqlite:////app/db/chess.sqlite3, HEALTH_BASE_URL=https://health.sleepzz.xyz, HEALTH_DATABASE_URL=sqlite+aiosqlite:////app/db/health.sqlite3, WOW_BASE_URL=https://wow.sleepzz.xyz, WOW_DATABASE_URL=sqlite+aiosqlite:////app/db/wow.sqlite3, HUB_INTERNAL_BASE_URL, COOKIE_DOMAIN=.sleepzz.xyz, COOKIE_SECURE=true 값을 우선 점검함.
  • 운영 기본 bridge network 컨테이너의 HUB_INTERNAL_BASE_URL은 http://junkbox-hub:8080 계열 Docker DNS 주소를 사용함.
  • 레이드 운영에서는 WCL_CLIENT_ID, WCL_CLIENT_SECRET, WCL_API_URL, WCL_TOKEN_URL, WCL_MAX_CONCURRENCY 값을 함께 점검함.
  • 체스 운영에서는 CHESS_DATABASE_URL, Lichess OAuth 설정, Stockfish 실행 파일 경로와 분석 제한값, JUNKBOX_CHESS_RESTART_POLICY 값을 함께 점검함.
  • hub-api 세션 정책 파일은 apps/hub-api/var/auth-policy.yml이며, 운영 컨테이너에서는 동일 경로가 이미지 또는 마운트에 포함되어야 함.

6.3 토큰​

  • HUB_API_INTERNAL_TOKEN은 Hub 외 앱이 hub-api 내부 인증 API, 내부 master-data API, AI usage-log 기록 API를 호출할 때 사용하는 서버 간 토큰임.
  • AI_ACCESS_TOKEN은 AI 에이전트 전용 ROLE_AI JWT 값이며 scripts/.env.ai에 보관함.
  • FASTAPI_BASE_URL은 scripts/fetch_master_data.py가 호출할 hub-api base URL임.
  • JWT_SECRET_KEY와 HUB_API_INTERNAL_TOKEN은 용도가 다르므로 서로 다른 랜덤 값을 사용하는 것을 기본 원칙으로 함.
  • AI_ACCESS_TOKEN은 사용자 인증 JWT, 서버 간 내부 토큰과 분리된 별도 값으로 관리함.

7. 개발 문서 벡터 캐시​

  • vault/docs/**/*.md 문서 원본은 사람이 Git으로 검증하고 커밋하는 Source of Truth임.
  • vault/docs/junkbox/**/*.md는 JunkBox 개발 가이드 문서 원본이며 docs/junkbox/common, docs/junkbox/libs, docs/junkbox/apps, docs/junkbox/domain으로 책임을 나눔.
  • vault 스키마의 문서 벡터 테이블은 AI 에이전트가 필요한 문서 chunk를 먼저 찾기 위한 읽기 최적화 캐시임.
  • 개발 문서 벡터 캐시는 로컬 markdown 원본에서 DB로만 동기화되며, DB 내용을 markdown으로 역동기화하지 않음.
  • scripts/sync_dev_docs.py는 vault/docs/junkbox/**/*.md 파일을 스캔하고 SHA-256 해시로 변경을 감지하여 vault.docs, vault.doc_chunks, vault.doc_embeddings, vault.index_runs에 반영함. 인덱스에 남은 다른 Vault 문서도 삭제 대상에 포함됨.
  • 변경되지 않은 문서는 임베딩을 재생성하지 않음.
  • 변경된 문서는 기존 chunk와 embedding을 문서 기준으로 교체하고 새 chunk를 임베딩하여 저장함.
  • 로컬 스캔 대상에 없는 인덱스 문서는 vault.docs.deleted_at에 삭제 시각을 기록하고 검색에서 제외함. 해당 문서의 chunk와 embedding은 row와 함께 보존되며, 같은 경로의 문서가 다시 들어오면 활성화된 문서 내용으로 교체됨.
  • scripts/search_dev_docs.py는 검색 query를 임베딩한 뒤 vault.doc_embeddings에서 cosine similarity 기준 상위 chunk를 조회함.
  • AI 작업 프롬프트는 vault/docs/junkbox 전체 파일을 무작정 읽기보다 scripts/search_dev_docs.py 검색 결과의 source, namespace, kind, project, heading, chunk를 기준으로 필요한 원본 문서만 좁혀 읽는 흐름을 우선함.

7.1 vault 스키마​

  • AI 개발 지식 캐시는 vault 스키마를 사용함.
  • vault.docs는 markdown 파일 단위의 원본 경로, 제목, route, namespace, kind, project, frontmatter, content hash, 삭제 상태를 저장함.
  • vault.doc_chunks는 문서를 heading 기반 chunk로 나눈 검색 단위이며 heading_path, heading_level, content, content_hash, token_count, metadata를 포함함.
  • vault.doc_embeddings는 chunk별 VECTOR(1536) 임베딩을 저장하며 embedding_model, embedding_dimension, content_hash를 함께 보관함.
  • vault.index_runs는 문서 색인 실행 이력, 처리 파일 수, 변경/삭제 수, chunk 수, 오류 메시지를 기록함.
  • content_hash는 SHA-256 기반 변경 감지에 사용됨.
  • vault.docs.deleted_at IS NOT NULL은 로컬 원본에서 사라져 검색 대상에서 제외된 문서를 나타냄. 다시 동기화되는 문서는 같은 source_path row의 deleted_at을 NULL로 되돌림.
  • jb_ai 계정은 vault 스키마 내 기존 테이블 데이터 CRUD와 시퀀스 사용 권한을 가진 AI 전용 계정이며 앱 구동 계정 jb_app과 분리됨.

8. 관련 문서​

  • 앱 목록과 문서 체계는 docs/junkbox/common/guide-jb-overview.md를 따름.
  • 구조 원칙과 공통 계약은 docs/junkbox/common/guide-jb-core.md를 따름.
  • 공통 설정 계층 구현은 docs/junkbox/libs/guide-lib-shared-core.md를 따름.
  • 개발 문서 벡터 동기화 구현은 docs/junkbox/libs/guide-lib-shared-ai.md를 따름.