TIL - 20260803

juni·2026년 8월 3일
TIL

TIL

목록 보기
421/468

0803 인프라/DevOps 운영 심화 (2/N): Docker, OrbStack과 개발 DB 운영

✅ 1. Docker란 무엇인가?

  • Docker는 애플리케이션 실행에 필요한 환경을 컨테이너로 묶어서 실행하는 도구입니다.
  • Node.js, PostgreSQL, Redis, Nginx 같은 실행 환경을 내 Mac에 직접 설치하지 않고도 독립된 공간에서 실행할 수 있습니다.
  • 로컬 개발환경, 테스트 환경, 배포 환경을 최대한 비슷하게 맞추는 데 유용합니다.
Mac
  ↓
Docker / OrbStack
  ↓
Container
  ├─ PostgreSQL
  ├─ Redis
  ├─ Backend
  ├─ Worker
  └─ Nginx

➕ 1-1. Docker를 쓰는 이유

  • 개발환경을 재현하기 쉽습니다.
  • PostgreSQL, Redis 같은 인프라를 쉽게 켜고 끌 수 있습니다.
  • 프로젝트마다 다른 버전의 DB를 분리해서 쓸 수 있습니다.
  • 새 Mac으로 옮겨도 docker compose up -d로 환경을 빠르게 복구할 수 있습니다.
  • 운영 배포 구조와 비슷한 환경을 로컬에서 테스트할 수 있습니다.
Docker 없이:
PostgreSQL 직접 설치
Redis 직접 설치
버전 충돌 가능
프로젝트마다 환경 꼬임

Docker 사용:
프로젝트별 compose 파일
컨테이너 단위 실행
버전 명시 가능
삭제/재생성 쉬움

✅ 2. Docker와 OrbStack의 관계

  • Docker는 컨테이너 기술과 생태계이고, OrbStack은 Mac에서 Docker 컨테이너를 더 가볍고 빠르게 실행할 수 있게 해주는 도구입니다.
  • Docker Desktop 대신 OrbStack을 쓰는 느낌으로 이해하면 됩니다.
  • 명령어는 대부분 동일하게 docker, docker compose를 사용합니다.
Docker:
컨테이너 실행 표준

Docker Desktop:
Mac에서 Docker를 실행하는 대표 앱

OrbStack:
Mac에서 Docker를 실행하는 가벼운 대안

➕ 2-1. OrbStack을 쓰는 이유

  • Docker Desktop보다 가볍게 느껴질 수 있습니다.
  • Mac에서 메모리 사용량이 비교적 부담이 적습니다.
  • 컨테이너, 볼륨, 네트워크 관리가 편합니다.
  • 로컬 개발용 PostgreSQL, Redis를 켜고 끄기에 좋습니다.

➕ 2-2. 주의할 점

OrbStack도 결국 컨테이너 실행 환경
컨테이너를 많이 켜면 RAM 사용
DB 볼륨을 지우면 데이터 삭제
프로젝트별 포트 충돌 주의
운영 서버와 완전히 같지는 않음
  • OrbStack이 가볍다고 해도 컨테이너를 무제한 켜도 되는 것은 아닙니다.
  • 필요한 프로젝트 인프라만 켜고, 안 쓰는 컨테이너는 끄는 습관이 좋습니다.

✅ 3. 컨테이너, 이미지, 볼륨, 네트워크

  • Docker를 이해하려면 이미지, 컨테이너, 볼륨, 네트워크 개념을 알아야 합니다.
개념의미예시
Image실행 템플릿postgres:16
Container실제 실행 중인 인스턴스togethermall-postgres
Volume데이터 저장 공간PostgreSQL 데이터
Network컨테이너 간 통신망backend ↔ postgres

➕ 3-1. 이미지

이미지:
컨테이너를 만들기 위한 원본

예:
postgres:16
redis:7
node:20-alpine
nginx:alpine

➕ 3-2. 컨테이너

컨테이너:
이미지를 실행한 실제 프로세스

예:
postgres 이미지를 실행하면
PostgreSQL 컨테이너가 됨

➕ 3-3. 볼륨

