한 장으로 끝내는 DevOps 매뉴얼: 1인 개발자도 팀처럼 배포하는 포켓 가이드

소프트웨어를 혼자서 배포하는 일이 꼭 전기톱을 저글링하는 기분일 필요는 없다.

신뢰성 있게 배포하려고 거대한 DevOps 플랫폼이나 대규모 팀 프로세스가 꼭 필요한 건 아니다. 진짜 필요한 건 아주 작은 구조화다. 밤샘 장애, 사라진 맥락, “잠깐, 지난번엔 이거 어떻게 배포했더라?” 같은 순간으로부터 당신을 보호해 줄 만큼의 구조.

그 구조는 한 개의 문서 안에 모두 담을 수 있다. 바로 원페이지 DevOps 매뉴얼이다.

이 글에서는 1인 개발자나 소규모 팀이 이 한 장짜리 문서를 어떻게 설계하면, 쓸데없이 복잡한 프로세스 없이도 잘 조직된 엔지니어링 조직처럼 배포할 수 있는지 살펴본다.

원페이지 DevOps 매뉴얼이란?

프로덕션에서 내 앱을 어떻게 운영할지에 대한 포켓 가이드라고 생각하면 된다.

어떻게 배포할지
어떻게 롤백할지
장애가 나면 어떻게 대응할지
“배포” 버튼을 누르기 전에 무엇이 반드시 충족되어야 하는지
실수로 프로덕션을 박살내지 않게 해 주는 최소한의 규칙들

이 문서는 모든 걸 다 담는 게 목적이 아니다. 대신에 이런 걸 목표로 한다.

2–3분 안에 다 읽을 수 있을 것
나만의 핵심 운영 습관을 캡처할 것
그때그때 감으로 결정하던 걸 재현 가능한 단계로 치환할 것

저장소에 ONE_PAGE_DEVOPS.md 같은 이름으로 넣어 두고, 배워나가면서 계속 업데이트하면 된다.

이제 핵심 구성 요소들을 하나씩 쪼개 보자.

1. 런북 템플릿: 반복 작업을 ‘좋게’ 지루하게 만들기

1인 개발자의 가장 큰 숨은 비용은 이미 해봤던 일을 다시 ‘어떻게 하지?’ 하고 매번 재결정하는 시간이다. 재시작, DB 마이그레이션, 캐시 플러시, 로그 확인 등등.

런북은 이런 혼란을 단계별로 따라 할 수 있는, 복사-붙여넣기 가능한 절차로 바꿔 준다.

런북(runbook) 은 짧고 구조화된 문서로, 다음 질문에 답한다.

이 작업은 무엇인가?
언제 이 작업을 수행해야 하나?
구체적으로 어떻게 해야 하나?
제대로 됐는지 어떻게 확인하나?

작업마다 파일을 따로 만들 필요는 없다. 이 원페이지 매뉴얼 안에 간단한 런북 템플릿을 정의하고, 가장 자주 하는 작업 2–5개만 채워 넣어도 충분하다.

런북 템플릿 예시:

### Runbook: [작업 이름]

**목적(Purpose):** 이 작업이 존재하는 이유 (1–2문장).

**실행 시점(When to run):** 어떤 트리거/상황에서 실행하는지.

**사전 점검(Pre-checks):**
- [ ] 점검 모드로 전환해야 하는 서비스가 있는가?
- [ ] 먼저 백업을 받아야 하는가?

**단계(Steps):**
1. Step 1
2. Step 2
3. Step 3

**검증(Validation):**
- [ ] 로그에 이상 없음
- [ ] 헬스 체크 통과
- [ ] 핵심 사용자 플로우 정상 동작: [설명]

**롤백 계획(Rollback plan):**
- [ ] 문제가 생겼을 때 되돌리거나 완화하는 방법

여기에 예를 들어 이런 런북들을 채워 넣어 보자.

“새 버전 배포하기”
“데이터베이스 마이그레이션 실행하기”
“앱 / 워커 서비스 재시작하기”

앞으로 이런 작업을 할 때마다 런북을 따라가며 실행하고, 더 나은 방법을 찾으면 그때그때 업데이트한다. 시간이 지나면 1인 개발자라도 운영이 점점 일관되고 예측 가능해진다.

2. 장애 대응 플레이북: 불이 난 뒤에는 즉흥으로 하지 말 것

프로덕션이 다운되면, 그 순간 당신의 뇌는 가장 신뢰하기 어려운 도구가 된다.

그래서 팀들은 장애 대응 플레이북(incident response playbook) 을 만든다. 가장 가능성 높은 장애 상황을 위해, 미리 써 둔 단계별 대응 가이드다. 1인 개발자도 마찬가지로 만들 수 있는데, 조금 더 가볍고 혼자 쓰기 좋게 만들면 된다.

원페이지 DevOps 매뉴얼 안에 이런 상황들을 위한 1–3개 정도의 장애 플레이북을 넣어 두자.

