Docker, Next.js(TypeScript, Tailwind CSS, App Router), Nginx를 활용한 개발 환경 구축⋆ JackerLab

개요

이 가이드는 Docker, Next.js(TypeScript, Tailwind CSS, App Router), 및 Nginx를 사용하여 효율적인 웹 개발 환경을 설정하는 방법을 설명합니다.

Nginx를 리버스 프록시로 활용하며, Next.js 컨테이너는 내부 포트만 사용하고 외부에 노출되지 않도록 설정됩니다.

1. 프로젝트 생성 및 설정

Next.js 애플리케이션 생성

터미널에서 아래 명령어를 실행하여 Next.js 프로젝트를 생성합니다:

npx create-next-app@latest nextjs-app

생성 과정에서 선택해야 하는 값:

√ Would you like to use TypeScript? ... Yes
√ Would you like to use ESLint? ... Yes
√ Would you like to use Tailwind CSS? ... Yes
√ Would you like your code inside a `src/` directory? ... No
√ Would you like to use App Router? (recommended) ... Yes
√ Would you like to use Turbopack for `next dev`? ... Yes
√ Would you like to customize the import alias (`@/*` by default)? ... Yes
√ What import alias would you like configured? ... @/*

디렉토리 구조

프로젝트 생성 후 디렉토리 구조는 아래와 같습니다:

project-root/
├── docker-compose.yml
├── nginx/
│   └── conf.d/
│   │   └── defualt.conf
│   ├── Dockerfile
├── nextjs-app/
│   ├── Dockerfile
│   ├── package.json
│   ├── tsconfig.json
│   ├── tailwind.config.js
│   ├── postcss.config.js
│   ├── next.config.ts
│   ├── app/
│   │   ├── page.tsx
│   └── public/

2. Tailwind CSS 설정 확인

Tailwind CSS는 프로젝트 생성 시 자동으로 구성됩니다.

tailwind.config.js 파일이 다음과 같이 생성됩니다:

import type { Config } from "tailwindcss";

export default {
  content: [
    "./pages/**/*.{js,ts,jsx,tsx,mdx}",
    "./components/**/*.{js,ts,jsx,tsx,mdx}",
    "./app/**/*.{js,ts,jsx,tsx,mdx}",
  ],
  theme: {
    extend: {
      colors: {
        background: "var(--background)",
        foreground: "var(--foreground)",
      },
    },
  },
  plugins: [],
} satisfies Config;

3. Next.js 기본 페이지 작성

app/page.tsx 파일을 작성하여 Tailwind CSS 스타일을 포함한 기본 페이지를 구성합니다:

export default function Home() {
  return (
    <div className="flex items-center justify-center h-screen bg-gray-100">
      <h1 className="text-4xl font-bold text-blue-500">
        Welcome to Next.js (TypeScript + Tailwind CSS) with Docker and Nginx!
      </h1>
    </div>
  );
}

4. Next.js 애플리케이션을 독립 실행형으로 배포 설정

Next.js 애플리케이션을 Docker와 같은 컨테이너 환경에 배포하려면, next.config.js 파일에 output: 'standalone' 옵션을 추가해야 합니다.

이 설정을 통해 Next.js는 애플리케이션을 독립 실행형으로 빌드하여 필요한 모든 파일을 포함한 패키지를 생성합니다.

다음과 같이 next.config.js 파일에 추가합니다:

import type { NextConfig } from "next";

const nextConfig: NextConfig = {
  /* config options here */
  output: 'standalone',  // 독립 실행형 배포를 위한 설정
  /* 다른 설정들 */
};

export default nextConfig;

이 설정을 적용하면 Docker에서 쉽게 배포할 수 있는 독립적인 실행 환경이 구성됩니다.

5. Next.js Dockerfile 작성

nextjs-app/Dockerfile 파일을 작성하여 Next.js 앱의 Docker 이미지를 정의합니다:

FROM node:18-alpine AS base

# Install dependencies only when needed
FROM base AS deps
RUN apk add --no-cache libc6-compat
WORKDIR /app