볼륨:
컨테이너가 삭제되어도 데이터를 보존하는 저장소

PostgreSQL:
DB 데이터는 반드시 volume에 저장해야 함

➕ 3-4. 네트워크

네트워크:
컨테이너끼리 이름으로 통신할 수 있게 해주는 연결

예:
backend 컨테이너에서 postgres 컨테이너 접속
host: postgres
port: 5432

✅ 4. Docker Compose란 무엇인가?

  • Docker Compose는 여러 컨테이너를 하나의 설정 파일로 관리하는 도구입니다.
  • PostgreSQL, Redis, Backend, Worker를 한 번에 켜고 끌 수 있습니다.
  • 로컬 개발환경에서는 거의 필수에 가깝습니다.
docker-compose.yml
  ↓
docker compose up -d
  ↓
PostgreSQL + Redis + Backend 실행

➕ 4-1. 자주 쓰는 명령어

docker compose up -d
docker compose down
docker compose ps
docker compose logs -f
docker compose restart
docker compose pull

➕ 4-2. 의미

명령어의미
up -d백그라운드 실행
down컨테이너 중지 및 제거
ps실행 상태 확인
logs -f로그 실시간 확인
restart재시작
pull이미지 최신 다운로드
  • 로컬에서는 up -d, down, logs -f, ps만 잘 써도 충분합니다.

✅ 5. 로컬 개발 DB를 Docker로 운영하는 이유

  • PostgreSQL을 Mac에 직접 설치할 수도 있지만, 프로젝트가 늘어나면 버전과 포트 관리가 복잡해집니다.
  • Docker/OrbStack으로 DB를 띄우면 프로젝트별로 분리하기 쉽습니다.

➕ 5-1. 직접 설치 방식

Mac에 PostgreSQL 직접 설치
  ↓
항상 background service로 실행
  ↓
모든 프로젝트가 localhost:5432 공유
  ↓
버전/데이터/권한 충돌 가능

➕ 5-2. Docker 방식

프로젝트별 PostgreSQL 컨테이너
  ↓
프로젝트별 DB/계정/볼륨 분리
  ↓
필요할 때만 실행
  ↓
삭제/재생성 쉬움

➕ 5-3. 현재 상황에 맞는 추천

개발 서버:
IDE에서 npm run dev로 실행

DB:
OrbStack PostgreSQL 컨테이너로 실행

Redis:
필요할 때만 컨테이너로 실행

Backend/Frontend:
초기에는 로컬 Node 실행 유지
  • 지금처럼 프론트/어드민/백엔드를 IDE에서 직접 실행하는 구조라면, DB와 Redis만 컨테이너로 두는 것이 가장 현실적입니다.
  • 모든 앱까지 Docker에 넣는 것은 나중에 필요할 때 해도 됩니다.

✅ 6. PostgreSQL Docker Compose 예시

  • 로컬 개발용 PostgreSQL은 compose 파일로 관리하는 것이 좋습니다.
services:
  postgres:
    image: postgres:16
    container_name: togethermall-postgres
    restart: unless-stopped
    ports:
      - "5432:5432"
    environment:
      POSTGRES_USER: together
      POSTGRES_PASSWORD: together_local_password
      POSTGRES_DB: together
    volumes:
      - togethermall_postgres_data:/var/lib/postgresql/data

volumes:
  togethermall_postgres_data:

➕ 6-1. 실행

docker compose up -d

➕ 6-2. 상태 확인

docker compose ps

➕ 6-3. 로그 확인

docker compose logs -f postgres
  • POSTGRES_PASSWORD는 로컬 개발용 값입니다.
  • 운영 DB 비밀번호와 같게 만들면 안 됩니다.

✅ 7. DATABASE_URL 설정

  • 백엔드에서 PostgreSQL에 접속하려면 DATABASE_URL이 필요합니다.
  • 로컬 Node.js 앱이 Docker 컨테이너 DB에 접속할 때는 보통 localhost:5432를 사용합니다.
DATABASE_URL="postgresql://together:together_local_password@localhost:5432/together?schema=public"

➕ 7-1. 로컬 Node에서 접속

Backend:
Mac에서 npm run dev

