Next.js, FastAPI, PostgreSQL(DB) 서버 구동 및 종료 방법

작성자:

📘 개요

풀스택 개발 환경에서 프론트엔드(Next.js), 백엔드(FastAPI), 데이터베이스(PostgreSQL)를 각각 구동/종료하고 관리하는 것이 필요합니다.
이번 포스팅에서는 Docker Compose를 사용한 DB(PostgreSQL) 서버, 백엔드(FastAPI) 서버, 프론트엔드(Next.js) 서버를 구동하고 종료하는 방법과 추가로 VS Code를 이용해 프론트엔드와 백엔드 서버를 동시에 실행하는 방법까지 알아보겠습니다.

🧩 참고:
– 개발 초기 단계에서는 코드 수정 후 즉각적인 반영과 디버깅 효율을 높이기 위해, Next.js와 FastAPI를 로컬 환경에서 직접 구동하는 방식으로 설정했습니다.
– Next.js와 FastAPI를 Docker Compose로 통합하여 실행하는 방법은 별도의 포스팅에서 자세히 다룰 예정입니다.

🧰 개발 환경

항목구성
OSWindows 11
IDEVisual Studio Code
형상관리Git
프론트엔드Next.js (v15.5.4) + React (v18.3.1)
백엔드FastAPI (v0.118.2)
데이터베이스PostgreSQL (v15, Docker Compose)
주요 패키지mantine@8.3.5, axios@1.12.2, next-auth@4.24.11, typescript@5.9.3

🐳 1. PostgreSQL (Docker Compose) 서버 구동 및 종료

📂 docker-compose.yml 예시

프로젝트 루트(project-root/)에 아래 내용을 작성합니다:

services:
  db:
    image: postgres:15
    environment:
      POSTGRES_USER: pguser
      POSTGRES_PASSWORD: pgpassword
      POSTGRES_DB: mydb
    ports:
      - "5432:5432"
    volumes:
      - db-data:/var/lib/postgresql/data

volumes:
  db-data:

▶️ DB 서버 실행 (Up)

# 백그라운드로 PostgreSQL 실행
docker compose up -d
  • 컨테이너 이름: project-root-db-1
  • DB 포트: 5432
  • 데이터 볼륨: db-data

실행 확인

docker ps

CONTAINER ID   IMAGE         COMMAND                   CREATED         STATUS         
PORTS                                         NAMES
fc74aabe0b2b   postgres:15   "docker-entrypoint.s…"   9 minutes ago   Up 9 minutes   0.0.0.0:5432->5432/tcp, [::]:5432->5432/tcp   project-root-db-1

DB 접속 테스트

docker exec -it [project-root-db-1] psql -U pguser -d mydb

# project-root-db-1 : docker ps로 확인되는 컨테이너 이름

⏹️ DB 서버 종료 (Down)

# 컨테이너 종료 및 네트워크 정리
docker compose down

⚡ 2. FastAPI (백엔드) 서버 구동 및 종료

📂 예시 디렉터리 구조

project-root/
 ├─ backend/
 │   ├─ main.py
 └─ frontend/

🧩 main.py 예시

from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware

app = FastAPI(title="FastAPI Backend")

origins = ["http://localhost:3000"]

app.add_middleware(
    CORSMiddleware,
    allow_origins=origins,
    allow_credentials=True,
    allow_methods=["*"],
    allow_headers=["*"],
)

@app.get("/")
def read_root():
    return {"message": "Hello from FastAPI!"}

▶️ FastAPI 실행 (Up)

uvicorn backend.main:app --reload --host 0.0.0.0 --port 8000
  • API 서버 주소: http://localhost:8000
  • 자동 리로드(--reload)로 코드 변경 시 즉시 반영됨

⏹️ FastAPI 종료 (Down)

터미널을 종료하거나 Ctrl + C 로 중단합니다.

💡 VS Code 통합 실행(launch.json) 사용 시,
“Stop (■)” 버튼으로 FastAPI와 Next.js를 동시에 중지할 수 있습니다.

🌐 3. Next.js (프론트엔드) 서버 구동 및 종료

