Runbook 패키징과 팀 공유 완벽 가이드

운영 환경을 문서화하고 팀과 공유하는 방법을 배웁니다. MkDocs를 활용한 Runbook 구축부터 배포까지, 실무에서 바로 쓸 수 있는 노하우를 담았습니다.

---

목차

1. docs_폴더_구조_설계
2. 설치_가이드_문서_작성
3. 네트워크_보안_정책_문서화
4. 백업_복구_절차_정리
5. 모니터링_알림_대응_가이드
6. MkDocs_빌드_및_배포
7. 팀_공유_및_유지보수_계획

---

1. docs 폴더 구조 설계

입사 6개월 차 김운영 씨는 최근 새로운 고민이 생겼습니다. 서버가 늘어나고 서비스가 확장되면서 운영 문서가 여기저기 흩어져 있었습니다.

누군가 야간 장애 전화를 받으면 슬랙 메시지를 뒤지고, 구글 드라이브를 뒤져야 했습니다.

docs 폴더 구조 설계는 운영 문서를 체계적으로 정리하는 첫걸음입니다. 마치 도서관의 분류 체계처럼 문서를 목적별로 나누어 관리합니다.

좋은 폴더 구조는 필요한 문서를 5초 안에 찾을 수 있게 해줍니다.

다음 코드를 살펴봅시다.

# docs 폴더 구조 생성 스크립트
mkdir -p docs/{installation,network,backup,monitoring,troubleshooting}
mkdir -p docs/assets/{images,diagrams}

# 각 섹션별 인덱스 파일 생성
cat > docs/index.md << 'EOF'
# 운영 Runbook

## 주요 섹션
- [설치 가이드](installation/index.md)
- [네트워크 정책](network/index.md)
- [백업/복구](backup/index.md)
- [모니터링](monitoring/index.md)
EOF

김운영 씨는 어느 날 밤 장애 전화를 받았습니다. "데이터베이스 백업을 어떻게 복구하죠?" 당황한 김운영 씨는 슬랙 검색창에 "백업"이라고 쳤습니다.

관련 메시지가 200개나 나왔습니다. 다음 날 출근해서 선배 박데브옵스 씨에게 하소연했습니다.

"이런 정보들을 한곳에 모을 방법이 없을까요?" 박데브옵스 씨가 웃으며 답했습니다. "바로 그래서 Runbook을 만드는 거죠." Runbook이란 무엇일까요?

쉽게 말해 운영 업무의 백과사전입니다. 서버 설치 방법부터 장애 대응까지, 실무에 필요한 모든 절차를 담은 문서입니다.

마치 요리책처럼 단계별로 따라 할 수 있게 작성합니다. 하지만 무작정 문서를 만들면 금방 엉망이 됩니다.

첫 번째 문서는 server_setup.md, 두 번째는 백업방법_최종_진짜최종.md 이런 식으로 이름이 붙습니다. 나중에는 어떤 문서가 최신인지조차 알 수 없게 됩니다.

여기서 폴더 구조가 중요해집니다. 좋은 구조는 도서관의 분류 체계와 같습니다.

소설은 소설 코너에, 요리책은 요리 코너에 있듯이 문서도 용도에 따라 분류해야 합니다. 가장 기본적인 구조는 다섯 가지 카테고리로 나눕니다.

installation 폴더에는 설치 관련 문서를, network 폴더에는 방화벽과 보안 정책을 넣습니다. backup 폴더에는 백업과 복구 절차를, monitoring 폴더에는 모니터링 설정과 알림 대응을 정리합니다.

여기서 한 가지 더 추가합니다. troubleshooting 폴더입니다.

실제 장애 사례와 해결 방법을 모아둡니다. 새벽 3시에 장애가 터졌을 때 가장 먼저 찾게 되는 폴더입니다.

각 폴더마다 index.md 파일을 만듭니다. 이 파일은 해당 카테고리의 목차 역할을 합니다.

예를 들어 installation/index.md에는 설치 관련 문서들의 링크가 들어갑니다. 그림이나 다이어그램은 어떻게 할까요?

assets 폴더를 별도로 만들어 관리합니다. 이미지는 assets/images에, 네트워크 다이어그램은 assets/diagrams에 넣습니다.

문서와 이미지를 분리하면 관리가 훨씬 쉬워집니다. 박데브옵스 씨가 하나 더 조언했습니다.

"각 문서 이름은 목적이 명확하게 드러나야 해요. setup.md보다는 ubuntu-server-initial-setup.md처럼 구체적으로 짓는 게 좋습니다." 김운영 씨는 이 구조를 팀에 공유했습니다.