PostgreSQL:
Docker 컨테이너

접속 주소:
localhost:5432

➕ 7-2. 컨테이너 내부 backend에서 접속

DATABASE_URL="postgresql://together:together_local_password@postgres:5432/together?schema=public"
Backend:
Docker 컨테이너

PostgreSQL:
Docker 컨테이너

접속 주소:
postgres:5432
  • 백엔드가 Mac에서 실행되면 localhost.
  • 백엔드도 컨테이너 안에서 실행되면 compose service name인 postgres를 사용합니다.
  • 이 차이를 헷갈리면 DB 연결 오류가 납니다.

✅ 8. Prisma와 Docker DB

  • Prisma를 사용한다면 Docker DB가 켜진 상태에서 migrate/generate/seed를 실행해야 합니다.
  • DB가 꺼져 있으면 PrismaClientInitializationError가 발생할 수 있습니다.

➕ 8-1. 기본 순서

docker compose up -d
npx prisma generate
npx prisma migrate dev
npm run seed
npm run dev

➕ 8-2. DB 연결 확인

npx prisma validate
npx prisma db pull

➕ 8-3. 자주 발생하는 문제

DB 컨테이너가 꺼져 있음
DATABASE_URL 포트가 틀림
POSTGRES_USER/PASSWORD가 다름
DB 이름이 다름
shadow database 권한 없음
migration 상태가 꼬임
  • Prisma 에러가 나면 백엔드 코드보다 먼저 DB 컨테이너 상태와 DATABASE_URL을 확인해야 합니다.

✅ 9. Shadow Database

  • Prisma migrate를 사용할 때 shadow database가 필요할 수 있습니다.
  • 로컬에서는 별도 shadow DB를 만들어두는 것이 좋습니다.

➕ 9-1. 예시

SHADOW_DATABASE_URL="postgresql://together:together_local_password@localhost:5432/together_shadow?schema=public"

➕ 9-2. 생성 명령

docker exec -it togethermall-postgres psql -U together -d postgres
CREATE DATABASE together_shadow;

➕ 9-3. 확인

\l
  • shadow DB가 없거나 권한이 부족하면 migration 중 에러가 날 수 있습니다.
  • 새 Mac 세팅 시 실제 개발 DB와 shadow DB를 모두 만들어야 합니다.

✅ 10. Redis Docker Compose 예시

  • Queue, Cache, Rate Limit, Session 등에 Redis를 쓴다면 Redis도 compose에 추가할 수 있습니다.
services:
  postgres:
    image: postgres:16
    container_name: togethermall-postgres
    restart: unless-stopped
    ports:
      - "5432:5432"
    environment:
      POSTGRES_USER: together
      POSTGRES_PASSWORD: together_local_password
      POSTGRES_DB: together
    volumes:
      - togethermall_postgres_data:/var/lib/postgresql/data

  redis:
    image: redis:7
    container_name: togethermall-redis
    restart: unless-stopped
    ports:
      - "6379:6379"
    volumes:
      - togethermall_redis_data:/data

volumes:
  togethermall_postgres_data:
  togethermall_redis_data:

➕ 10-1. Redis URL

REDIS_URL="redis://localhost:6379"

➕ 10-2. Redis 상태 확인

docker exec -it togethermall-redis redis-cli ping

정상 응답:

PONG
  • Redis는 필요한 프로젝트에서만 켜면 됩니다.
  • Queue Worker가 없거나 Redis를 쓰지 않는 기능이면 굳이 항상 켤 필요는 없습니다.

✅ 11. 프로젝트별 포트 충돌 관리

  • 여러 프로젝트를 동시에 운영하면 포트 충돌이 자주 납니다.
  • PostgreSQL은 기본 5432, Redis는 6379, 백엔드는 3000, 프론트는 5173 등을 자주 씁니다.

➕ 11-1. 포트 충돌 예시

프로젝트 A PostgreSQL:
localhost:5432

프로젝트 B PostgreSQL:
localhost:5432

결과:
둘 중 하나만 실행 가능

➕ 11-2. 해결 방법

ports:
  - "5433:5432"
DATABASE_URL="postgresql://user:password@localhost:5433/project_b?schema=public"

