서버 배포 및 운영

인프라 개요

사용자 (Tailscale VPN)
  ↓ HTTPS
anki.greenhead.dev (Caddy, :443)
  ↓ reverse_proxy
awesome-anki 컨테이너 (Podman, :3100)
  ↓ host network
AnkiConnect (headless Anki, :8765)
  ↓ 5분 주기 sync
Anki Sync Server (:27701)

MiniPC 접속

• 호스트명: greenhead-minipc
• Tailscale IP: 100.79.80.95
• SSH: ssh greenhead@100.79.80.95 (키 인증만 허용, 비밀번호 불가)
• NixOS 설정: ~/Workspace/nixos-config (GitHub: greenheadHQ/nixos-config)

컨테이너 구성

--network=host를 사용하는 이유: AnkiConnect가 Tailscale IP(100.79.80.95:8765)에서만 리스닝하므로, 컨테이너가 호스트 네트워크 스택을 공유해야 접근 가능. Tailscale 방화벽 + WireGuard 암호화로 보안 보장.

환경변수

환경변수 파일은 awesome-anki-env systemd oneshot 서비스가 agenix 시크릿을 복호화하여 /run/awesome-anki-env에 생성.

리버스 프록시 (Caddy)

• 도메인: anki.greenhead.dev
• 바인드: Tailscale IP만 (100.79.80.95:443)
• SSL: Cloudflare DNS-01 ACME (Let's Encrypt 자동 갱신)
• 보안 헤더: HSTS, X-Content-Type-Options, X-Frame-Options
• NixOS 설정: ~/Workspace/nixos-config/modules/nixos/programs/caddy.nix

systemd 서비스 기동 순서

tailscaled → anki-sync-server → anki-connect
                                      ↓
caddy-env → caddy       awesome-anki-env → podman-awesome-anki

핵심 의존성: awesome-anki-env (시크릿 복호화) 완료 후에만 컨테이너 시작.

CI/CD 파이프라인

1. main push 또는 v* 태그 push → GitHub Actions 트리거
2. Docker Buildx로 이미지 빌드 (GHA 캐시)
3. ghcr.io/greenheadhq/awesome-anki 레지스트리에 push
4. MiniPC awesome-anki-auto-update 타이머 (5분 주기)가 latest digest 변경 감지 → systemctl restart로 교체

태그 전략

자동 배포 흐름

main push → GitHub Actions (~3분) → GHCR latest 갱신
  → MiniPC awesome-anki-auto-update (5분 주기) → digest 변경 감지
  → podman pull → systemctl restart (10-30초 다운타임)

실패 시 이전 이미지로 자동 롤백. Tailscale 내부망 전용이므로 짧은 다운타임 수용.

빠른 작업 명령어

컨테이너 관리

# 상태 확인
systemctl status podman-awesome-anki

# 로그 확인
podman logs awesome-anki
journalctl -u podman-awesome-anki -n 50

# 재시작
systemctl restart podman-awesome-anki

# 이미지 업데이트 (자동)
# 5분마다 자동 실행 — 수동 개입 불필요
systemctl status awesome-anki-auto-update.timer  # 타이머 상태
journalctl -u awesome-anki-auto-update -n 10     # 업데이트 로그

# 이미지 업데이트 (수동 — 긴급 시)
podman pull ghcr.io/greenheadhq/awesome-anki:latest
systemctl restart podman-awesome-anki

AnkiConnect 관리

# 상태 확인
systemctl status anki-connect
curl http://100.79.80.95:8765

# 재시작
systemctl restart anki-connect

# 수동 동기화
systemctl start anki-connect-sync

NixOS 설정 변경

# MiniPC에서 직접
cd ~/Workspace/nixos-config
sudo nixos-rebuild switch --flake .#greenhead-minipc

# MacBook에서 원격
nixos-rebuild switch --flake .#greenhead-minipc --target-host greenhead@100.79.80.95

데이터 경로

Health Check

• 엔드포인트: GET /api/health (인증 불필요)
• 응답: { status: "ok", timestamp: "..." }
• Docker: 30초 간격, 5초 타임아웃, 3회 재시도, 30초 시작 대기
• 확인: curl https://anki.greenhead.dev/api/health

상세 참조

• references/nixos-config.md — NixOS 모듈 구조, 설정 옵션, 서비스 의존성
• references/container-setup.md — Dockerfile, CI/CD, 볼륨, 이미지 관리
• references/troubleshooting.md — 컨테이너/AnkiConnect/Caddy/NixOS 문제 해결