📂 명령어

cd frontend
npm install        # 처음 1회만
npm run dev        # 개발 서버 실행

⏹️ Next.js 종료 (Down)

Ctrl + C 로 중단하거나,
VS Code에서 “Stop (■)” 버튼을 클릭합니다.

🧭 4. VS Code로 프론트엔드 + 백엔드 동시 구동하기

🧩 .vscode/launch.json 설정

VS Code에서 .vscode/launch.json 파일을 아래와 같이 작성합니다:

{
  "version": "0.2.0",
  "configurations": [
    // 🚀 [1] Next.js 프론트엔드 디버깅
    {
      "name": "Next.js (Frontend)",
      "type": "node",
      "request": "launch",
      "runtimeExecutable": "npm",
      "runtimeArgs": ["run", "dev"],
      "cwd": "${workspaceFolder}/frontend",
      "port": 9229,
      "env": {
        "NODE_OPTIONS": "--inspect",
        "NEXT_TELEMETRY_DISABLED": "1"
      },
      "console": "integratedTerminal",
      "skipFiles": ["<node_internals>/**"]
    },

    // ⚡ [2] FastAPI 백엔드 디버깅
    {
      "name": "FastAPI (Backend with uvicorn)",
      "type": "debugpy",
      "request": "launch",
      "module": "uvicorn",
      "args": [
        "backend.main:app",
        "--reload",
        "--host", "0.0.0.0",
        "--port", "8000"
      ],
      "cwd": "${workspaceFolder}",
      "env": {
        "PYTHONPATH": "${workspaceFolder}",
        "PYTHONUNBUFFERED": "1"
      },
      "console": "integratedTerminal",
      "justMyCode": true
    },

    // 🌐 [3] Chrome 클라이언트 디버깅
    {
      "name": "Chrome (Frontend UI)",
      "type": "chrome",
      "request": "launch",
      "url": "http://localhost:3000",
      "webRoot": "${workspaceFolder}/frontend",
      "sourceMaps": true
    }
  ],
  "compounds": [
    {
      "name": "🧠 Full Stack Debug (Next + FastAPI + Chrome)",
      "configurations": [
        "FastAPI (Backend with uvicorn)",
        "Next.js (Frontend)",
        "Chrome (Frontend UI)"
      ]
    },
    {
      "name": "⚙️ Backend Only (FastAPI)",
      "configurations": ["FastAPI (Backend with uvicorn)"]
    },
    {
      "name": "💻 Frontend Only (Next.js)",
      "configurations": ["Next.js (Frontend)"]
    }
  ]
}

▶️ 통합 실행 (Up)

  1. VS Code 왼쪽 메뉴 → Run and Debug (Ctrl + Shift + D)
  2. 상단 드롭다운에서 🧠 Full Stack Debug (Next + FastAPI + Chrome) 선택
  3. ▶️ 버튼 클릭

✅ 결과:

⏹️ 통합 종료 (Down)

VS Code 상단의 Stop (■) 버튼 클릭 시,
모든 프로세스(Next.js + FastAPI + Chrome)가 동시에 종료됩니다.

🧾 5. 서버 실행 요약표

구성 요소실행 포트실행 명령종료 방법비고
PostgreSQL (Docker)5432docker compose up -ddocker compose down데이터는 db-data에 유지
FastAPI8000uvicorn main:app --reloadCtrl + C백엔드 API 서버
Next.js3000npm run devCtrl + C프론트엔드 UI
통합 실행 (VS Code)3000 / 8000Full Stack DebugStop (■)프론트+백엔드+브라우저 동시 실행

📌 마무리

이제 하나의 VS Code 프로젝트 내에서

  • PostgreSQL(DB) 서버는 Docker Compose로
  • FastAPI(백엔드)와 Next.js(프론트엔드)는 VS Code 통합 실행으로
    완벽히 제어할 수 있습니다.

🧱 다음 포스팅에서는
Docker Compose를 이용해 Next.js + FastAPI + PostgreSQL 전체를 통합 실행하는 방법
을 단계별로 다룰 예정입니다.

댓글 남기기