➕ 11-3. 추천 기준

메인 프로젝트:
PostgreSQL 5432
Redis 6379

서브 프로젝트:
PostgreSQL 5433, 5434
Redis 6380, 6381
  • 동시에 여러 프로젝트를 켜야 한다면 포트를 분리해야 합니다.
  • 하지만 평소에는 필요한 프로젝트 하나만 켜는 것이 가장 깔끔합니다.

✅ 12. 볼륨 관리

  • Docker에서 DB 데이터는 volume에 저장됩니다.
  • 컨테이너를 지워도 volume이 남아 있으면 DB 데이터는 유지됩니다.

➕ 12-1. 컨테이너만 내리기

docker compose down
  • 컨테이너는 제거되지만 volume은 유지됩니다.

➕ 12-2. 볼륨까지 삭제

docker compose down -v
  • DB 데이터까지 삭제됩니다.
  • 조심해서 사용해야 합니다.

➕ 12-3. 볼륨 목록 확인

docker volume ls

➕ 12-4. 볼륨 삭제

docker volume rm togethermall_postgres_data
  • down -v는 로컬 DB를 초기화할 때는 편하지만, 실수하면 데이터가 날아갑니다.
  • 운영 DB에서는 절대 이런 식으로 접근하면 안 됩니다.

✅ 13. DB 초기화가 필요한 경우

  • 로컬 개발 중 migration이 꼬이거나 seed 데이터가 망가졌다면 DB를 초기화할 수 있습니다.
  • 단, 로컬에서만 안전합니다.

➕ 13-1. 로컬 DB 초기화 흐름

docker compose down -v
docker compose up -d
npx prisma migrate dev
npm run seed

➕ 13-2. Prisma reset

npx prisma migrate reset
  • migrate reset은 DB를 날리고 migration과 seed를 다시 실행합니다.
  • 로컬 개발 DB에서만 사용해야 합니다.

➕ 13-3. 주의

운영 DB에서 reset 금지
스테이징에서도 신중히 사용
seed가 최신인지 확인
로컬 테스트 데이터 삭제됨
  • DB 초기화 명령어는 강력합니다.
  • 실서버와 로컬 터미널을 헷갈리지 않게 prompt나 AWS profile, DB URL을 반드시 확인해야 합니다.

✅ 14. 로컬 DB 백업과 덤프

  • 로컬 DB도 필요하면 덤프를 떠둘 수 있습니다.
  • 테스트 데이터나 특정 상태를 보존하고 싶을 때 유용합니다.

➕ 14-1. pg_dump

docker exec togethermall-postgres pg_dump \
  -U together \
  -d together \
  > together_local_backup.sql

➕ 14-2. 복원

cat together_local_backup.sql | docker exec -i togethermall-postgres psql \
  -U together \
  -d together

➕ 14-3. 주의

운영 데이터 덤프는 개인정보 포함 가능
로컬에 실데이터 저장 주의
Git에 dump 파일 절대 커밋 금지
백업 파일 이름에 날짜 포함
  • 운영 DB 덤프를 로컬로 가져오는 것은 보안상 매우 조심해야 합니다.
  • 고객 전화번호, 이름, 상담 메모가 포함될 수 있습니다.

✅ 15. Docker 로그 확인

  • 컨테이너가 정상 실행되지 않으면 로그를 봐야 합니다.

➕ 15-1. Compose 로그

docker compose logs -f postgres

➕ 15-2. 최근 로그만 보기

docker compose logs --tail=100 postgres

➕ 15-3. 컨테이너 직접 확인

docker logs togethermall-postgres
  • DB 연결이 안 될 때는 애플리케이션 로그와 DB 컨테이너 로그를 같이 봐야 합니다.
  • 컨테이너가 계속 재시작된다면 환경변수나 volume 권한 문제일 수 있습니다.

✅ 16. 컨테이너 안으로 들어가기

  • 컨테이너 내부에서 명령을 실행해야 할 때가 있습니다.
  • PostgreSQL에서는 psql, Redis에서는 redis-cli를 자주 씁니다.

➕ 16-1. PostgreSQL 접속

