문제 상황
배포 서버에서 가장 흔한 실수는 코드가 바뀌었는데 컨테이너만 재시작하거나, 반대로 환경변수만 바뀌었는데 전체 이미지를 다시 만드는 것입니다. 두 작업은 비슷해 보이지만 실제 비용과 반영 범위가 다릅니다.
build가 필요한 경우
Dockerfile의 COPY, RUN npm run build, npm ci처럼 이미지 레이어에 들어가는 값이 바뀌면 build가 필요합니다. 프론트엔드 번들에 들어가는 공개 환경변수도 빌드 결과에 고정되므로 다시 빌드해야 합니다.
restart로 충분한 경우
이미지 내용은 그대로이고 프로세스 실행 시점에 읽는 환경변수만 바뀌었다면 restart나 recreate로 충분합니다. 예를 들어 백엔드의 JWT secret, CORS origin, 로그 레벨처럼 프로세스 시작 시 읽는 값은 새 컨테이너가 뜨면 반영됩니다.
운영 기준
- 소스, lockfile, Dockerfile, 빌드 args 변경: build
- runtime env, healthcheck, restart policy 변경: recreate 또는 restart
- 네트워크, 볼륨, reverse proxy 변경: redeploy 후 라우팅 확인
결론
build는 산출물을 바꾸는 작업이고 restart는 실행 상태를 다시 여는 작업입니다. 운영 문서에 이 구분을 짧게 적어 두면 배포 실수를 크게 줄일 수 있습니다.