콘텐츠로 이동

OCI 정적 배포 가이드

이 문서는 wiki.nornen.net을 OCI 인스턴스에서 직접 서빙할 때 필요한 최소 정적 배포 절차를 정리합니다. 전제는 이 위키가 애플리케이션 서버 없이 정적 파일만 서빙된다는 점입니다.

적합성

  • 현재 위키는 MkDocs + Material 정적 사이트입니다.
  • site/ 산출물은 작고, 앱 서버나 데이터베이스가 필요하지 않습니다.
  • 따라서 VM.Standard.E2.1.Micro (1 OCPU, 1GB RAM)에서도 충분히 운영 가능합니다.

권장 구조

  • 웹서버: Caddy 컨테이너
  • 도메인: wiki.nornen.net
  • 정적 루트: /var/www/wiki.nornen.net/site
  • bluecafe 정적 루트: /var/www/bluecafe
  • 인증서: Caddy 자동 TLS

저장소 안의 준비 파일:

  • deploy/oci/caddy/Caddyfile
  • scripts/prepare_oci_static_bundle.py
  • sites/bluecafe/
  • make oci-bundle

로컬에서 배포 산출물 만들기

make oci-bundle

완료되면 .oci-static/ 아래에 아래가 생성됩니다.

  • site/
  • wiki.nornen.net.Caddyfile.example
  • README.md

OCI 서버 준비

현재 운영 기준은 Caddy 컨테이너입니다. 서버에 docker만 있으면 충분합니다.

필수 디렉터리:

sudo mkdir -p /var/www/wiki.nornen.net/site
sudo mkdir -p /var/www/wiki.nornen.net
sudo chown -R opc:opc /var/www/wiki.nornen.net

서버 반영

  1. .oci-static/site/ 내용을 /var/www/wiki.nornen.net/site로 복사
  2. Caddy 설정이 바뀌어야 할 때만 .oci-static/wiki.nornen.net.Caddyfile.example의 wiki.nornen.net 블록을 기존 /var/www/wiki.nornen.net/Caddyfile에 병합
  3. bluecafe.kr, www.bluecafe.kr 같은 기존 도메인 블록은 유지
  4. caddy:2 컨테이너를 재시작하거나, 최초 1회만 실행

예시:

정적 파일만 갱신할 때:

sudo rm -rf /var/www/wiki.nornen.net/site
sudo mv /tmp/wiki-site /var/www/wiki.nornen.net/site
sudo docker restart wiki-caddy

Caddy 설정까지 갱신해야 할 때:

# 1) /tmp/wiki.nornen.net.Caddyfile.example 를 참고해
#    기존 /var/www/wiki.nornen.net/Caddyfile 안의 wiki.nornen.net 블록만 교체
# 2) bluecafe.kr / www.bluecafe.kr 같은 다른 블록은 그대로 유지
sudo docker restart wiki-caddy

최초 1회 컨테이너 생성 예시:

sudo docker rm -f wiki-caddy || true
sudo docker run -d \
  --name wiki-caddy \
  --restart unless-stopped \
  -p 80:80 -p 443:443 \
  -v /var/www/wiki.nornen.net/site:/srv/wiki:ro \
  -v /var/www/bluecafe:/srv/bluecafe:ro \
  -v /var/www/wiki.nornen.net/Caddyfile:/etc/caddy/Caddyfile:ro \
  -v /var/lib/wiki-caddy-data:/data \
  -v /var/lib/wiki-caddy-config:/config \
  caddy:2

TLS 적용

Caddy를 쓰면 wiki.nornen.net에 대한 TLS는 자동으로 발급·갱신됩니다. 별도 certbot은 필요하지 않습니다.

갱신 절차

위키 콘텐츠를 갱신할 때는 아래 순서면 충분합니다.

  1. 로컬에서 make verify
  2. 로컬에서 make oci-bundle
  3. .oci-static/site/만 서버로 복사
  4. sudo docker restart wiki-caddy

정적 파일만 바뀌면 컨테이너 재생성보다 restart면 충분합니다.

운영 메모

  • 이 인스턴스 크기에서는 mkdocs serve, Playwright, 대규모 CI 같은 무거운 작업을 서버에서 돌리지 않는 편이 좋습니다.
  • OCI VM은 정적 파일 서빙만 담당하고, 빌드는 로컬에서 끝내는 구성이 가장 안전합니다.
  • 현재 실제 배포는 Caddy 컨테이너 기준으로 맞춰 두었습니다.
  • 운영 서버의 /var/www/wiki.nornen.net/Caddyfile가 여러 도메인(wiki.nornen.net, bluecafe.kr, www.bluecafe.kr)을 함께 담고 있다면, 위키 배포 시 다른 도메인 블록을 삭제하거나 덮어쓰지 않습니다.
  • wiki와 bluecafe를 한 컨테이너에서 함께 서빙할 때는 /srv와 /srv/bluecafe처럼 중첩 bind mount를 피하고, /srv/wiki, /srv/bluecafe처럼 분리된 루트를 쓰는 편이 안전합니다.
  • bluecafe.kr 정적 원본은 이 저장소의 sites/bluecafe/에 같이 보관해 서버와 Git 이력을 맞춥니다.
  • Vercel 배포와 병행할 수도 있지만, DNS를 OCI로 붙였으면 운영 기준은 이 문서를 따르는 편이 명확합니다.