이제 누가 물어봐도 "docs 폴더의 backup 섹션을 보세요"라고 답할 수 있게 되었습니다. 좋은 폴더 구조는 시간이 지나도 무너지지 않습니다.

새로운 문서를 추가할 때도 어디에 넣어야 할지 고민할 필요가 없습니다. 마치 잘 정돈된 서랍처럼 자연스럽게 제자리를 찾아갑니다.

실전 팁

💡 - 폴더 깊이는 3단계를 넘지 않도록 유지합니다

• 각 폴더의 index.md에 간단한 설명과 링크를 넣어 네비게이션을 돕습니다
• 자주 찾는 문서는 루트의 index.md에서 바로 링크합니다

---

2. 설치 가이드 문서 작성

신입 이개발 씨가 개발 서버를 새로 셋업하게 되었습니다. 선배에게 물어보니 "지난번에 내가 설치한 거 참고해"라는 답만 돌아왔습니다.

하지만 어떤 명령어를 실행했는지, 어떤 설정을 바꿨는지 기록이 없었습니다.

설치 가이드 문서는 서버나 애플리케이션을 처음부터 설치하는 모든 단계를 기록합니다. 복사 붙여넣기만으로 설치가 완료되도록 작성합니다.

이를 통해 누구나 동일한 환경을 만들 수 있습니다.

다음 코드를 살펴봅시다.

# docs/installation/ubuntu-initial-setup.md
## Ubuntu 22.04 초기 설정

### 1. 시스템 업데이트
apt update && apt upgrade -y

### 2. 필수 패키지 설치
apt install -y curl wget git vim htop net-tools

### 3. 타임존 설정
timedatectl set-timezone Asia/Seoul

### 4. 방화벽 설정
ufw allow 22/tcp
ufw allow 80/tcp
ufw allow 443/tcp
ufw --force enable

### 5. 확인
echo "설치 완료: $(date)"

이개발 씨는 막막했습니다. 선배가 예전에 설치한 서버는 잘 돌아가는데, 자신이 새로 만든 서버는 왜인지 에러가 났습니다.

어떤 단계를 빠뜨렸을까요? 이런 상황을 방지하기 위해 설치 가이드 문서가 필요합니다.

요리 레시피처럼 모든 단계를 빠짐없이 기록합니다. 좋은 설치 가이드는 세 가지 원칙을 따릅니다.

첫째, 재현 가능해야 합니다. 같은 문서를 보고 10명이 설치하면 10개의 동일한 서버가 나와야 합니다.

둘째, 복사 붙여넣기 가능해야 합니다. 명령어를 일일이 타이핑하다가 오타가 나면 안 됩니다.

셋째, 검증 단계가 포함되어야 합니다. 문서 구조는 간단합니다.

제목에 운영체제와 버전을 명시합니다. Ubuntu 22.04 초기 설정처럼 구체적으로 씁니다.

나중에 Ubuntu 24.04용 문서를 따로 만들 수 있습니다. 각 단계는 번호를 붙입니다.

"1. 시스템 업데이트", "2.

필수 패키지 설치" 이런 식입니다. 순서가 중요한 작업이라면 반드시 번호를 붙여야 합니다.

명령어는 코드 블록으로 작성합니다. 마크다운의 백틱 세 개로 감싸면 됩니다.

이렇게 하면 복사하기 버튼이 자동으로 생깁니다. 각 명령어 앞에 간단한 설명을 붙입니다.

"타임존 설정"이라고 쓰고 timedatectl set-timezone Asia/Seoul 명령어를 넣습니다. 왜 이 작업이 필요한지 한 줄로 설명하면 더 좋습니다.

설치가 끝나면 확인 단계를 넣습니다. 예를 들어 방화벽을 설정했다면 ufw status로 제대로 적용되었는지 체크합니다.

이 단계를 빼먹으면 나중에 문제가 생겼을 때 어느 단계에서 잘못됐는지 찾기 어렵습니다. 환경변수나 설정 파일을 수정해야 한다면 변경 전후를 모두 기록합니다.

"이 줄을 찾아서 이렇게 바꾸세요"라고 명확히 적습니다. 박데브옵스 씨는 한 가지 팁을 더 알려줬습니다.

"문서 맨 위에 예상 소요 시간을 적어두세요. '이 작업은 약 20분 소요됩니다'라고 쓰면 작업자가 시간을 계획할 수 있습니다." 또 하나 중요한 것은 버전 정보입니다.

패키지 설치 시 특정 버전이 필요하다면 반드시 명시합니다. apt install nginx=1.18.0-0ubuntu1처럼 버전까지 고정하면 더 안전합니다.