docker exec -it togethermall-postgres psql -U together -d together

➕ 16-2. DB 목록 보기

\l

➕ 16-3. 테이블 목록 보기

\dt

➕ 16-4. Redis 접속

docker exec -it togethermall-redis redis-cli
  • 컨테이너 내부에서 직접 확인하면 문제를 빨리 좁힐 수 있습니다.
  • 다만 운영 서버에서 직접 DB를 만지는 습관은 위험합니다.

✅ 17. Backend까지 Docker에 넣을까?

  • 로컬 개발에서 백엔드까지 Docker에 넣을 수는 있습니다.
  • 하지만 1인 개발자이고 IDE에서 빠르게 개발하는 상황이라면 처음부터 모든 앱을 Docker에 넣는 것은 오히려 번거로울 수 있습니다.

➕ 17-1. 백엔드 로컬 실행 방식

Backend:
Mac Node.js에서 npm run dev

DB:
Docker PostgreSQL

장점:
디버깅 쉬움
파일 변경 반영 빠름
IDE 연동 편함
메모리 사용 상대적으로 단순

➕ 17-2. 백엔드 Docker 실행 방식

Backend:
Docker 컨테이너

DB:
Docker PostgreSQL

장점:
운영 환경과 비슷함
팀원 온보딩 쉬움
Node 버전 통일 쉬움

단점:
볼륨/파일 watch 이슈
디버깅 번거로움
빌드/재시작 비용

➕ 17-3. 추천

지금 단계:
DB/Redis만 Docker
Backend/Frontend/Admin은 로컬 Node 실행

나중 단계:
배포 테스트용으로 backend Dockerfile 작성
CI/CD 또는 staging에서 container build
  • 현재는 DB와 Redis만 컨테이너로 두는 것이 가장 실용적입니다.
  • 백엔드 Docker화는 배포 자동화 단계에서 다뤄도 늦지 않습니다.

✅ 18. 프로젝트 3개를 동시에 다룰 때 구조

  • 여러 프로젝트를 동시에 관리한다면 인프라 컨테이너를 어떻게 나눌지 정해야 합니다.
  • 같은 PostgreSQL 하나에 DB만 나눌 수도 있고, 프로젝트별 PostgreSQL 컨테이너를 따로 둘 수도 있습니다.

➕ 18-1. 하나의 PostgreSQL 컨테이너 공유

postgres 컨테이너 1개
  ├─ project_a DB
  ├─ project_b DB
  └─ project_c DB

장점:

가벼움
관리 단순
포트 하나만 사용

단점:

프로젝트 간 완전 분리 아님
버전 다르게 쓰기 어려움
실수로 DB 선택 잘못할 수 있음

➕ 18-2. 프로젝트별 PostgreSQL 컨테이너 분리

project_a-postgres:5432
project_b-postgres:5433
project_c-postgres:5434

장점:

프로젝트별 완전 분리
삭제/초기화 안전
버전 다르게 가능

단점:

컨테이너 많아짐
포트 관리 필요
메모리 사용 증가

➕ 18-3. 추천

주력 프로젝트:
별도 compose + 별도 volume

가끔 보는 토이 프로젝트:
공유 PostgreSQL 또는 필요할 때만 실행

동시에 3개 상시 실행:
비추천, 필요한 것만 켜기
  • 48GB RAM 장비라도 모든 프로젝트를 항상 켜둘 필요는 없습니다.
  • “프로젝트별로 쉽게 켜고 끄는 구조”가 더 중요합니다.

✅ 19. Compose 파일 이름과 위치

  • compose 파일은 프로젝트 루트에 두는 것이 일반적입니다.
togethermall/
  docker-compose.yml
  package.json
  apps/
  packages/
  prisma/

➕ 19-1. 개발용과 운영용 분리

docker-compose.yml:
기본 또는 로컬 개발용

docker-compose.dev.yml:
개발용

docker-compose.prod.yml:
운영 배포용

docker-compose.override.yml:
개인 로컬 override

➕ 19-2. 실행 예시

