앱 추가하기

Yundera App Store에 새 앱을 추가하는 전체 참조입니다. 빠른 개요는 기여 개요를 참조하세요.

최소 템플릿 (AppShield SSO)

권장 패턴: AppShield 사이드카가 백엔드를 보호하고 Yundera SSO를 제공. 백엔드는 직접 노출되지 않으며 사이드카만 라우팅 레이블을 받습니다.

name: myapp   # 소문자 영숫자 + 하이픈, 숫자로 시작 불가

services:
  myapp:                                    # ← AppShield 사이드카 (공개 대면)
    image: ghcr.io/yundera/appshield:2.0.3  # 버전 고정; 절대 :latest 사용 금지
    container_name: myapp                   # 최상위 name:과 반드시 동일
    restart: unless-stopped
    user: "root"
    expose:
      - 80
    labels:
      caddy_0: myapp-${APP_DOMAIN}
      caddy_0.import: gateway_tls
      caddy_0.reverse_proxy: "{{upstreams 80}}"
    environment:
      AUTH_HASH: $AUTH_HASH
      BACKEND_HOST: "myapp-backend"
      BACKEND_PORT: "80"
      LISTEN_PORT: "80"
      OIDC_REGISTRAR_URL: "http://auth-registrar:9092"
      REDIRECT_HOST_SUFFIXES: "${APP_DOMAIN},${APP_PUBLIC_IP_DASH}.nip.io,${APP_PUBLIC_IP_DASH}.sslip.io"
      CREDENTIAL_VALIDATE_URL: "http://casaos-oidc-bridge:8090/validate"
    depends_on:
      - myapp-backend
    cpu_shares: 80
    networks:
      - pcs

  myapp-backend:                            # ← 실제 앱 (내부 전용)
    image: someimage:1.2.3
    container_name: myapp-backend
    restart: unless-stopped
    user: "0:0"
    expose:
      - 80
    environment:
      TZ: $TZ
    volumes:
      - /DATA/AppData/$AppID/data/:/app/data/
    cpu_shares: 50
    networks:
      - pcs

networks:
  pcs:
    name: pcs
    external: true

네이밍 규칙 (중요)

사이드카의 container_name은 최상위 name:과 반드시 동일해야 합니다. 이것은 구조적으로 중요합니다: auth registrar가 pcs 네트워크의 PTR 룩업을 통해 컨테이너 이름에서 OIDC client_id를 파생합니다. 일치하지 않으면 SSO 등록이 조용히 실패합니다.

규칙:

• name: / 사이드카 container_name: 소문자 영숫자 + 하이픈, 숫자로 시작 불가.
• Caddy 레이블은 사이드카에만 — 절대 백엔드에 붙이지 마세요.
• 백엔드에는 ports:와 Caddy 레이블 없음.
• 절대 auth-${APP_DOMAIN}을 Caddy 레이블에 사용하지 마세요 — PCS의 Authelia와 충돌합니다.

볼륨 경로

volumes:
  - /DATA/AppData/$AppID/config/:/app/config    # 앱 설정
  - /DATA/AppData/$AppID/data/:/app/data        # 앱 데이터 / DB
  - /DATA/Media/Music/:/music:ro                # 공유 미디어 (읽기 전용)

중요

볼륨 경로의 호스트 측에 항상 **후행 /**를 추가하세요. 없으면 CasaOS가 $AppID를 올바르게 해석하지 못하고 파일이 /DATA/AppData/에 직접 생성됩니다.

리소스 제한

cpu_shares는 모든 서비스에 필수입니다.

cpu_shares	사용 사례
80	사이드카, 웹 프론트엔드
70	백그라운드 작업이 있는 메인 앱
50	표준 백엔드 서비스
30	데이터베이스, 캐시
20	ML / 배치 처리

시스템 변수

설치 시 주입되는 변수:

변수	예시	사용
$APP_DOMAIN	yourname.nsl.sh	https://myapp-${APP_DOMAIN}
$APP_PUBLIC_IP_DASH	203-0-113-42	nip.io / sslip.io 레이블
$AUTH_HASH	(생성됨)	AppShield 토큰
$APP_DEFAULT_PASSWORD	(생성됨)	초기 관리자 비밀번호
$AppID	myapp	볼륨 경로: /DATA/AppData/$AppID/
$PUID / $PGID	1000 / 1000	파일 소유권
$TZ	Asia/Seoul	시간대