인증 패턴

Yundera App Store의 모든 앱에서 인증은 필수입니다. 예외는 rationale.md 파일에서 정당화되어야 합니다. 세 가지 지원 패턴이 있습니다.

패턴 1 — AppShield SSO (권장)

AppShield 사이드카가 인증을 처리합니다. 백엔드는 내부 pcs 네트워크에서 사이드카를 통해서만 접근 가능하며 직접 노출되지 않습니다.

대부분의 앱에 권장되는 패턴입니다. 전체 compose 설정은 전체 템플릿을 참조하세요.

예시: ConvertX, Spliit, Netdata, Stremio, Terminal, Tribler.

패턴 2 — AppShield + 앱 자체 인증 비활성화

일부 백엔드는 자체 로그인 시스템을 가지고 있습니다. AppShield를 사용할 때는 백엔드의 내장 인증을 비활성화하여 사용자가 두 번 로그인하지 않도록 합니다.

myapp-backend:
  environment:
    # 백엔드의 자체 인증 비활성화
    AUTHENTICATION_ENABLED: "false"  # 앱마다 다름

구체적인 환경 변수는 애플리케이션에 따라 다릅니다.

패턴 3 — 앱이 자체 인증 유지 (AppShield 없음)

앱의 인증을 비활성화할 수 없거나 하면 안 될 때, Caddy 레이블로 앱을 직접 노출하고 앱이 자체적으로 로그인을 처리하도록 합니다.

tips.before_install에 기본 자격 증명을 문서화하세요:

x-casaos:
  tips:
    before_install:
      en_us: |
        ## 기본 자격 증명
        | 사용자명 | 비밀번호 |
        |----------|----------|
        | `admin`  | `$APP_DEFAULT_PASSWORD` |

예시: Jellyfin, Immich, n8n, Stirling-PDF.

주의

compose 파일에 비밀번호를 하드코딩하지 마세요. 생성된 자격 증명에는 항상 $APP_DEFAULT_PASSWORD를 사용하세요.

체크리스트

PR 제출 전:

• 인증이 활성화되고 문서화됨
• AppShield이 특정 버전으로 고정 (현재 ghcr.io/yundera/appshield:2.0.3)
• 사이드카 container_name이 최상위 name:과 동일
• Caddy 레이블이 사이드카에만 존재
• 백엔드에 ports:나 Caddy 레이블 없음
• 어디에도 auth-${APP_DOMAIN} 레이블 없음
• 하드코딩된 자격 증명 없음
• AppShield 사용 시 index: /?hash=$AUTH_HASH 설정됨