docker compose -f docker-compose.dev.yml up -d
  • 처음에는 docker-compose.yml 하나로 시작해도 됩니다.
  • 운영 배포까지 Docker Compose로 할 계획이면 dev/prod를 분리하는 것이 좋습니다.

✅ 20. .env와 Docker Compose

  • Docker Compose에서도 .env를 사용할 수 있습니다.
  • 단, 로컬 개발용 값과 운영 Secret을 섞으면 안 됩니다.

➕ 20-1. compose에서 변수 사용

services:
  postgres:
    image: postgres:16
    ports:
      - "${POSTGRES_PORT}:5432"
    environment:
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: ${POSTGRES_DB}

➕ 20-2. .env 예시

POSTGRES_PORT=5432
POSTGRES_USER=together
POSTGRES_PASSWORD=together_local_password
POSTGRES_DB=together

➕ 20-3. 주의

로컬 compose .env는 Git 커밋 주의
.env.example 제공
운영 Secret과 동일한 값 사용 금지
비밀번호는 개발용이라도 너무 대충 공개하지 않기
  • 공개 레포라면 .env는 커밋하면 안 됩니다.
  • 대신 .env.example로 필요한 변수만 알려주는 것이 좋습니다.

✅ 21. .env.example 관리

  • 새 Mac 세팅이나 다른 환경 복구를 위해 .env.example은 중요합니다.
  • 실제 Secret 없이 구조만 남깁니다.
POSTGRES_PORT=5432
POSTGRES_USER=together
POSTGRES_PASSWORD=change_me
POSTGRES_DB=together

DATABASE_URL=postgresql://together:change_me@localhost:5432/together?schema=public
SHADOW_DATABASE_URL=postgresql://together:change_me@localhost:5432/together_shadow?schema=public
REDIS_URL=redis://localhost:6379

➕ 21-1. 좋은 .env.example

필요한 변수 모두 포함
실제 비밀번호 없음
로컬 실행 기준 설명
주석으로 용도 표시
최신 상태 유지
  • .env.example이 최신이면 새 장비에서 세팅이 훨씬 쉬워집니다.
  • AI에게 마이그레이션 작업을 맡길 때도 기준 파일로 쓰기 좋습니다.

✅ 22. 컨테이너 리소스 관리

  • Docker/OrbStack을 오래 쓰다 보면 안 쓰는 이미지, 컨테이너, 볼륨이 쌓입니다.
  • 디스크 용량과 메모리 사용량을 주기적으로 확인해야 합니다.

➕ 22-1. 상태 확인

docker system df

➕ 22-2. 사용하지 않는 컨테이너/이미지 정리

docker system prune

➕ 22-3. 볼륨까지 정리

docker system prune --volumes
  • --volumes는 DB 데이터까지 지울 수 있으므로 매우 조심해야 합니다.
  • 어떤 volume이 필요한지 모르면 실행하지 않는 것이 안전합니다.

➕ 22-4. 추천 습관

안 쓰는 프로젝트 컨테이너 down
필요 없는 이미지 정리
볼륨 삭제 전 이름 확인
DB 데이터 필요한지 확인
프로젝트별 volume 이름 명확히 작성

✅ 23. 개발환경 시작/종료 스크립트

  • 반복적으로 DB/Redis를 켜고 끄는 명령은 스크립트로 만들면 편합니다.

➕ 23-1. start script

#!/bin/bash
set -e

echo "Starting local infra..."
docker compose up -d postgres redis
docker compose ps

➕ 23-2. stop script

#!/bin/bash
set -e

echo "Stopping local infra..."
docker compose stop postgres redis
docker compose ps

➕ 23-3. package.json script

{
  "scripts": {
    "infra:up": "docker compose up -d postgres redis",
    "infra:down": "docker compose down",
    "infra:stop": "docker compose stop postgres redis",
    "infra:logs": "docker compose logs -f"
  }
}
  • down은 컨테이너 제거, stop은 중지입니다.
  • 로컬 DB 데이터를 유지하면서 잠시 끄려면 stop도 좋습니다.

✅ 24. 로컬 개발환경 표준 실행 순서

  • 새 Mac이나 재부팅 후 개발환경을 띄울 때 순서를 정해두면 좋습니다.
