개발 slecs

광고 빌드·nginx·어드민 DB를 리포로 끌어들인 배포 자동화 첫 세트

목차

배포 자동화 첫 세트를 하나의 커밋으로 묶어서 올렸다. publish.sh, 빌드 스크립트, nginx 설정, DB 초기화 SQL까지 — 흩어져 있던 배포 재료들을 한 번에 리포지토리 안으로 끌어들인 작업이었다.

왜 이 타이밍에 배포 아티팩트를 묶었나

프로젝트 초반에는 "배포는 나중에"라는 암묵적인 합의가 팀 안에 늘 존재한다. 기능 개발에 치이다 보면 배포 관련 파일들은 누군가의 로컬, 슬랙 메시지, 위키 어딘가에 흩어지게 된다. 이 상태가 길어지면 "실제 배포 방법을 아는 사람이 한 명"인 상황이 만들어지고, 그 사람이 자리를 비우면 팀 전체가 멈춘다.

이번에 publish.sh부터 nginx 설정, DB 초기화 SQL까지 한 커밋으로 묶은 건 단순히 "파일 정리"가 아니었다. 배포 지식을 코드로 문서화하는 작업이었다. 팀원 누구든 리포지토리를 클론하면 배포 흐름을 따라갈 수 있어야 한다는 원칙을 실제로 구현한 것.

변경 파일별 역할 정리

파일 위치 역할
build-ads.js build-ads/ 광고 관련 에셋 빌드 메인 스크립트
package.json build-ads/ 빌드 의존성 및 스크립트 선언
.env.example build-ads/ 환경변수 템플릿 — 민감 정보 없이 구조만 공개
README.md build-ads/ 빌드 스크립트 사용법 문서
admin-db-init.sql deploy/ 어드민 DB 초기 스키마 및 시드 SQL
nginx-job.conf deploy/ nginx 라우팅/프록시 설정

파일 수 자체는 많지 않지만 레이어가 다양하다. 프론트 빌드, 인프라 설정, DB 초기화가 하나의 커밋 안에 묶인 셈이다. 이런 경우 커밋을 쪼개는 게 맞지 않냐는 의견도 있을 수 있다.

실제로 팀 내 코드리뷰에서도 그 질문이 나왔다. 내 판단은 "이 파일들은 함께 동작해야 의미가 있다" 였다. nginx 설정만 있고 DB가 없으면 어드민이 뜨지 않고, 빌드 스크립트만 있고 .env.example이 없으면 신규 투입 멤버가 첫 실행에서 막힌다. 배포 단위로 묶는 것이 원자성 측면에서 더 명확하다고 봤다.

.env.example과 README.md — 작은 파일이 주는 큰 맥락

빌드 스크립트를 짤 때 .env.example을 함께 넣는 건 습관처럼 해온 일이지만, 팀 전체 입장에서 보면 이게 온보딩 비용을 낮추는 가장 저렴한 방법 중 하나다.

# build-ads/.env.example
API_BASE_URL=
CDN_BUCKET=
BUILD_ENV=production

실제 값은 없지만 "어떤 환경변수가 필요한지"를 코드가 직접 알려준다. 신규 팀원이 세팅하다가 누군가를 붙잡고 물어보는 횟수가 눈에 띄게 줄었다. README.md도 마찬가지 — 빌드 스크립트가 아무리 잘 짜여 있어도 진입점이 문서화되어 있지 않으면 블랙박스다.

admin-db-init.sql을 리포에 넣는 기준

DB 초기화 SQL을 버전 관리에 포함할지는 팀마다 의견이 갈린다. 운영 DB 스키마 전체를 SQL 덤프로 관리하면 마이그레이션 도구(Flyway, Liquibase 등)와 충돌하거나 관리 포인트가 이중화되는 문제가 생기기도 한다.

이번 admin-db-init.sql은 어드민 전용 초기 스키마 한정이라 범위가 명확했다. 운영 메인 DB와 분리된 어드민 DB를 새 환경에서 띄울 때 필요한 최소한의 DDL + 초기 데이터만 담았다. 이 정도 범위라면 SQL 파일 자체를 리포에 두는 게 마이그레이션 히스토리를 추적하기에도 낫다고 판단했다.

  • 민감 데이터(실 계정, 패스워드 등) 절대 포함 금지
  • 초기화 용도임을 파일명과 주석으로 명시
  • 로컬 / 스테이징 / 운영 환경 분기 필요 시 파일 분리 고려

nginx 설정을 코드로 관리하는 이유

nginx-job.conf를 서버에 직접 관리하면 어느 순간 "서버에만 있는 설정"이 된다. 서버가 교체되거나 새 인스턴스가 추가될 때 설정이 유실되거나 버전이 달라지는 문제가 생긴다. 리포에 넣어두면 변경 이력이 남고, PR 리뷰를 통해 nginx 설정 변경도 팀이 함께 검토할 수 있다.

배포 자동화 첫 세트라는 타이틀이 어울리는 커밋이었다. 기능 코드는 꽤 쌓였는데 "어떻게 띄우는지"가 문서화되지 않은 상태였다면, 이 커밋이 그 공백을 채운 셈이다.

다음 단계는 publish.sh 안의 수동 스텝들을 CI 파이프라인으로 연결하는 것.

🛒 이 글과 어울리는 추천 상품

*위 링크는 쿠팡파트너스 활동의 일환이며, 일정액의 수수료를 제공받을 수 있습니다.

이어보기

댓글 0

첫 댓글 달아줘.