앱은 살아있지만 심각하게 느린 경우
API가 5xx 에러를 반환하는 경우
데이터베이스가 과부하 상태이거나 접근 불가한 경우

각 플레이북은 이런 질문에 답한다.

첫 액션: 가장 먼저 무엇을 확인해야 하는가?
트리아지 경로: 어떤 메트릭/로그/툴을 어떤 순서로 볼 것인가?
임시 완화책: 피해를 빨리 줄이는 방법은?
언제 롤백하거나 기능을 끌 것인가?

장애 플레이북 예시: “API가 5xx 에러를 쏟아낼 때”

### Incident Playbook: API 5xx Spikes

**증상(Symptoms):**
- 5분 이상 에러율 5% 초과
- 사용자들이 데이터 로딩 실패를 신고

**첫 액션(First moves, 순서대로):**
1. 프로덕션 로그에서 새로운 에러 패턴이 있는지 확인.
2. 마지막 배포 버전 및 배포 시각 확인.
3. 최근 30분 안에 배포가 있었다면 롤백 준비.

**트리아지 경로(Triage path):**
1. 앱 서버 CPU/메모리 사용량 확인.
2. DB 연결 수, 슬로 쿼리 확인.
3. 사용하는 서드파티 API들의 상태 페이지/장애 여부 확인.

**빠른 완화책(Fast mitigations):**
- 배포 직후부터 에러가 발생했다면: 이전 버전으로 롤백.
- DB 과부하라면: 중요도가 낮은 백그라운드 잡을 일시 중단.

**사후 정리(After incident):**
- 5–10개 bullet로 요약: 어떤 일이 있었는지, 무엇이 문제를 해결했는지.
- 새롭게 배운 점이나 필요한 단계가 있다면 이 플레이북에 추가.

목표는 완벽한 문서를 만드는 게 아니다. 목표는, 스트레스받는 순간에 매번 머릿속에서 처음부터 생각을 시작하지 않도록 만드는 것이다.

3. DevOps 가드레일: 1인 개발자에게 팀 수준의 안전망을

1인 개발자는 ‘프로세스’라는 말을 들으면 보통 귀찮고 무거운 걸 떠올린다. 하지만 아주 얇은 몇 가지 가드레일(guardrails) 만 있어도, 부담은 거의 없이 팀 수준의 안전을 누릴 수 있다.

이 가드레일들은 원페이지 매뉴얼에서 **“있으면 좋겠는 것”이 아니라 “반드시 지키는 규칙”**으로 적어 두자.

a) main/production 브랜치 보호하기

메인 브랜치를 절대 메모장처럼 다루지 말자.

브랜치 보호 규칙을 설정해 다음을 강제한다.

main 혹은 master 브랜치에 누구도(본인 포함) 직접 push할 수 없게 만들기
모든 변경은 반드시 Pull Request(PR) 를 통해서만 들어가게 하기

1인 개발자에게도 이게 중요한 이유:

강제로 한 번 더 멈춰서 자기 코드를 검토하게 만든다.
실수로 git push 한 번에 덜 완성된 코드가 그대로 프로덕션으로 가는 상황을 막는다.

혼자 올리고 혼자 리뷰하는 셀프 PR 이라도, 로컬 아무 상태에서 그냥 머지하는 것보다는 훨씬 낫다.

b) 머지 전 빌드(와 테스트) 통과 강제하기

보호된 브랜치는 CI를 통과한 코드만 받도록 설정하자.

저장소를 이렇게 설정한다.

main 으로 PR을 머지하기 전, CI가 빌드를 실행해야 한다.
가능하다면 유닛 테스트나 최소한의 스모크 테스트도 통과해야 한다.

이렇게 하면:

모든 변경에 대해 최소한의 품질 기준선이 생긴다.
깨진 빌드를 프로덕션에 올리기 전에 미리 잡아낼 수 있다.

이는 대기업식 관료주의가 아니라, 미래의 고통을 줄여 주는 아주 작은 자동화다.

c) PR을 1인용 ‘자기 리뷰’ 도구로 쓰기

저장소에 혼자 있다고 해도, PR은 충분히 유용하다.

간단히 PR 설명을 남긴다: 무엇이 바뀌었는지, 왜 바꿨는지, 어떤 리스크가 있는지.
마치 다른 사람 코드 보듯이 diff를 한 번 쭉 훑어본다.
그다음에 머지 버튼을 누른다.

이렇게 30초만 시야를 바꿔 보는 것만으로도 눈에 띄는 실수를 꽤 많이 잡을 수 있다.

4. 배포 전 체크리스트: 마지막 안전망

사람은 원래 모든 걸 기억 못 한다. 특히 시간이 없고 급할 때는 더더욱.

배포 전 체크리스트(pre-deployment checklist) 는 매번 릴리스를 하기 전에 반드시 거치는 짧은 단계 목록이다. 이 리스트는 원페이지 매뉴얼 안에 두고, 모든 프로덕션 변경에 재사용한다.