이개발 씨는 이번 경험을 바탕으로 자신이 설치한 과정을 문서로 남겼습니다. 다음에 누가 서버를 셋업하든 똑같은 환경을 만들 수 있게 되었습니다.

문서는 한 번 쓰고 끝이 아닙니다. 시간이 지나면 운영체제나 패키지 버전이 바뀝니다.

6개월마다 한 번씩 실제로 따라 해보고 업데이트해야 합니다.

실전 팁

💡 - 명령어는 sudo 포함 여부를 명확히 합니다

• 실패 가능한 단계는 해결 방법을 미리 적어둡니다
• 설치 후 재부팅이 필요한지 명시합니다

---

3. 네트워크 보안 정책 문서화

김보안 씨는 신규 서비스 오픈을 앞두고 있었습니다. 보안팀에서 "방화벽 정책 문서를 보내주세요"라는 요청이 왔습니다.

하지만 정작 어떤 포트가 열려 있는지, 왜 열었는지 기록이 없었습니다. 급하게 서버에 접속해서 iptables를 확인하며 땀을 흘렸습니다.

네트워크 보안 정책 문서는 방화벽 규칙, 접근 제어, 포트 설정을 정리한 문서입니다. 어떤 포트가 왜 열려 있는지, 누가 접근할 수 있는지 명확히 기록합니다.

보안 감사나 장애 대응 시 필수입니다.

다음 코드를 살펴봅시다.

# docs/network/firewall-policy.md
## 방화벽 정책

### 웹 서버 (10.0.1.10)
| 포트 | 프로토콜 | 소스 | 용도 | 담당자 |
|------|----------|------|------|--------|
| 22 | TCP | 관리망 | SSH | 운영팀 |
| 80 | TCP | 0.0.0.0/0 | HTTP | 개발팀 |
| 443 | TCP | 0.0.0.0/0 | HTTPS | 개발팀 |

### 적용 명령어
ufw allow from 10.0.0.0/24 to any port 22
ufw allow 80/tcp
ufw allow 443/tcp

### 변경 이력
- 2024-03-15: 초기 정책 수립 (김보안)

김보안 씨가 서버를 점검하다가 이상한 포트가 열려 있는 것을 발견했습니다. 8888번 포트였습니다.

"이거 누가 열었지?" 슬랙에 물어봤지만 아무도 기억하지 못했습니다. 결국 프로세스를 추적해보니 6개월 전 테스트용으로 열어둔 포트였습니다.

테스트가 끝났는데 닫는 것을 잊어버렸던 겁니다. 만약 이 포트로 공격을 받았다면 큰일 날 뻔했습니다.

이런 일을 방지하려면 네트워크 정책 문서가 필요합니다. 마치 건물의 출입 명부처럼 누가 언제 어떤 출입구를 만들었는지 기록합니다.

문서는 표 형식이 가장 보기 좋습니다. 마크다운 테이블로 만들면 한눈에 들어옵니다.

포트 번호, 프로토콜, 접근 가능한 소스, 용도, 담당자를 컬럼으로 넣습니다. 소스 항목이 특히 중요합니다.

0.0.0.0/0은 모든 곳에서 접근 가능하다는 뜻입니다. 80번, 443번 포트처럼 공개 서비스에만 사용해야 합니다.

SSH 같은 관리 포트는 반드시 특정 IP 대역으로 제한합니다. 용도 컬럼에는 왜 이 포트가 필요한지 적습니다.

"HTTP"보다는 "웹 서비스 사용자 접속용"이라고 구체적으로 쓰는 게 좋습니다. 나중에 "이 포트 닫아도 되나요?"라고 물어볼 때 판단 근거가 됩니다.

담당자도 반드시 적습니다. 포트를 요청한 팀이나 담당자를 기록해둡니다.

문제가 생겼을 때 누구한테 물어볼지 알 수 있습니다. 표 아래에는 실제 적용 명령어를 적습니다.

문서를 보고 바로 방화벽을 설정할 수 있어야 합니다. UFW를 쓴다면 ufw 명령어를, iptables를 쓴다면 그에 맞는 명령어를 넣습니다.

변경 이력 섹션도 중요합니다. 언제 누가 어떤 정책을 추가했는지 기록합니다.

Git 커밋처럼 날짜와 담당자를 적습니다. 나중에 "왜 이 포트가 열렸지?"라고 의문이 들 때 이력을 보면 알 수 있습니다.

보안 정책은 한 번 만들고 끝이 아닙니다. 3개월마다 정책 리뷰를 해야 합니다.

