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
인증서: Caddy 자동 TLS

저장소 안의 준비 파일:

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

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

make oci-bundle

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

site/
Caddyfile
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

서버 반영¶

.oci-static/site/ 내용을 /var/www/wiki.nornen.net/site로 복사
.oci-static/Caddyfile를 /var/www/wiki.nornen.net/Caddyfile로 복사
caddy:2 컨테이너를 80/443으로 실행

예시:

sudo rm -rf /var/www/wiki.nornen.net/site
sudo mv /tmp/wiki-site /var/www/wiki.nornen.net/site
sudo mv /tmp/Caddyfile /var/www/wiki.nornen.net/Caddyfile
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: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은 필요하지 않습니다.

갱신 절차¶

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

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

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

운영 메모¶

이 인스턴스 크기에서는 mkdocs serve, Playwright, 대규모 CI 같은 무거운 작업을 서버에서 돌리지 않는 편이 좋습니다.
OCI VM은 정적 파일 서빙만 담당하고, 빌드는 로컬에서 끝내는 구성이 가장 안전합니다.
현재 실제 배포는 Caddy 컨테이너 기준으로 맞춰 두었습니다.
Vercel 배포와 병행할 수도 있지만, DNS를 OCI로 붙였으면 운영 기준은 이 문서를 따르는 편이 명확합니다.