배포 전 체크리스트 예시:

### Pre-Deployment Checklist

- [ ] CI에서 모든 테스트 통과
- [ ] PR 설명에 변경 사항과 리스크가 명확히 적혀 있음
- [ ] 데이터베이스 마이그레이션을 로컬에서 검토 및 테스트 완료
- [ ] 리스크가 큰 변경은 필요한 경우 기능 플래그(Feature flag) 준비
- [ ] 롤백 계획 작성 완료 (이 변경을 어떻게 되돌릴지)
- [ ] 모니터링 대시보드 확인 (현재 기준선이 정상인지)
- [ ] 변경 로그(Changelog) 또는 릴리스 노트 업데이트

스택에 맞게 항목을 수정하되, 실제로 매번 사용할 만큼 짧게 유지하는 게 중요하다.

이 체크리스트는 다음을 도와준다.

마이그레이션을 빼먹거나, 크론 잡을 깨먹는 등 놓치기 쉬운 단계를 걸러 준다.
여러 달이 지나도 릴리스 과정을 일관되게 유지해 준다.
“내가 뭔가 빠뜨린 건 없나?”라는 불안을 줄여 준다. 할 건 다 했다는 확신이 생기기 때문이다.

시간이 지나면서 문제가 생기면 이렇게 자문해 보자. “이걸 체크리스트에 한 줄 추가해야 할까?” 이런 식으로, 쓸데없이 의식을 늘리지 않고도 점점 더 나은 시스템으로 개선해 갈 수 있다.

5. 1인 개발 환경을 ‘작은 팀 환경’처럼 대하라

여기서 필요한 사고방식 전환은 단순하다.

“어차피 나 혼자니까” 하는 태도에서 벗어나, 사람은 거의 없고 자동화가 많은 아주 작은 팀처럼 내 환경을 대하라.

큰 조직에서는 사람 수가 채워 주는 걸, 여기서는 템플릿, 자동화, 정책이 대신해 준다고 생각하자.

런북은 구전 지식(“나만 아는 요령”)을 문서로 대체한다.
장애 플레이북은 전사적 ‘워룸’ 회의를 대신한다.
브랜치 보호와 PR 은 동료들의 시선과 압박을 대신한다.
CI 체크 는 “내 로컬에선 되는데?”를 대신한다.
배포 전 체크리스트 는 기억력과 ‘야근 영웅 모드’를 대신한다.

이 모든 것을 한데 엮어 주는 게 바로 원페이지 매뉴얼이다. 무언가가 깨졌을 때든, 나중에 협업자를 온보딩할 때든, 이 문서는 운영에 관한 단일한 진실의 원천(single source of truth) 이 된다.

하나로 모으기: `ONE_PAGE_DEVOPS.md` 예시 레이아웃

다음은 간단한 ONE_PAGE_DEVOPS.md 아웃라인 예시다.

# One-Page DevOps Manual

## 1. Guardrails
- Protected branches: main
- main에 직접 push 금지; PR로만 변경
- 머지 전 CI 통과 필수

## 2. Pre-Deployment Checklist
[여기에 본인의 체크리스트를 작성]

## 3. Runbooks
- 새 버전 배포
- DB 마이그레이션 실행
- 앱/워커 재시작

## 4. Incident Playbooks
- API 5xx 급증
- 앱 느림 / 고지연

## 5. Notes & Improvements
- 아이디어, 배운 점, 향후 개선 아이템을 이곳에 적어 둔다.

시작은 이 정도면 충분하다.

짧게 유지하라. 잘 보이는 곳에 두어라. 그리고 현실이 (때때로 고통스럽게) 새로운 걸 가르쳐 줄 때마다 업데이트하라.

마무리: 혼자여도 팀처럼 배포하기

규모가 큰 엔터프라이즈 툴이 있어야만 조직적인 개발을 할 수 있는 건 아니다. 필요한 건 다음뿐이다.

간단하지만 살아 움직이는 원페이지 매뉴얼
가장 흔한 실수를 막아 줄 몇 가지 가드레일
루틴 작업과 위기 상황 모두에서 나를 침착하게 만들어 줄 런북과 플레이북
매번의 릴리스를 하나의 의식처럼 반복 가능하게 만들어 줄 배포 전 체크리스트

이것들을 갖추면, 내 개발 환경은 ‘영웅 하나가 다 떠받치는 구조’에서 시스템이 굴러가게 만드는 구조로 바뀐다. 더 자신 있게 배포하게 되고, 프로덕션을 망가뜨리는 일은 줄어들며, 설령 문제가 생겨도 더 침착한 과거의 내가 써 둔 계획을 참고할 수 있게 된다.

한 장으로 시작하라. 매 배포와 매 장애를 겪을 때마다 조금씩 다듬어라. 시간이 지나면 이 문서 한 장이, 방 안에 나 혼자 있을 때에도 나를 ‘팀처럼’ 움직이게 해 주는 조용한 동료가 되어 있을 것이다.