더 이상 사용하지 않는 포트가 있는지, 불필요하게 넓게 열린 규칙이 있는지 점검합니다. 박데브옵스 씨가 추천한 방법은 실제 트래픽과 비교하는 것입니다.

방화벽 로그를 보고 실제로 사용되는 포트만 남깁니다. 문서에는 있지만 트래픽이 없는 포트는 삭제 후보입니다.

김보안 씨는 이제 보안팀 감사가 와도 당황하지 않습니다. "여기 문서 보세요"라고 자신 있게 말할 수 있습니다.

네트워크 정책 문서는 단순히 규정 때문에 만드는 게 아닙니다. 실제로 장애가 났을 때 "혹시 방화벽 문제인가?"라고 의심될 때 가장 먼저 보는 문서입니다.

실전 팁

💡 - 클라우드 환경이라면 보안 그룹 ID도 함께 기록합니다

• 임시로 여는 포트는 만료일을 표에 추가합니다
• VPN이나 Bastion 서버 접속 정보도 함께 문서화합니다

---

4. 백업 복구 절차 정리

새벽 2시, 최운영 씨의 전화가 울렸습니다. "데이터베이스가 날아갔어요!" 식은땀을 흘리며 서버에 접속했습니다.

백업은 매일 하고 있었지만, 정작 복구하는 방법을 문서로 만들어둔 적이 없었습니다. 구글을 뒤지며 복구 명령어를 찾기 시작했습니다.

백업 복구 절차 문서는 평소에 어떻게 백업하고, 장애 시 어떻게 복구하는지 기록합니다. 백업 주기, 보관 위치, 복구 테스트 방법까지 포함합니다.

데이터를 지키는 마지막 안전장치입니다.

다음 코드를 살펴봅시다.

# docs/backup/postgresql-backup.md
## PostgreSQL 백업 및 복구

### 백업 실행
# 전체 백업 (매일 새벽 2시 cron)
pg_dump -h localhost -U postgres -d myapp \
  | gzip > /backup/myapp_$(date +%Y%m%d).sql.gz

### 백업 확인
ls -lh /backup/myapp_*.sql.gz
# 최근 7일치 백업 파일이 있는지 확인

### 복구 실행
# 1. 백업 파일 압축 해제
gunzip -c /backup/myapp_20241210.sql.gz > restore.sql

# 2. 데이터베이스 복구
psql -h localhost -U postgres -d myapp < restore.sql

최운영 씨는 그날 밤 3시간 동안 고생했습니다. 백업 파일은 있었지만 어떤 명령어로 복구하는지 헷갈렸습니다.

옵션 하나를 잘못 줘서 데이터가 꼬이기도 했습니다. 결국 해결했지만 진땀을 뺐습니다.

다음 날 팀 회의에서 결심했습니다. "백업 문서를 제대로 만들자." 선배 박데브옵스 씨도 동의했습니다.

"백업은 복구할 수 있을 때만 의미가 있어요." 백업 문서는 세 부분으로 구성됩니다. 백업 실행 방법, 백업 검증 방법, 복구 절차입니다.

이 세 가지가 모두 있어야 완전한 문서입니다. 첫 번째는 백업 실행 방법입니다.

어떤 명령어를 언제 실행하는지 적습니다. pg_dump처럼 데이터베이스 덤프 명령어를 기록하고, 파일명에 날짜를 넣는 방법도 보여줍니다.

cron 스케줄도 함께 적습니다. "매일 새벽 2시"라고만 쓰지 말고 실제 cron 표현식 0 2 * * *도 넣습니다.

나중에 다른 서버에 똑같이 설정할 때 복사해서 쓸 수 있습니다. 백업 파일 보관 위치도 명시합니다.

로컬 디스크 경로뿐만 아니라 S3 같은 외부 스토리지도 함께 기록합니다. 서버가 통째로 날아가도 복구할 수 있어야 합니다.

두 번째는 백업 검증입니다. 백업이 잘 되고 있는지 확인하는 방법을 적습니다.

ls -lh 명령어로 파일 크기를 보거나, 최근 7일치 백업이 있는지 체크합니다. 더 확실한 방법은 복구 테스트입니다.

한 달에 한 번씩 실제로 백업 파일로 복구해봅니다. 테스트 서버에서 진행하고 결과를 문서에 기록합니다.

"2024-12-10: 백업 파일로 복구 성공 확인"처럼 적습니다. 세 번째는 복구 절차입니다.

이 부분이 가장 중요합니다. 장애가 났을 때 당황하지 않고 따라 할 수 있도록 단계별로 적습니다.

복구는 보통 두 단계입니다. 먼저 백업 파일 압축을 풀고, 그다음 데이터베이스에 임포트합니다.

