프로젝트 기본 구성: Next.js + PostgreSQL + Gitea Actions 배포

- Next.js 15 (App Router, TypeScript, Tailwind), pg 커넥션 풀
- /api/health DB 헬스체크, standalone Dockerfile
- Gitea Actions: 빌드 → 컨테이너 교체 → Traefik(jskim.vexplor.com) 라우팅
- 로컬 개발용 SSH DB 터널 스크립트 (scripts/db-tunnel.sh)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

.gitea/workflows/build-and-deploy.yml

@@ -0,0 +1,62 @@
+# Gitea Actions — 빌드 & 배포
+#
+# 동작:
+#   1. main 브랜치 push 시 자동 실행
+#   2. 러너가 호스트 docker 데몬으로 이미지 빌드 (레지스트리 불필요)
+#   3. 같은 호스트에서 컨테이너 교체 → Traefik이 jskim.vexplor.com HTTPS 라우팅
+#
+# DATABASE_URL은 서버의 /home/three/jskim/.env (chmod 600)에서 읽는다.
+# 저장소에는 어떤 비밀값도 커밋하지 않는다.
+
+name: build-and-deploy
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+env:
+  IMAGE: harbor.wace.me/dev-pilots/jskim:latest
+  CONTAINER_NAME: jskim
+  DOMAIN: jskim.vexplor.com
+  HOST_ENV_DIR: /home/three/jskim
+
+jobs:
+  deploy:
+    runs-on: ubuntu-24.04
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: docker CLI 준비
+        run: command -v docker || (apt-get update -qq && apt-get install -y -qq docker.io)
+
+      - name: 이미지 빌드
+        run: docker build -t "$IMAGE" .
+
+      - name: 컨테이너 교체
+        run: |
+          # 호스트의 env 파일을 호스트 docker 데몬 경유로 읽는다 (러너 컨테이너에는 미마운트)
+          DATABASE_URL=$(docker run --rm -v "$HOST_ENV_DIR":/cfg:ro alpine sh -c 'grep "^DATABASE_URL=" /cfg/.env | cut -d= -f2-')
+          if [ -z "$DATABASE_URL" ]; then echo "호스트 $HOST_ENV_DIR/.env 에 DATABASE_URL 없음"; exit 1; fi
+          docker rm -f "$CONTAINER_NAME" 2>/dev/null || true
+          docker run -d \
+            --name "$CONTAINER_NAME" \
+            --restart always \
+            --network web \
+            -e TZ=Asia/Seoul \
+            -e DATABASE_URL="$DATABASE_URL" \
+            --label "traefik.enable=true" \
+            --label "traefik.docker.network=web" \
+            --label "traefik.http.routers.jskim.rule=Host(\`$DOMAIN\`)" \
+            --label "traefik.http.routers.jskim.entrypoints=websecure" \
+            --label "traefik.http.routers.jskim.tls.certresolver=le" \
+            --label "traefik.http.services.jskim.loadbalancer.server.port=3000" \
+            "$IMAGE"
+          docker network connect pgnet "$CONTAINER_NAME"
+
+      - name: 헬스체크
+        run: |
+          sleep 10
+          docker exec "$CONTAINER_NAME" wget -qO- http://localhost:3000/api/health || (docker logs --tail 50 "$CONTAINER_NAME"; exit 1)

.gitignore

@@ -0,0 +1,41 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/versions
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# env files (can opt-in for committing if needed)
+.env*
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts

AGENTS.md

