Windows 환경에서 Next.js + FastAPI + PostgreSQL(Docker) 로컬 개발환경 구축

작성자:

개발을 시작하기 전, 로컬 개발환경(Local Development Environment)을 구성하기 위한 가이드 입니다.
이번 포스팅에서는 Windows 환경을 기반으로 VS Code, Git, Next.js, FastAPI, PostgreSQL을 Docker 로 연결해 완전한 로컬 개발환경을 구축하는 과정을 단계별로 안내합니다.

🧭 전체 구성 개요

  • 운영체제: Windows 11
  • 개발툴: Visual Studio Code
  • 형상관리: Git
  • 프론트엔드: Next.js 15.5.4 (React 18.3.1)
  • 백엔드: FastAPI 0.118.2
  • 데이터베이스: PostgreSQL 15.14 (Docker 기반)

이 모든 환경을 구성하면, 하나의 PC에서 프론트엔드/백엔드/DB를 독립적으로 실행하고, 효율적인 개발 및 테스트가 가능합니다.

프론트엔드와 백엔드를 Docker에 연동하지 않은 이유는 초기 개발단계에서 빠르게 컴파일하고 변경된 결과를 확인하기 위해서 입니다.

1️⃣ Git 설치 및 설정

Git 다운로드

  • 공식 페이지: https://git-scm.com/download/win
  • “64-bit Git for Windows Setup” 파일을 다운로드하여 실행합니다.
  • 설치 과정 중 기본값을 그대로 두고 “Next”를 계속 클릭해도 무방합니다.

설치 확인

설치가 완료되면 명령 프롬프트(cmd) 또는 VS Code 터미널을 열어 다음 명령어를 입력합니다.

git --version
// 결과 예시

C:\>git --version
git version 2.51.0.windows.2

사용자 정보 등록

Git 커밋 시 필요한 사용자 정보를 등록합니다.

git config --global user.name "홍길동"
git config --global user.email "hong@example.com"

2️⃣ VS Code 설치

다운로드 링크

3️⃣ Docker Desktop 설치

다운로드 링크

설치 확인

터미널에서 다음 명령어를 실행하세요.

docker --version
docker compose version
// 결과 예시

C:\>docker --version
Docker version 28.4.0, build d8eb465

C:\>docker compose version
Docker Compose version v2.39.4-desktop.1

정상적으로 버전이 표시되면 Docker Desktop이 올바르게 동작 중입니다.

4️⃣ PostgreSQL 설치 (Docker 기반)

docker-compose.yml 파일 생성

Docker를 이용해 PostgreSQL을 컨테이너로 실행합니다.
VS Code 프로젝트 루트 경로에 docker-compose.yml 파일을 생성하세요.

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

실행 명령어

docker compose up -d

“3”에서 설치한 Docker Desktop이 실행된 상태에서 명령어를 실행해야 합니다.
만약 Docker Desktop이 실행되지 않은 상태에서 명령어를 실행하면 아래와 같이 에러가 발생 합니다.

unable to get image 'postgres:15': error during connect: Get "http://%2F%2F.%2Fpipe%2FdockerDesktopLinuxEngine/v1.51/images/postgres:15/json": open //./pipe/dockerDesktopLinuxEngine: The system cannot find the file specified.

실행 확인 명령어

docker ps

5️⃣ Python & FastAPI 설치

Python 다운로드

설치 확인:

python --version

가상환경 생성

python -m venv .venv
.\.venv\Scripts\activate

FastAPI 및 필수 패키지 설치

pip install fastapi==0.118.2 uvicorn[standard] sqlalchemy alembic psycopg[binary] python-dotenv

FastAPI 기본 코드 작성

app/main.py

from fastapi import FastAPI

app = FastAPI()

@app.get("/health")
def health():
    return {"status": "ok"}

서버 실행

uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

→ 브라우저에서 http://localhost:8000/health 접속 시 { "status": "ok" } 응답 확인

6️⃣ Node.js & Next.js 설치

Node.js 다운로드

설치 확인:

node -v
npm -v

Next.js 프로젝트 생성

npx create-next-app@15.5.4 frontend
cd frontend
npm install react@18.3.1 react-dom@18.3.1

개발 서버 실행

npm run dev

브라우저에서 http://localhost:3000 으로 접근

추가 컴포넌트 설치

@mantine/core (v8.3.5)

Mantine은 React 기반의 UI 컴포넌트 라이브러리로, 다양한 스타일링 옵션과 반응형 디자인을 제공합니다. @mantine/core는 Mantine의 핵심 컴포넌트를 포함하고 있습니다.

설치명령어:

npm install @mantine/core@8.3.5

@mantine/dates (v8.3.5)

Mantine의 날짜 및 시간 선택 컴포넌트를 제공합니다. DatePicker, DateTimePicker 등과 같은 컴포넌트를 사용하여 날짜 입력 기능을 쉽게 구현할 수 있습니다.

설치 명령어:

npm install @mantine/dates@8.3.5

@mantine/hooks (v8.3.5)

Mantine에서 제공하는 유용한 React 훅 모음입니다. 상태 관리, 이벤트 처리, 브라우저 기능 활용 등 다양한 기능을 제공합니다.

설치 명령어:

npm install @mantine/hooks@8.3.5

@mantine/notifications (v8.3.5)

알림(Notification) 컴포넌트를 제공하여 사용자에게 메시지를 표시할 수 있습니다. 성공, 경고, 오류 등의 알림을 쉽게 구현할 수 있습니다.

설치 명령어:

npm install @mantine/notifications@8.3.5

@types/axios (v0.9.36)

TypeScript 프로젝트에서 Axios를 사용할 때 타입 정의를 제공합니다. Axios와 함께 사용하여 더 안전한 네트워크 요청 코드를 작성할 수 있습니다.

설치 명령어:

npm install @types/axios@0.9.36

axios (v1.12.2)

Axios는 HTTP 클라이언트 라이브러리로, API 요청을 간단하게 처리할 수 있습니다. GET, POST, PUT, DELETE 등 다양한 HTTP 메서드를 지원합니다.

설치 명령어:

npm install axios@1.12.2

✅ 마무리 요약

이제 다음 환경이 모두 구축되었습니다.

구성 요소버전역할
Git최신형상관리
VS Code최신통합 개발툴
Node.js20+프론트엔드 빌드
Next.js15.5.4React 기반 FE 프레임워크
FastAPI0.118.2백엔드 API 서버
PostgreSQL15.14데이터베이스
Docker최신컨테이너 환경

댓글 남기기