각 단계마다 예상 소요 시간도 적어둡니다. "압축 해제 약 5분, 복구 약 30분" 이런 식입니다.

복구 중 주의사항도 빠뜨리지 않습니다. "복구 전에 반드시 현재 데이터를 백업하세요"처럼 중요한 경고를 상단에 큰 글씨로 적습니다.

다양한 시나리오를 준비합니다. 전체 복구, 특정 테이블만 복구, 특정 시점으로 복구 등 상황별 방법을 나눠서 적습니다.

박데브옵스 씨는 한 가지 팁을 더 줬습니다. "복구 명령어 옆에 '위험도'를 표시하세요.

DROP DATABASE 같은 위험한 명령어는 빨간색으로 강조합니다." 최운영 씨는 문서를 완성한 후 팀원들과 복구 훈련을 했습니다. 각자 문서만 보고 테스트 서버에 복구해보는 연습입니다.

실제 장애가 나기 전에 미리 익숙해지는 겁니다. 이제 최운영 씨는 새벽 전화가 와도 당황하지 않습니다.

문서를 보고 차근차근 따라 하면 됩니다.

실전 팁

💡 - 백업 파일 보관 기간을 명시합니다 (예: 7일치 로컬, 30일치 S3)

• 복구 시 접속을 차단해야 하는지 여부를 적습니다
• 복구 후 검증 쿼리를 함께 제공합니다 (예: SELECT COUNT(*) 비교)

---

5. 모니터링 알림 대응 가이드

정개발 씨는 슬랙 알림을 받았습니다. "CPU 사용률 90% 초과!" 당황한 정개발 씨는 서버에 접속했지만 뭘 해야 할지 몰랐습니다.

CPU가 왜 높아졌는지, 어떻게 조치해야 하는지 기준이 없었습니다. 결국 선배에게 전화해서 도움을 받았습니다.

모니터링 알림 대응 가이드는 알림이 왔을 때 어떻게 대응해야 하는지 정리한 문서입니다. 알림 종류별로 확인 사항, 대응 방법, 에스컬레이션 기준을 담습니다.

야간 당직자의 필수 매뉴얼입니다.

다음 코드를 살펴봅시다.

# docs/monitoring/alert-response.md
## CPU 사용률 알림 대응

### 알림 조건
- Critical: CPU 90% 이상 5분 지속
- Warning: CPU 80% 이상 10분 지속

### 1차 확인 사항
# 현재 CPU 사용률 확인
top -bn1 | head -20

# 상위 프로세스 확인
ps aux --sort=-%cpu | head -10

### 대응 절차
# 1. 로그 확인
tail -f /var/log/application.log

# 2. 비정상 프로세스 종료 (필요 시)
kill -15 <PID>

### 에스컬레이션
- 10분 내 해결 안 되면 팀장에게 연락
- 연락처: 010-XXXX-XXXX

정개발 씨는 그날 이후 생각했습니다. "알림은 받는데 뭘 해야 할지 모르면 무슨 소용이지?" 모니터링 시스템은 잘 구축되어 있었지만, 알림에 대응하는 매뉴얼이 없었습니다.

선배 박데브옵스 씨도 공감했습니다. "예전에는 알림이 오면 무조건 나한테 전화했어요.

이제는 신입도 1차 대응할 수 있게 문서를 만들어야죠." 알림 대응 가이드는 각 알림마다 별도 섹션으로 만듭니다. CPU 사용률, 메모리 부족, 디스크 용량, 응답 지연 등 알림 유형별로 나눕니다.

각 섹션은 네 부분으로 구성됩니다. 알림 조건, 1차 확인 사항, 대응 절차, 에스컬레이션 기준입니다.

알림 조건부터 명확히 합니다. "CPU 90% 이상 5분 지속 시 Critical 알림"처럼 구체적으로 적습니다.

알림을 받은 사람이 얼마나 급한 상황인지 판단할 수 있어야 합니다. Warning과 Critical을 구분합니다.

Warning은 "주의 깊게 지켜보세요"라는 신호이고, Critical은 "지금 당장 조치하세요"라는 의미입니다. 1차 확인 사항은 문제의 원인을 파악하는 단계입니다.

CPU 알림이라면 top 명령어로 어떤 프로세스가 CPU를 많이 쓰는지 확인합니다. 명령어를 그대로 적어서 복사 붙여넣기하면 되게 만듭니다.

확인 결과를 판단하는 기준도 제공합니다. "java 프로세스가 CPU 80% 이상이면 애플리케이션 문제", "시스템 프로세스가 높으면 인프라 문제" 이런 식으로 가이드합니다.

