Hyperbook 웹서비스의 Git 소스 저장소 운영 원칙

제안

/home/ec2-user/copilot/hyperbook을 Hyperbook의 정식 소스 저장소로 사용한다. 현재 이 디렉터리는 Git 저장소이며 main 브랜치가 원격 origin/main과 동기화되어 있고 작업 트리도 깨끗하다.

배경

현재 8765 포트 웹서비스는 Copilot 세션 상태 디렉터리 아래의 hyperbook-site에서 실행되고 있다. 이 방식은 당장 동작하지만 세션 상태 디렉터리의 수명과 서비스의 수명이 결합될 수 있다. 세션 정리나 경로 변경이 발생하면 실행 파일과 정적 자산을 잃을 위험이 있다.

권장 구조

Git 저장소는 변경 이력과 협업을 위한 정식 소스(source of truth)로 두고, 서비스 실행은 안정적인 배포 디렉터리 또는 저장소 경로를 사용한다. 저장소에는 index.html, styles.css, script.js, stackbit.config.ts뿐 아니라 실제 실행에 필요한 server.py와 hyperbook_logo.jpg도 포함해야 한다.

운영 흐름은 다음과 같다.

소스 수정 → Git commit → 원격 push → 배포 경로 갱신 → systemd 서비스 재시작

간단한 단일 서버라면 systemd가 저장소 디렉터리의 server.py를 직접 실행할 수 있다. 배포 안정성이 더 중요하면 Git 저장소를 작업 공간으로 유지하고, 검증된 커밋을 별도의 영구 배포 디렉터리에 복사한 뒤 systemd가 배포 디렉터리를 실행하도록 한다.

기대 효과

1. 모든 웹 콘텐츠와 실행 코드의 변경 이력을 추적할 수 있다.
2. 세션 상태 디렉터리에 대한 의존성이 제거된다.
3. 이전 커밋으로 되돌리거나 특정 버전을 재현하기 쉽다.
4. 원격 저장소를 통해 백업과 협업이 가능하다.
5. systemd의 자동 시작·재시작 정책과 Git 기반 배포를 독립적으로 관리할 수 있다.

주의점

Git 저장소를 사용하더라도 토큰, 비밀번호, .env 같은 비밀정보는 커밋하지 않아야 한다. .gitignore를 추가해 비밀정보와 생성 파일을 제외하고, 서비스가 참조하는 경로가 세션 디렉터리가 아닌지 확인해야 한다. 배포 후에는 systemctl --user status hyperbook-site.service와 curl http://127.0.0.1:8765/로 서비스 상태와 HTTP 응답을 확인한다.

결론

Hyperbook 폴더를 Git commit 용도로 사용하는 것은 적절하다. 핵심은 Git 저장소를 정식 소스 기준으로 삼되, 실행 서비스의 수명과 Copilot 세션의 수명을 분리하는 것이다. 이 구조가 현재의 단순한 정적 사이트에도 가장 낮은 복잡도로 재현성·안정성·감사 가능성을 제공한다.