1. OrbStack 실행 확인
2. docker compose up -d postgres redis
3. docker compose ps
4. DATABASE_URL 확인
5. npx prisma generate
6. migration 상태 확인
7. 백엔드 npm run dev
8. 프론트/어드민 npm run dev
9. 주요 API 접속 확인

➕ 24-1. DB 연결 오류가 날 때 순서

1. docker compose ps
2. docker compose logs postgres
3. DATABASE_URL 확인
4. 포트 충돌 확인
5. psql 직접 접속
6. Prisma validate
7. 백엔드 재시작
  • 에러가 나면 무작정 코드를 수정하지 말고 인프라 상태부터 확인해야 합니다.
  • DB 연결 오류는 대부분 DB 미실행, URL 오류, 포트 충돌입니다.

✅ 25. 운영 DB와 로컬 DB를 절대 헷갈리지 않기

  • DevOps에서 가장 위험한 실수 중 하나는 로컬인 줄 알고 운영 DB를 건드리는 것입니다.
  • DB URL, AWS profile, 터미널 prompt, 환경변수를 확실히 구분해야 합니다.

➕ 25-1. 위험한 상황

DATABASE_URL이 운영 DB를 가리킴
로컬에서 migrate reset 실행
운영 DB에 seed 실행
실데이터 덤프를 Git에 커밋
실서버 데이터를 로컬 테스트처럼 수정

➕ 25-2. 방지 방법

.env.local과 .env.production 분리
운영 DATABASE_URL 로컬 저장 최소화
터미널에 현재 AWS profile 표시
운영 명령어는 별도 확인 프롬프트 추가
Prisma reset은 로컬에서만 실행
운영 DB 접속 권한 최소화

➕ 25-3. 로컬 DB 이름 기준

로컬 DB:
together_local 또는 together

Shadow DB:
together_shadow

스테이징 DB:
together_staging

운영 DB:
절대 로컬 명령어에서 사용하지 않기
  • 1인 개발자라도 운영 DB 보호는 절대 가볍게 보면 안 됩니다.
  • 실수 한 번이 고객 데이터 사고로 이어질 수 있습니다.

✅ 26. AI에게 Docker/DB 문제를 물어볼 때 좋은 질문법

  • Docker나 DB 연결 문제는 현재 상태 정보를 같이 줘야 정확한 답을 받을 수 있습니다.
  • 에러 메시지만 던지면 추측 답변이 나올 수 있습니다.

➕ 26-1. 좋은 질문 예시

Mac + OrbStack 환경에서 Docker Compose로 PostgreSQL을 띄우고, NestJS + Prisma 백엔드를 로컬 Node로 실행 중이야.

상황:
1. PostgreSQL 컨테이너 이름은 togethermall-postgres
2. compose ports는 "5432:5432"
3. POSTGRES_USER=together
4. POSTGRES_DB=together
5. DATABASE_URL은 postgresql://together:****@localhost:5432/together?schema=public
6. 백엔드는 Docker가 아니라 Mac에서 npm run dev로 실행함
7. npx prisma migrate dev 실행 시 DB 연결 오류가 남

아래 정보 기준으로 원인을 좁혀줘:
- docker compose ps 결과
- docker compose logs postgres 결과
- DATABASE_URL
- Prisma 에러 메시지

답변은 확인 순서와 수정 명령어 중심으로 정리해줘.

➕ 26-2. AI 답변 검증 기준

  1. 백엔드가 Mac에서 실행되는지 컨테이너에서 실행되는지 구분하는가?
  2. localhost와 compose service name 차이를 설명하는가?
  3. DB 컨테이너 상태를 먼저 확인하라고 하는가?
  4. 포트 충돌 가능성을 확인하는가?
  5. Prisma shadow DB 가능성을 언급하는가?
  6. 운영 DB reset 같은 위험한 명령을 함부로 제안하지 않는가?
  7. down -v의 데이터 삭제 위험을 설명하는가?
  8. 실제 명령어를 순서대로 제안하는가?

✅ 27. 실무 체크리스트