대응 절차는 단계별로 번호를 붙입니다. 먼저 로그를 확인하고, 필요하면 프로세스를 재시작하고, 그래도 안 되면 서버를 재부팅합니다.

각 단계의 위험도도 표시합니다. 자주 발생하는 케이스는 예시를 넣습니다.

"배치 작업이 동시에 실행되어 CPU가 높아진 경우" 같은 실제 사례와 해결 방법을 적습니다. 에스컬레이션 기준이 가장 중요합니다.

혼자 해결할 수 없을 때 언제 누구에게 연락해야 하는지 명확히 합니다. "10분 내 해결 안 되면 팀장에게 연락"처럼 시간 기준을 줍니다.

연락처도 함께 적습니다. 전화번호뿐만 아니라 슬랙 채널, 이메일도 모두 기록합니다.

야간이나 주말에는 누구에게 연락해야 하는지도 명시합니다. 박데브옵스 씨가 강조한 것은 안전 장치입니다.

"절대 하지 말아야 할 것"을 상단에 큰 글씨로 적습니다. "운영 데이터베이스에서 DELETE 실행 금지"처럼 치명적인 실수를 방지합니다.

정개발 씨는 이 문서를 만든 후 팀원들과 시뮬레이션을 했습니다. 일부러 CPU를 높이고 알림을 발생시켜 문서대로 대응해보는 연습입니다.

연습 중에 문서에서 부족한 부분을 발견했습니다. 특정 명령어가 안 되는 권한 문제, 로그 파일 경로 오류 등입니다.

이런 것들을 수정해서 문서를 개선했습니다. 이제 정개발 씨는 알림이 와도 당황하지 않습니다.

문서를 보며 차근차근 확인하고 대응합니다. 해결되면 슬랙에 간단히 보고합니다.

알림 대응 가이드는 살아있는 문서여야 합니다. 새로운 유형의 장애가 발생하면 즉시 추가합니다.

6개월 지난 내용은 실제와 맞는지 확인하고 업데이트합니다.

실전 팁

💡 - 자주 발생하는 알림은 자동 복구 스크립트도 함께 제공합니다

• 대응 시간을 기록해서 평균 해결 시간을 문서에 적습니다
• 거짓 알림(false positive)이 자주 발생하면 알림 조건을 조정합니다

---

6. MkDocs 빌드 및 배포

문서를 모두 작성한 최문서 씨는 고민에 빠졌습니다. 마크다운 파일은 완성했지만 팀원들이 보기에는 불편했습니다.

파일을 일일이 열어봐야 했고, 검색도 어려웠습니다. "웹사이트처럼 만들 수는 없을까?"

MkDocs는 마크다운 파일을 깔끔한 웹사이트로 만들어주는 도구입니다. 검색 기능, 네비게이션, 반응형 디자인을 자동으로 제공합니다.

문서를 더욱 접근하기 쉽게 만듭니다.

다음 코드를 살펴봅시다.

# 1. MkDocs 설치
pip install mkdocs mkdocs-material

# 2. 설정 파일 생성 (mkdocs.yml)
cat > mkdocs.yml << 'EOF'
site_name: 운영 Runbook
theme:
  name: material
  palette:
    primary: indigo
  features:
    - navigation.tabs
    - search.suggest

nav:
  - 홈: index.md
  - 설치 가이드: installation/ubuntu-initial-setup.md
  - 네트워크 정책: network/firewall-policy.md
  - 백업/복구: backup/postgresql-backup.md
  - 모니터링: monitoring/alert-response.md
EOF

# 3. 로컬에서 미리보기
mkdocs serve

# 4. 정적 사이트 빌드
mkdocs build

최문서 씨가 팀원들에게 문서를 공유했습니다. "docs 폴더에 있어요.

마크다운 에디터로 보시면 됩니다." 하지만 반응이 시큰둥했습니다. 마크다운에 익숙하지 않은 팀원들은 불편해했습니다.

선배 박데브옵스 씨가 제안했습니다. "MkDocs로 웹사이트를 만들어봐요.

클릭만으로 보기 쉬워집니다." MkDocs는 정적 사이트 생성기입니다. 마크다운 파일을 입력하면 HTML 웹사이트가 출력됩니다.

마치 요리 재료를 넣으면 완성된 요리가 나오는 것과 같습니다. 설치는 간단합니다.

Python이 설치되어 있다면 pip install 한 줄이면 됩니다. mkdocs-material 테마도 함께 설치합니다.

이 테마는 구글의 Material Design을 따라서 깔끔하고 현대적입니다. 핵심은 mkdocs.yml 설정 파일입니다.

