본문으로 건너뛰기

Team Library 도메인 및 HTTPS 배포 가이드

목적​

team-library.biny.cloud를 Docusaurus 정적 사이트에 연결하고, nginx와 HTTPS까지 안정적으로 운영하기 위한 기준 문서입니다.

적용 대상​

  • 도메인: team-library.biny.cloud
  • 프로젝트 경로: /root/.openclaw/workspace/docusaurus-team-library
  • 배포 경로: /var/www/team-library
  • 웹서버: nginx

구성 요약​

  • 콘텐츠 원본: docusaurus-team-library/
  • 빌드 결과물: docusaurus-team-library/build/
  • 실제 서비스 경로: /var/www/team-library
  • nginx 적용 파일: /etc/nginx/sites-available/team-library
  • nginx enable 링크: /etc/nginx/sites-enabled/team-library
  • 인증서 경로: /etc/letsencrypt/live/team-library.biny.cloud/

선행 조건​

  • DNS에서 team-library.biny.cloud가 현재 서버 IP를 가리켜야 합니다.
  • 프로젝트에서 npm run build가 정상 동작해야 합니다.
  • 서버에 nginx와 certbot이 설치되어 있어야 합니다.

1. 빌드 생성​

프로젝트 폴더로 이동한 뒤 정적 사이트를 빌드합니다.

cd /root/.openclaw/workspace/docusaurus-team-library
npm run build

빌드가 성공하면 build/ 폴더가 생성됩니다.

2. 서비스 경로에 배포​

빌드 결과물을 nginx가 읽는 경로로 동기화합니다.

sudo mkdir -p /var/www/team-library
sudo rsync -av --delete /root/.openclaw/workspace/docusaurus-team-library/build/ /var/www/team-library/

3. nginx 설정 적용​

프로젝트 안의 nginx 템플릿을 실제 서버 설정으로 복사합니다.

sudo cp /root/.openclaw/workspace/docusaurus-team-library/deploy/nginx/team-library.biny.cloud.conf /etc/nginx/sites-available/team-library
sudo ln -s /etc/nginx/sites-available/team-library /etc/nginx/sites-enabled/team-library

이미 심볼릭 링크가 있으면 ln -s 단계는 생략해도 됩니다.

4. nginx 설정 검사 및 반영​

sudo nginx -t
sudo systemctl reload nginx

이 단계가 끝나면 HTTP 기준으로 사이트가 열려야 합니다.

5. HTTPS 인증서 적용​

HTTP 연결이 정상인 상태에서 certbot으로 인증서를 발급합니다.

sudo certbot --nginx -d team-library.biny.cloud

적용이 끝나면 보통 다음 상태가 됩니다.

  • HTTP → HTTPS 리다이렉트
  • HTTPS 443 응답 활성화
  • 인증서 자동 갱신 대상 등록

확인 방법​

curl -I http://team-library.biny.cloud
curl -I https://team-library.biny.cloud

정상 예시:

  • HTTP: 301 Moved Permanently
  • HTTPS: 200 OK

운영 중 재배포 명령​

문서나 화면을 수정한 뒤에는 보통 아래 명령이면 충분합니다.

cd /root/.openclaw/workspace/docusaurus-team-library
npm run build && sudo rsync -av --delete build/ /var/www/team-library/

정적 파일만 바뀌는 경우에는 nginx reload가 필수는 아닙니다.

자주 발생하는 오류​

1) cp: missing destination file operand​

원인:

  • cp 명령에서 원본과 대상 경로 사이 공백이 빠진 경우
  • 명령이 줄바꿈으로 잘린 경우

정상 형식:

sudo cp /root/.openclaw/workspace/docusaurus-team-library/deploy/nginx/team-library.biny.cloud.conf /etc/nginx/sites-available/team-library

2) HTTP는 열리는데 HTTPS가 다른 서비스로 연결됨​

원인:

  • team-library.biny.cloud용 443 SSL 설정이 없어서 기본 SSL 사이트가 응답하는 경우

해결:

sudo certbot --nginx -d team-library.biny.cloud

3) 배포 후에도 예전 화면이 보임​

점검 항목:

  • npm run build를 실제로 했는지
  • rsync --delete로 반영했는지
  • 브라우저 캐시 영향은 없는지
  • 다른 nginx server block과 충돌하지 않는지

운영 팁​

  • nginx 템플릿 원본은 프로젝트 안 deploy/nginx/ 경로를 기준으로 관리합니다.
  • 서버에서 직접 설정을 수정했다면 프로젝트 쪽 템플릿에도 반영해 두는 것이 좋습니다.
  • 장애 대응 시에는 먼저 curl -I로 HTTP/HTTPS 상태를 구분해서 확인합니다.

관련 경로​

  • 프로젝트: /root/.openclaw/workspace/docusaurus-team-library
  • nginx 템플릿: /root/.openclaw/workspace/docusaurus-team-library/deploy/nginx/team-library.biny.cloud.conf
  • 배포 스크립트: /root/.openclaw/workspace/docusaurus-team-library/deploy/deploy-team-library.sh