## 왜 복구 가이드가 필요한가?
서비스 장애는 예고 없이 찾아옵니다. 특히 레거시 시스템이나 운영 중인 서비스가 많을수록, 담당자가 바뀌거나 긴급 상황에서 빠르게 대응하기 어렵습니다. 이런 상황을 대비해 **복구 가이드 문서화**는 필수적입니다.
이번 글에서는 실제 Docker 기반 웹 서비스의 복구 가이드를 작성하면서 얻은 실무 노하우를 공유합니다.
---
## 복구 가이드에 포함되어야 할 핵심 요소
### 1. 서비스 아키텍처 개요
- **서버 구성**: Frontend/Backend 분리 여부, 포트 정보
- **데이터베이스**: 연결 정보, 스키마 구조
- **배포 상태**: 현재 운영 중인지, 중단 상태인지 명확히 기록
### 2. Docker 환경 특이사항
Docker를 사용하는 경우, 환경별로 주의할 점이 다릅니다.
```bash
# DNS 문제가 있는 서버 환경에서는 host 네트워크 사용
docker build --network=host -t service-name .
```
**주의사항**:
- `--network=host` 옵션은 Docker 컨테이너가 호스트의 네트워크를 직접 사용하게 합니다
- 방화벽이나 특정 네트워크 정책이 있는 환경에서 유용합니다
- 단, 포트 충돌 가능성을 반드시 확인해야 합니다
### 3. 빌드 시간 및 리소스 예측
특정 패키지 설치로 빌드 시간이 길어질 수 있습니다.
```dockerfile
# 문서 변환이나 한글 폰트가 필요한 경우
RUN apt-get update && apt-get install -y \
libreoffice \
fonts-nanum
```
**팁**: 빌드 시간이 10분 이상 소요되는 경우, 문서에 명시하여 담당자가 당황하지 않도록 합니다.
---
## 장애 진단을 위한 체크리스트
복구 가이드는 단순 재시작 방법만 담는 게 아닙니다. **진단 명령어**도 함께 기록해야 합니다.
### 기본 진단 명령어
```bash
# 컨테이너 상태 확인
docker ps -a | grep service-name
# 로그 확인
docker logs -f container-id
# DB 연결 테스트
psql -h db-server -p 5432 -U username -d database-name
# 네트워크 연결 확인
telnet db-server 5432
```
### 주요 장애 유형별 대응
1. **DB 연결 실패**: 방화벽, 인증 정보, 네트워크 확인
2. **컨테이너 시작 실패**: 로그에서 에러 메시지 확인, 의존성 체크
3. **빌드 실패**: Dockerfile 문법, 베이스 이미지 변경 여부 확인
---
## 문서화 실전 팁
### 1. 인수인계 시나리오 고려
담당자가 바뀌어도 이해할 수 있도록 **맥락**을 함께 기록합니다.
- "왜 이 옵션을 사용하는가?"
- "과거 어떤 문제가 있었는가?"
### 2. 버전 정보 명시
```markdown
- Docker 버전: 20.10.x 이상
- Node.js 버전: 16.x
- PostgreSQL: 13.x
```
### 3. 연락처 및 이슈 트래킹
- 원본 요청자/담당자 정보
- 관련 이슈 티켓 번호
- 최종 업데이트 일자
---
## 문서 관리 위치
프로젝트 구조에 따라 다르지만, 일반적으로 추천하는 위치:
```
project-root/
├── docs/
│ ├── deployment/ # 배포 가이드
│ ├── recovery/ # 복구 가이드
│ └── troubleshooting/ # 장애 대응
└── README.md
```
팀원 모두가 접근 가능한 Wiki나 Confluence에 동기화하는 것도 좋은 방법입니다.
---
## 결론
복구 가이드 문서화는 단순한 메모가 아니라 **팀의 안전망**입니다. 특히:
- ✅ 긴급 상황에서 빠른 대응 가능
- ✅ 담당자 변경 시 인수인계 시간 단축
- ✅ 반복되는 질문 방지
**다음 단계**: 현재 담당하고 있는 서비스 중 문서가 없는 것이 있다면, 오늘부터 간단한 복구 가이드를 작성해보세요. 미래의 자신과 팀원이 감사할 것입니다.
---
### 참고 자료
- Docker 공식 네트워크 문서: https://docs.docker.com/network/
- PostgreSQL 연결 문제 해결: https://www.postgresql.org/docs/current/libpq-connect.html