COPY package.json yarn.lock* package-lock.json* pnpm-lock.yaml* ./
RUN \
  if [ -f yarn.lock ]; then yarn --frozen-lockfile; \
  elif [ -f package-lock.json ]; then npm ci; \
  elif [ -f pnpm-lock.yaml ]; then corepack enable pnpm && pnpm i --frozen-lockfile; \
  else echo "Lockfile not found." && exit 1; \
  fi

FROM base AS builder
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .

RUN \
  if [ -f yarn.lock ]; then yarn run build; \
  elif [ -f package-lock.json ]; then npm run build; \
  elif [ -f pnpm-lock.yaml ]; then corepack enable pnpm && pnpm run build; \
  else echo "Lockfile not found." && exit 1; \
  fi

FROM base AS runner
WORKDIR /app

ENV NODE_ENV=production

RUN addgroup --system --gid 1001 nodejs
RUN adduser --system --uid 1001 nextjs

RUN mkdir .next
RUN chown nextjs:nodejs .next

COPY --from=builder --chown=nextjs:nodejs /app/.next/standalone ./
COPY --from=builder --chown=nextjs:nodejs /app/.next/static ./.next/static

USER nextjs

EXPOSE 3000
ENV PORT=3000

CMD ["node", "server.js"]

6. Nginx 설정 파일 작성

nginx/conf.d/default.conf 파일을 작성하여 Nginx를 리버스 프록시로 설정합니다:

server {
    listen 80;

    location / {
        proxy_pass http://nextjs-app:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

7. Nginx Dockerfile 작성

Docker에서 nginx를 설정할 때, 별도의 volume을 사용하지 않고 직접 설정 파일을 컨테이너에 복사할 수 있습니다.

이를 위해 Dockerfile에서 COPY 명령어를 사용하여 로컬의 conf.d 폴더 내 설정 파일들을 Nginx 컨테이너의 /etc/nginx/conf.d/ 디렉토리로 복사합니다.

다음과 같이 Dockerfile에 설정을 추가합니다:

FROM nginx:latest

RUN rm /etc/nginx/conf.d/default.conf

COPY ./conf.d/ /etc/nginx/conf.d/

이렇게 설정하면 nginx 컨테이너는 ./conf.d/ 폴더 내의 모든 설정 파일을 자동으로 로드하게 됩니다.

이를 통해 Nginx의 설정을 보다 간편하게 관리할 수 있습니다.

8. `docker-compose.yml` 작성

루트 디렉토리에 docker-compose.yml 파일을 작성합니다. 이 파일은 Next.js 및 Nginx 컨테이너를 정의하며, Next.js 포트를 외부에 노출하지 않습니다:

version: '3.8'

services:
  nextjs-app:
    container_name: nextjs-app
    build:
      context: ./nextjs-app/
      dockerfile: Dockerfile
    restart: always
    networks:
      - app-network

  nginx:
    container_name: nginx
    build:
      context: ./nginx/
      dockerfile: Dockerfile
    ports:
      - "80:80"
    depends_on:
      - nextjs-app
    networks:
      - app-network

networks:
  app-network:

9. Docker 환경 실행

Docker 컨테이너를 빌드하고 실행하려면 프로젝트 루트에서 아래 명령어를 실행합니다:

docker-compose up -d --build

10. 애플리케이션 확인

브라우저에서 http://localhost로 이동하여 애플리케이션이 정상적으로 실행되는지 확인합니다.

Tailwind CSS 스타일이 적용된 페이지가 표시됩니다.

최종 결과

이 가이드는 Next.js (TypeScript + Tailwind CSS, App Router)와 Nginx를 활용한 Docker 기반의 개발 환경 설정 방법을 제공합니다.

Next.js 포트는 외부에 노출되지 않으며, Nginx가 요청을 Next.js 컨테이너로 안전하게 전달합니다.

이 설정은 효율적이고 확장 가능한 애플리케이션 개발을 지원합니다. 🎉

참고자료

https://nextjs.org/docs/app/getting-started
https://tailwindcss.com/docs/installation
https://github.com/vercel/next.js
https://github.com/vercel/next.js/blob/canary/examples/with-docker/Dockerfile

개요