이 파일이 웹사이트의 구조를 결정합니다. 프로젝트 루트에 만듭니다.

설정 파일의 site_name은 웹사이트 제목입니다. 브라우저 탭에 표시되는 이름입니다.

"운영 Runbook"처럼 명확한 이름을 짓습니다. theme 섹션에서 테마를 선택합니다.

material 테마를 쓰면 반응형 디자인이 자동으로 적용됩니다. 모바일에서도 보기 좋습니다.

palette로 색상을 정합니다. primary를 indigo로 하면 남색 계열의 깔끔한 느낌이 납니다.

회사 CI 색상에 맞춰도 좋습니다. features에는 편의 기능을 추가합니다.

navigation.tabs는 상단에 탭 메뉴를 만들고, search.suggest는 검색 시 자동완성을 제공합니다. 가장 중요한 부분은 nav 섹션입니다.

웹사이트의 메뉴 구조를 정의합니다. 들여쓰기로 계층 구조를 표현합니다.

각 항목은 "메뉴명: 파일경로" 형식입니다. 홈: index.md라고 쓰면 홈 메뉴가 index.md를 가리킵니다.

파일 경로는 docs 폴더를 기준으로 합니다. 설정 파일을 만들었으면 로컬 미리보기를 합니다.

mkdocs serve 명령어를 실행하면 http://127.0.0.1:8000에서 사이트를 볼 수 있습니다. 파일을 수정하면 자동으로 새로고침됩니다.

미리보기에서 만족스러우면 빌드합니다. mkdocs build 명령어를 실행하면 site 폴더에 HTML 파일들이 생성됩니다.

이 폴더를 웹 서버에 올리면 끝입니다. 박데브옵스 씨가 팁을 줬습니다.

"검색 기능이 정말 유용해요. 팀원들이 특정 키워드로 문서를 찾을 수 있습니다." MkDocs는 자동으로 전체 문서를 인덱싱해서 검색 기능을 제공합니다.

또 하나 유용한 기능은 이전/다음 버튼입니다. 문서 하단에 자동으로 생깁니다.

nav에 정의한 순서대로 이동할 수 있습니다. 최문서 씨는 몇 가지 커스터마이징을 추가했습니다.

회사 로고를 넣고, 푸터에 담당팀 정보를 추가했습니다. mkdocs.yml에 logo와 copyright 항목을 설정하면 됩니다.

빌드된 사이트는 매우 가볍습니다. JavaScript 프레임워크 없이 순수 HTML과 CSS만 사용합니다.

로딩이 빠르고 서버 부담도 적습니다. 최문서 씨는 완성된 사이트를 팀원들에게 보여줬습니다.

"와, 전문적이네요!" 이제 누구나 브라우저만 열면 문서를 볼 수 있습니다.

실전 팁

💡 - 다크 모드를 추가하려면 palette 설정에 scheme: slate를 넣습니다

• 플러그인으로 PDF 내보내기, 다이어그램 지원 등을 추가할 수 있습니다
• GitHub Pages로 무료 호스팅이 가능합니다

---

7. 팀 공유 및 유지보수 계획

박팀장은 완성된 Runbook을 보고 만족했습니다. "이제 우리 팀만의 지식 베이스가 생겼네요." 하지만 한 가지 걱정이 있었습니다.

"시간이 지나면 이 문서들이 방치되지 않을까?" 문서는 만드는 것보다 유지하는 게 더 어렵습니다.

팀 공유 및 유지보수 계획은 문서를 살아있게 유지하는 방법입니다. 접근 권한 관리, 업데이트 주기, 담당자 지정, 리뷰 프로세스를 정합니다.

문서가 현실과 동떨어지지 않도록 만듭니다.

다음 코드를 살펴봅시다.

# 1. Git 저장소 초기화
git init
git add docs/ mkdocs.yml
git commit -m "Initial runbook setup"

# 2. GitHub에 푸시
git remote add origin https://github.com/company/runbook.git
git push -u origin main

# 3. GitHub Actions 배포 설정 (.github/workflows/deploy.yml)
name: Deploy MkDocs
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - run: pip install mkdocs-material
      - run: mkdocs gh-deploy --force

# 4. 문서 리뷰 요청
gh pr create --title "Update backup policy" \
  --body "백업 보관 기간 7일 → 14일로 변경"

박팀장의 걱정은 현실이 될 수 있습니다. 많은 팀에서 문서를 만들지만 6개월 후에는 아무도 보지 않습니다.

내용이 오래되어 신뢰할 수 없게 되기 때문입니다. 선배 박데브옵스 씨가 해결책을 알려줬습니다.

