콘텐츠로 이동

Docs Runbook

Rocky Linux Production 상세 문서를 빠르게 선택하고 작업 순서를 좁히기 위한 short runbook 모음.

로컬 실행

최초 클론 후 Python 패키지 설치와 shared assets 심링크 연결은 프로젝트 루트 README.md를 따른다.

mkdocs-runbook.yml은 docs-runbook 폴더를 기준으로 동작한다.

python -m mkdocs build --strict -f mkdocs-runbook.yml
python -m mkdocs serve -f mkdocs-runbook.yml -a 127.0.0.1:8000

두 문서 사이트 모두 위 예시는 127.0.0.1:8000을 사용하므로 동시에 실행하지 않는다. 동시에 확인해야 하면 한쪽 포트를 8001 등으로 변경한다.

브라우저에서 접속.

http://127.0.0.1:8000/

상세 절차는 MkDocs Material 개발 환경 Runbook과 프로젝트 루트 README.md를 참고.

1. 문서 사용 순서

서버 구축, 점검, 수정 작업을 요청받으면 아래 순서로 확인한다.

  1. Project Map
  2. 요청 영역의 short runbook
  3. short runbook에서 지정한 상세 문서
  4. 입력값 부족분과 중단 조건
  5. 검증 명령과 완료 기준

2. 핵심 Runbook

반복 작업이나 사고 가능성이 높은 작업은 short runbook을 먼저 기준으로 삼는다.

3. 문서 운영 원칙

이 폴더는 docs 상세 문서를 대체하지 않는 작업 인덱스다.

  • 상세 명령과 긴 설명은 docs를 source of truth로 둔다.
  • 이 폴더에는 입력값, 작업 순서, 중단 조건, 검증 기준, 상세 문서 링크만 둔다.
  • 실제 서버 값, credential, secret은 이 폴더에 저장하지 않는다.
  • MkDocs에 한 사이트로 같이 보이게 할 때는 mkdocs-runbook.yml을 기준으로 별도 서빙한다.

4. 요청 입력값

아래 항목은 매번 모두 적을 필요는 없다. 작업 시작 전에 부족한 값만 다시 확인한다.

항목 예시
목표 OS 설치 완료 서버를 운영 서버 기준으로 구성
서버 역할 GitLab, Node.js, Next.js, Laravel, MySQL, Redis, Nginx gateway
OS 상태 Rocky Linux 9 설치 완료, SELinux Enforcing 유지 예정
접속 방식 SSH 가능, 콘솔 가능 여부, 임시 계정 사용 여부
네트워크 내부망/VPN 전용, 외부 공개, 허용 CIDR
도메인 FQDN, DNS 준비 여부, SSL 처리 위치
스토리지 기본 디스크 사용, 별도 mount 사용, 데이터 경로
설치 범위 OS baseline만, 서비스 설치까지, CI/CD까지
실행 방식 Codex가 직접 명령 실행, 명령만 제시, 사용자가 결과 전달

5. Codex 작업 지시 방식

Codex에게 서버 구축, 점검, 수정 작업을 요청할 때는 먼저 docs-runbook을 기준으로 범위를 좁힌다.

이 프로젝트는 docs-runbook 기준으로 진행해.
전체 docs는 필요한 상세 문서만 선택해서 열어.
부족한 입력값과 중단 조건을 먼저 확인한 뒤 진행해.

더 짧게는 다음처럼 요청해도 된다.

docs-runbook 기준으로 GitLab 서버 구축 진행해줘.

docs-runbook 기준으로 Node.js 운영 서버 구축 진행해줘.

docs-runbook 기준으로 기존 서버 audit 결과 검토해줘.

요청 예시:

docs-runbook을 먼저 기준으로 봐줘.
전체 docs를 한 번에 읽지 말고, 필요한 상세 문서만 선택해서 열어.

목표:
Rocky Linux 9 설치 완료 서버를 GitLab 운영 서버로 구성

현재 상태:
- SSH 접속 가능
- SELinux Enforcing 유지 예정
- DNS는 gitlab.example.com으로 준비됨
- Reverse Proxy는 같은 서버에서 Nginx로 처리 예정

원하는 작업:
1. OS baseline 점검
2. GitLab 사전 준비
3. GitLab 설치와 gitlab.rb 설정
4. Nginx reverse proxy 기준 정리
5. 방화벽/SELinux 확인
6. 완료 검증 명령까지 정리

6. Credential 운영 기준

운영 credential을 전달할 때는 다음 원칙을 지킨다.

  • 가능하면 비밀번호 대신 임시 공개키 접속을 사용한다.
  • 임시 비밀번호를 사용한 경우 작업 후 rotation 또는 비활성화 여부를 확인한다.
  • private key, access key, token, .env 원문은 문서에 저장하지 않는다.
  • credential이 필요한 작업은 어디에 저장할지와 누가 읽을 수 있는지 먼저 정한다.

7. 기본 진행 순서

Codex는 아래 흐름으로 문서 범위와 작업 기준을 좁힌다.

  1. Project Map으로 요청 범위를 찾는다.
  2. 해당 영역의 short runbook을 먼저 읽는다.
  3. 입력값 부족분과 중단 조건을 확인한다.
  4. 필요한 상세 문서만 docs에서 추가로 읽는다.
  5. 적용 전 검증 명령을 먼저 제시하거나 실행한다.
  6. 변경 작업을 수행한다.
  7. 완료 기준에 맞는 검증 명령과 결과를 정리한다.

8. 영역별 Short Runbook