@@ -0,0 +1,9 @@
+<!-- BEGIN:nextjs-agent-rules -->
+
+# This is NOT the Next.js you know
+
+This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` (resolved from this file's directory; in monorepos the `next` package may not be visible from the repo root) before writing any code. Heed deprecation notices.
+
+This block is written and re-added by `next dev` — verify at `node_modules/next/dist/server/lib/generate-agent-files.js`. Removing it from a diff only re-creates the uncommitted change; committing it with your work keeps the tree clean.
+
+<!-- END:nextjs-agent-rules -->

CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

Dockerfile

@@ -0,0 +1,28 @@
+# --- 빌드 스테이지 ---
+FROM node:20-alpine AS builder
+WORKDIR /app
+
+COPY package.json package-lock.json ./
+RUN npm ci
+
+COPY . .
+RUN npm run build
+
+# --- 실행 스테이지 (standalone) ---
+FROM node:20-alpine AS runner
+WORKDIR /app
+
+ENV NODE_ENV=production
+ENV PORT=3000
+ENV HOSTNAME=0.0.0.0
+
+RUN addgroup -S nodejs && adduser -S nextjs -G nodejs
+
+COPY --from=builder /app/.next/standalone ./
+COPY --from=builder /app/.next/static ./.next/static
+COPY --from=builder /app/public ./public
+
+USER nextjs
+EXPOSE 3000
+
+CMD ["node", "server.js"]

README.md

@@ -0,0 +1,46 @@
+# jskim.vexplor.com
+
+Next.js(App Router, TypeScript) + PostgreSQL 개인 프로젝트.
+
+## 스택
+
+- **프론트/백엔드**: Next.js 15 (React 19, API Routes로 Node.js 백엔드 겸용)
+- **DB**: PostgreSQL 17 — THREEDEV 서버(211.115.91.140) `pg-jskim` 컨테이너, DB/계정 `jskim`
+- **배포**: Gitea Actions → Harbor(`harbor.wace.me/dev-pilots/jskim`) → Docker + Traefik(HTTPS, `jskim.vexplor.com`)
+
+## 로컬 개발
+
+DB가 방화벽 뒤에 있어 SSH 터널이 필요하다.
+
+```bash
+# 터미널 1: DB 터널 (localhost:5436 -> pg-jskim)
+./scripts/db-tunnel.sh
+
+# 터미널 2: 개발 서버
+npm run dev
+```
+
+- 환경변수: `.env.local` (gitignore 대상, `.env.example` 참고)
+- DB 연결 확인: http://localhost:3000/api/health
+
+## 배포
+
+`main` 브랜치에 push하면 Gitea Actions(`.gitea/workflows/build-and-deploy.yml`)가 자동으로:
+
+1. 서버(THREEDEV)에서 Docker 이미지 빌드 (레지스트리 불필요)
+2. 컨테이너 교체 (`web` + `pgnet` 네트워크, Traefik 라벨)
+3. `/api/health` 헬스체크
+
+운영 `DATABASE_URL`은 서버의 `/home/three/jskim/.env`(chmod 600)에서 읽는다.
+
+## 구조
+
+```
+src/
+  app/              # App Router 페이지
+    api/health/     # DB 연결 헬스체크
+  lib/db.ts         # pg Pool (DATABASE_URL 사용)
+scripts/db-tunnel.sh
+Dockerfile          # standalone 빌드, node:20-alpine
+.gitea/workflows/   # CI/CD
+```

eslint.config.mjs

@@ -0,0 +1,18 @@
+import { defineConfig, globalIgnores } from "eslint/config";
+import nextVitals from "eslint-config-next/core-web-vitals";
+import nextTs from "eslint-config-next/typescript";
+
+const eslintConfig = defineConfig([
+  ...nextVitals,
+  ...nextTs,
+  // Override default ignores of eslint-config-next.
+  globalIgnores([
+    // Default ignores of eslint-config-next:
+    ".next/**",
+    "out/**",
+    "build/**",
+    "next-env.d.ts",
+  ]),
+]);
+
+export default eslintConfig;

next.config.ts

@@ -0,0 +1,7 @@
+import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {
+  output: "standalone",
+};
+
+export default nextConfig;

package.json

@@ -0,0 +1,28 @@
+{
+  "name": "project",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start",
+    "lint": "eslint"
+  },
+  "dependencies": {
+    "next": "16.3.0",
+    "pg": "^8.23.0",
+    "react": "19.2.8",
+    "react-dom": "19.2.8"
+  },
+  "devDependencies": {
+    "@tailwindcss/postcss": "^4",
+    "@types/node": "^20",
+    "@types/pg": "^8.21.0",
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "eslint": "^9",
+    "eslint-config-next": "16.3.0",
+    "tailwindcss": "^4",
+    "typescript": "^5"
+  }
+}

postcss.config.mjs

@@ -0,0 +1,7 @@
+const config = {
+  plugins: {
+    "@tailwindcss/postcss": {},
+  },
+};
+
+export default config;

public/file.svg

@@ -0,0 +1 @@
+<svg fill="none" viewBox="0 0 16 16" xmlns="http://www.w3.org/2000/svg"><path d="M14.5 13.5V5.41a1 1 0 0 0-.3-.7L9.8.29A1 1 0 0 0 9.08 0H1.5v13.5A2.5 2.5 0 0 0 4 16h8a2.5 2.5 0 0 0 2.5-2.5m-1.5 0v-7H8v-5H3v12a1 1 0 0 0 1 1h8a1 1 0 0 0 1-1M9.5 5V2.12L12.38 5zM5.13 5h-.62v1.25h2.12V5zm-.62 3h7.12v1.25H4.5zm.62 3h-.62v1.25h7.12V11z" clip-rule="evenodd" fill="#666" fill-rule="evenodd"/></svg>

public/globe.svg

@@ -0,0 +1 @@
+<svg fill="none" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16"><g clip-path="url(#a)"><path fill-rule="evenodd" clip-rule="evenodd" d="M10.27 14.1a6.5 6.5 0 0 0 3.67-3.45q-1.24.21-2.7.34-.31 1.83-.97 3.1M8 16A8 8 0 1 0 8 0a8 8 0 0 0 0 16m.48-1.52a7 7 0 0 1-.96 0H7.5a4 4 0 0 1-.84-1.32q-.38-.89-.63-2.08a40 40 0 0 0 3.92 0q-.25 1.2-.63 2.08a4 4 0 0 1-.84 1.31zm2.94-4.76q1.66-.15 2.95-.43a7 7 0 0 0 0-2.58q-1.3-.27-2.95-.43a18 18 0 0 1 0 3.44m-1.27-3.54a17 17 0 0 1 0 3.64 39 39 0 0 1-4.3 0 17 17 0 0 1 0-3.64 39 39 0 0 1 4.3 0m1.1-1.17q1.45.13 2.69.34a6.5 6.5 0 0 0-3.67-3.44q.65 1.26.98 3.1M8.48 1.5l.01.02q.41.37.84 1.31.38.89.63 2.08a40 40 0 0 0-3.92 0q.25-1.2.63-2.08a4 4 0 0 1 .85-1.32 7 7 0 0 1 .96 0m-2.75.4a6.5 6.5 0 0 0-3.67 3.44 29 29 0 0 1 2.7-.34q.31-1.83.97-3.1M4.58 6.28q-1.66.16-2.95.43a7 7 0 0 0 0 2.58q1.3.27 2.95.43a18 18 0 0 1 0-3.44m.17 4.71q-1.45-.12-2.69-.34a6.5 6.5 0 0 0 3.67 3.44q-.65-1.27-.98-3.1" fill="#666"/></g><defs><clipPath id="a"><path fill="#fff" d="M0 0h16v16H0z"/></clipPath></defs></svg>

public/next.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 394 80"><path fill="#000" d="M262 0h68.5v12.7h-27.2v66.6h-13.6V12.7H262V0ZM149 0v12.7H94v20.4h44.3v12.6H94v21h55v12.6H80.5V0h68.7zm34.3 0h-17.8l63.8 79.4h17.9l-32-39.7 32-39.6h-17.9l-23 28.6-23-28.6zm18.3 56.7-9-11-27.1 33.7h17.8l18.3-22.7z"/><path fill="#000" d="M81 79.3 17 0H0v79.3h13.6V17l50.2 62.3H81Zm252.6-.4c-1 0-1.8-.4-2.5-1s-1.1-1.6-1.1-2.6.3-1.8 1-2.5 1.6-1 2.6-1 1.8.3 2.5 1a3.4 3.4 0 0 1 .6 4.3 3.7 3.7 0 0 1-3 1.8zm23.2-33.5h6v23.3c0 2.1-.4 4-1.3 5.5a9.1 9.1 0 0 1-3.8 3.5c-1.6.8-3.5 1.3-5.7 1.3-2 0-3.7-.4-5.3-1s-2.8-1.8-3.7-3.2c-.9-1.3-1.4-3-1.4-5h6c.1.8.3 1.6.7 2.2s1 1.2 1.6 1.5c.7.4 1.5.5 2.4.5 1 0 1.8-.2 2.4-.6a4 4 0 0 0 1.6-1.8c.3-.8.5-1.8.5-3V45.5zm30.9 9.1a4.4 4.4 0 0 0-2-3.3 7.5 7.5 0 0 0-4.3-1.1c-1.3 0-2.4.2-3.3.5-.9.4-1.6 1-2 1.6a3.5 3.5 0 0 0-.3 4c.3.5.7.9 1.3 1.2l1.8 1 2 .5 3.2.8c1.3.3 2.5.7 3.7 1.2a13 13 0 0 1 3.2 1.8 8.1 8.1 0 0 1 3 6.5c0 2-.5 3.7-1.5 5.1a10 10 0 0 1-4.4 3.5c-1.8.8-4.1 1.2-6.8 1.2-2.6 0-4.9-.4-6.8-1.2-2-.8-3.4-2-4.5-3.5a10 10 0 0 1-1.7-5.6h6a5 5 0 0 0 3.5 4.6c1 .4 2.2.6 3.4.6 1.3 0 2.5-.2 3.5-.6 1-.4 1.8-1 2.4-1.7a4 4 0 0 0 .8-2.4c0-.9-.2-1.6-.7-2.2a11 11 0 0 0-2.1-1.4l-3.2-1-3.8-1c-2.8-.7-5-1.7-6.6-3.2a7.2 7.2 0 0 1-2.4-5.7 8 8 0 0 1 1.7-5 10 10 0 0 1 4.3-3.5c2-.8 4-1.2 6.4-1.2 2.3 0 4.4.4 6.2 1.2 1.8.8 3.2 2 4.3 3.4 1 1.4 1.5 3 1.5 5h-5.8z"/></svg>

public/vercel.svg

@@ -0,0 +1 @@
+<svg fill="none" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1155 1000"><path d="m577.3 0 577.4 1000H0z" fill="#fff"/></svg>

public/window.svg

@@ -0,0 +1 @@
+<svg fill="none" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16"><path fill-rule="evenodd" clip-rule="evenodd" d="M1.5 2.5h13v10a1 1 0 0 1-1 1h-11a1 1 0 0 1-1-1zM0 1h16v11.5a2.5 2.5 0 0 1-2.5 2.5h-11A2.5 2.5 0 0 1 0 12.5zm3.75 4.5a.75.75 0 1 0 0-1.5.75.75 0 0 0 0 1.5M7 4.75a.75.75 0 1 1-1.5 0 .75.75 0 0 1 1.5 0m1.75.75a.75.75 0 1 0 0-1.5.75.75 0 0 0 0 1.5" fill="#666"/></svg>

scripts/db-tunnel.sh

@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+# THREEDEV 서버의 pg-jskim(5436)으로 SSH 터널을 연다.
+# DB는 방화벽으로 외부 직접 접속이 막혀 있어 로컬 개발 시 이 터널이 필요함.
+# 자격증명은 ~/.claude/.env.secrets 의 THREEDEV_SSH_* 변수를 사용한다.
+set -euo pipefail
+
+source ~/.claude/.env.secrets
+
+echo "SSH 터널 시작: localhost:5436 -> pg-jskim (${THREEDEV_SSH_HOST})"
+echo "종료하려면 Ctrl+C"
+
+exec sshpass -p "$THREEDEV_SSH_PASS" ssh \
+  -o StrictHostKeyChecking=no \
+  -N \
+  -L 5436:localhost:5436 \
+  -p "$THREEDEV_SSH_PORT" \
+  "$THREEDEV_SSH_USER@$THREEDEV_SSH_HOST"

src/app/api/health/route.ts

@@ -0,0 +1,27 @@
+import { NextResponse } from "next/server";
+import { db } from "@/lib/db";
+
+export const dynamic = "force-dynamic";
+
+export async function GET() {
+  try {
+    const { rows } = await db.query("SELECT now() AS now, version() AS version");
+    return NextResponse.json({
+      status: "ok",
+      db: {
+        connected: true,
+        now: rows[0].now,
+        version: rows[0].version,
+      },
+    });
+  } catch (error) {
+    return NextResponse.json(
+      {
+        status: "error",
+        db: { connected: false },
+        message: error instanceof Error ? error.message : String(error),
+      },
+      { status: 503 },
+    );
+  }
+}

src/app/globals.css

@@ -0,0 +1,26 @@
+@import "tailwindcss";
+
+:root {
+  --background: #ffffff;
+  --foreground: #171717;
+}
+
+@theme inline {
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --font-sans: var(--font-geist-sans);
+  --font-mono: var(--font-geist-mono);
+}
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    --background: #0a0a0a;
+    --foreground: #ededed;
+  }
+}
+
+body {
+  background: var(--background);
+  color: var(--foreground);
+  font-family: Arial, Helvetica, sans-serif;
+}

src/app/layout.tsx

@@ -0,0 +1,29 @@
+import type { Metadata } from "next";
+import { Geist, Geist_Mono } from "next/font/google";
+import "./globals.css";
+
+const geistSans = Geist({
+  variable: "--font-geist-sans",
+  subsets: ["latin"],
+});
+
+const geistMono = Geist_Mono({
+  variable: "--font-geist-mono",
+  subsets: ["latin"],
+});
+
+export const metadata: Metadata = {
+  title: "Create Next App",
+  description: "Generated by create next app",
+};
+
+export default function RootLayout({ children }: LayoutProps<"/">) {
+  return (
+    <html
+      lang="en"
+      className={`${geistSans.variable} ${geistMono.variable} h-full antialiased`}
+    >
+      <body className="min-h-full flex flex-col">{children}</body>
+    </html>
+  );
+}

src/app/page.tsx

@@ -0,0 +1,16 @@
+export default function Home() {
+  return (
+    <main className="flex min-h-screen flex-col items-center justify-center gap-4 p-8">
+      <h1 className="text-4xl font-bold">jskim.vexplor.com</h1>
+      <p className="text-lg text-gray-500 dark:text-gray-400">
+        Next.js + PostgreSQL 프로젝트가 준비되었습니다.
+      </p>
+      <a
+        href="/api/health"
+        className="mt-4 rounded-lg border border-gray-300 px-4 py-2 text-sm hover:bg-gray-100 dark:border-gray-700 dark:hover:bg-gray-800"
+      >
+        DB 연결 상태 확인 → /api/health
+      </a>
+    </main>
+  );
+}

src/lib/db.ts

@@ -0,0 +1,23 @@
+import { Pool } from "pg";
+
+// Next.js 개발 모드의 핫 리로드에서 Pool이 중복 생성되지 않도록 전역에 보관
+const globalForDb = globalThis as unknown as { pgPool?: Pool };
+
+export const db =
+  globalForDb.pgPool ??
+  new Pool({
+    connectionString: process.env.DATABASE_URL,
+    max: 10,
+  });
+
+if (process.env.NODE_ENV !== "production") {
+  globalForDb.pgPool = db;
+}
+
+export async function query<T extends Record<string, unknown>>(
+  text: string,
+  params?: unknown[],
+) {
+  const result = await db.query(text, params);
+  return result.rows as T[];
+}

tsconfig.json

@@ -0,0 +1,34 @@
+{
+  "compilerOptions": {
+    "target": "ES2017",
+    "lib": ["dom", "dom.iterable", "esnext"],
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "bundler",
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "react-jsx",
+    "incremental": true,
+    "plugins": [
+      {
+        "name": "next"
+      }
+    ],
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  },
+  "include": [
+    "next-env.d.ts",
+    "**/*.ts",
+    "**/*.tsx",
+    ".next/types/**/*.ts",
+    ".next/dev/types/**/*.ts",
+    "**/*.mts"
+  ],
+  "exclude": ["node_modules"]
+}