"문서도 코드처럼 관리해야 해요. Git으로 버전 관리하고, PR로 리뷰하고, 자동 배포를 설정하는 겁니다." 첫 번째 단계는 Git 저장소를 만드는 것입니다.

docs 폴더와 mkdocs.yml을 Git으로 관리합니다. 이제 누가 언제 무엇을 바꿨는지 이력이 남습니다.

GitHub나 GitLab에 저장소를 만들어 푸시합니다. 팀원들이 함께 작업할 수 있게 됩니다.

저장소는 private으로 만들어 내부 정보를 보호합니다. 브랜치 전략도 정합니다.

main 브랜치는 항상 배포 가능한 상태로 유지합니다. 수정할 때는 feature 브랜치를 만들어 작업하고 PR을 보냅니다.

PR은 리뷰 필수로 설정합니다. 혼자 판단하기 어려운 내용은 다른 팀원의 검토를 받습니다.

"이 절차가 맞나요?"라고 물어볼 수 있습니다. 자동 배포는 GitHub Actions로 설정합니다.

main 브랜치에 푸시되면 자동으로 MkDocs를 빌드하고 GitHub Pages에 배포합니다. 수동으로 배포할 필요가 없습니다.

배포 워크플로우는 간단합니다. checkout으로 코드를 가져오고, mkdocs-material을 설치하고, mkdocs gh-deploy로 배포합니다.

5분이면 문서 사이트가 업데이트됩니다. 접근 권한도 관리합니다.

모든 팀원은 읽기 권한을 갖고, 운영팀만 쓰기 권한을 갖습니다. 중요한 문서는 CODEOWNERS 파일로 특정 사람의 승인을 필수로 만듭니다.

문서 유지보수는 정기적으로 해야 합니다. 3개월마다 문서 리뷰 데이를 정합니다.

팀원들이 모여 각자 담당 문서를 점검합니다. 오래된 내용은 업데이트하고, 더 이상 필요 없는 문서는 삭제합니다.

각 문서 상단에 메타 정보를 추가합니다. 작성일, 최종 수정일, 담당자를 적습니다.

주석으로 넣거나 마크다운 표로 만듭니다. 이렇게 하면 문서가 얼마나 신선한지 한눈에 알 수 있습니다.

박데브옵스 씨가 강조한 것은 피드백 채널입니다. 문서를 보다가 잘못된 내용을 발견하면 바로 제보할 수 있어야 합니다.

각 페이지 하단에 "수정 제안" 링크를 넣어 GitHub 이슈로 연결합니다. 변경 로그도 유지합니다.

중요한 정책 변경은 CHANGELOG.md에 기록합니다. "2024-12-10: 백업 보관 기간 변경 (7일 → 14일)" 이런 식입니다.

팀원들이 무엇이 바뀌었는지 알 수 있습니다. 신규 입사자에게는 온보딩 가이드로 활용합니다.

첫날 Runbook 사이트 주소를 알려주고 주요 문서를 안내합니다. 한 달 후 피드백을 받아 문서를 개선합니다.

최문서 씨는 팀 슬랙 채널에 문서 봇을 추가했습니다. 특정 키워드를 치면 관련 문서 링크를 자동으로 알려줍니다.

"백업"이라고 치면 백업 문서 링크가 나옵니다. 문서 사이트 접속 통계도 모니터링합니다.

Google Analytics를 붙여 어떤 문서가 많이 조회되는지 확인합니다. 자주 찾는 문서는 더 자세히 만들고, 안 보는 문서는 정말 필요한지 재검토합니다.

박팀장은 분기마다 문서 기여도를 측정합니다. PR 횟수, 리뷰 참여도를 보고 인사 평가에 반영합니다.

문서 작성도 중요한 업무임을 인정받게 됩니다. 1년 후, 팀은 Runbook 덕분에 많은 것이 달라졌습니다.

신입이 와도 빠르게 적응하고, 야간 장애가 나도 혼자 해결할 수 있게 되었습니다. 무엇보다 지식이 특정 사람에게만 쌓이지 않고 팀 전체에 공유되었습니다.

박데브옵스 씨가 마지막으로 말했습니다. "좋은 문서는 팀의 자산입니다.

시간을 들여 만들고 유지할 가치가 있습니다."

실전 팁

💡 - 문서 템플릿을 만들어 일관된 형식을 유지합니다

• 중요한 절차는 스크린 레코딩을 추가해 영상 가이드로 보완합니다
• 분기마다 가장 많이 조회된 문서 Top 5를 슬랙에 공유해 관심을 유지합니다

---

이상으로 학습을 마칩니다. 위 내용을 직접 코드로 작성해보면서 익혀보세요!