➕ 27-1. Docker Compose 체크리스트

  1. docker-compose.yml이 프로젝트 루트에 있는가?
  2. PostgreSQL image 버전이 명시되어 있는가?
  3. container_name이 프로젝트명 기준으로 명확한가?
  4. ports가 다른 프로젝트와 충돌하지 않는가?
  5. volume 이름이 프로젝트별로 구분되는가?
  6. POSTGRES_USER/PASSWORD/DB가 .env.example에 정리되어 있는가?
  7. Redis가 필요한 경우에만 포함되어 있는가?
  8. docker compose up -d로 재현 가능한가?

➕ 27-2. DB 운영 체크리스트

  1. 로컬 DATABASE_URL이 localhost 또는 올바른 포트를 가리키는가?
  2. 백엔드가 컨테이너인지 로컬 Node인지에 따라 DB host가 맞는가?
  3. shadow database가 필요한 경우 생성되어 있는가?
  4. migration 실행 전 DB 컨테이너가 켜져 있는가?
  5. seed가 최신 schema와 맞는가?
  6. migrate reset을 운영 DB에서 실행하지 않도록 방지하고 있는가?
  7. 운영 덤프 파일이 Git에 올라가지 않도록 .gitignore에 포함되어 있는가?
  8. DB 초기화 절차가 문서화되어 있는가?

➕ 27-3. 리소스 관리 체크리스트

  1. 안 쓰는 컨테이너를 중지했는가?
  2. docker system df로 용량을 확인했는가?
  3. 볼륨 삭제 전 데이터 필요 여부를 확인했는가?
  4. 여러 프로젝트 포트를 정리했는가?
  5. OrbStack이 불필요하게 많은 리소스를 쓰고 있지 않은가?
  6. 프로젝트별 start/stop script가 있는가?
  7. 새 Mac 세팅 시 compose만으로 인프라 복구가 가능한가?
  8. README에 로컬 실행 순서가 정리되어 있는가?

📌 요약

  • Docker는 애플리케이션 실행 환경을 컨테이너로 묶어 로컬 개발, 테스트, 배포 환경을 더 일관되게 만드는 도구입니다.
  • OrbStack은 Mac에서 Docker 컨테이너를 가볍게 실행하기 위한 Docker Desktop 대안으로 볼 수 있으며, 명령어는 대부분 docker, docker compose를 그대로 사용합니다.
  • 로컬 개발에서는 처음부터 백엔드/프론트까지 전부 Docker에 넣기보다, PostgreSQL과 Redis 같은 인프라만 컨테이너로 두고 앱은 로컬 Node로 실행하는 방식이 현실적입니다.
  • 백엔드가 Mac에서 실행되면 DB host는 localhost, 백엔드도 컨테이너 안에서 실행되면 DB host는 compose service name인 postgres를 사용합니다.
  • PostgreSQL 데이터는 volume에 저장되므로 docker compose down은 데이터가 유지되지만, docker compose down -v는 DB 데이터까지 삭제할 수 있어 조심해야 합니다.
  • Prisma를 사용할 때는 DB 컨테이너 실행, DATABASE_URL, SHADOW_DATABASE_URL, migration 상태, seed 최신 여부를 함께 확인해야 합니다.
  • 여러 프로젝트를 동시에 다룰 때는 포트 충돌을 피하기 위해 프로젝트별 포트와 volume 이름을 명확히 나눠야 합니다.
  • 운영 DB와 로컬 DB를 헷갈리는 것은 매우 위험하므로 .env.local, .env.production, AWS profile, DB 이름, reset 명령어 사용 기준을 확실히 분리해야 합니다.
  • Docker/DB 문제를 AI에게 물어볼 때는 컨테이너 상태, compose 파일, DATABASE_URL, 실행 위치, 에러 메시지를 함께 제공해야 정확한 원인 분석이 가능합니다.
  • 1인 개발자에게 중요한 것은 거창한 컨테이너 운영이 아니라, 새 Mac에서도 docker compose up -d → migrate → seed → npm run dev로 재현 가능한 안정적인 로컬 인프라 구조를 만드는 것입니다.
profile
juni
이전 포스트

TIL - 20260801

다음 포스트

TIL - 20260804

0개의 댓글