운영 & 배포

프로덕션 환경은 nginx(정적 서빙) + cloudflared(터널) 조합으로 data-sketchers.com 을 서빙합니다. 이 문서는 컨테이너 구성과 주의사항을 다룹니다.

운영 URL

프로덕션: https://data-sketchers.com — 모두 cloudflared 터널을 통해 유입됩니다.

---

nginx 설정

nginx 컨테이너는 정적 사이트 결과물을 서빙하고, 향후 /api를 Go 백엔드로 프록시할 예정입니다.

infra/nginx.conf

server {
    listen 80;
    server_name data-sketchers.com;

    root /usr/share/nginx/html;
    index index.html;

    # 클린 URL: 확장자 없는 경로를 .html로 매핑 (use_directory_urls: false 대응)
    location / {
        try_files $uri $uri/ $uri.html =404;
    }

    # Astro 정적 에셋은 내용 기반 해시 → 롱캐시
    location /_astro/ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }

    # TODO: /api → Go 백엔드 프록시 (미구현)
    # location /api/ {
    #     proxy_pass http://api:8080;
    #     proxy_set_header Host $host;
    #     proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    # }
}

location	동작
/	try_files 로 클린 URL → .html 매핑
/_astro/	해시 기반 에셋 1년 롱캐시 (immutable)
/api/	Go 백엔드 프록시 (TODO, 주석 처리)

try_files 순서

$uri.html 을 $uri/ 뒤에 두는 것이 중요합니다. 디렉터리 인덱스를 먼저 확보해야 폴더 경로가 깨지지 않습니다. 위키는 use_directory_urls: false이므로 확장자 붙은 경로(foo.html)로도 접근 가능합니다.

---

docker-compose

nginx 서비스와 cloudflared 터널 서비스를 함께 기동합니다.

infra/docker-compose.yml

services:
  nginx:
    image: ${REGISTRY_IMAGE}
    restart: unless-stopped
    networks: [web]
    ports:
      - "8080:80"

  cloudflared:
    image: cloudflare/cloudflared:latest
    restart: unless-stopped
    command: tunnel --no-autoupdate run --token ${TUNNEL_TOKEN}
    networks: [web]

networks:
  web:

시크릿 관리 — TUNNEL_TOKEN

TUNNEL_TOKEN 은 cloudflared가 외부 트래픽을 내부 컨테이너로 넣는 데 필요한 토큰입니다. 반드시 GitLab CI/CD 변수(마스크 등) 나 비밀 저장소에서 주입하세요. - 절대 커밋하지 말 것 — .env/.gitignore 대상 - 로컬에서도 토큰이 터미널 로그에 노출되지 않게 유의 - 토큰 유출 시 Cloudflare 대시보드에서 즉시 재발급

---

배포 절차 요약

# 1) CI가 kaniko로 이미지 빌드·push
# 2) deploy 스테이지가 ds-20000 호스트에서:
cd /srv/data-sketchers
docker compose pull
docker compose up -d

# 3) cloudflared가 터널로 트래픽 유입
# 4) https://data-sketchers.com 확인

배포 파이프라인의 자세한 내용은 CI/CD를 참고하세요.

---

운영 체크리스트

• 배포 후 https://data-sketchers.com 정상 응답 확인
• 새 정적 에셋이 /_astro/ 롱캐시 규칙을 따르는지 확인
• TUNNEL_TOKEN 이 CI/CD 변수에만 존재(커밋 아님) 확인
• 동적 기능을 쓴다면 /api 프록시 TODO 해결 확인
• 로그는 docker compose logs -f nginx cloudflared 로 모니터링

비밀정보를 코드에 넣지 말 것

어떤 시크릿(키, 토큰, 비밀번호)도 infra/ 아래 마크다운·yaml에 직접 하드코딩하지 마세요. 항상 CI/CD 변수 또는 시크릿 매니저를 사용하세요.