TK-FB-Project/docs/guides/SETUP.md

개발 환경 설정 가이드

TK-FB-Project 로컬 개발 환경 구축 가이드

📋 목차

1. 시스템 요구사항
2. 필수 도구 설치
3. 프로젝트 설정
4. 데이터베이스 설정
5. 애플리케이션 실행
6. 개발 도구
7. 문제 해결

---

시스템 요구사항

최소 사양

• OS: macOS, Linux, Windows 10+
• CPU: 2 Core 이상
• RAM: 4GB 이상
• 디스크: 10GB 이상 여유 공간

권장 사양

• OS: macOS (Apple Silicon) 또는 Ubuntu 22.04 LTS
• CPU: 4 Core 이상
• RAM: 8GB 이상
• 디스크: SSD 20GB 이상

---

필수 도구 설치

1. Node.js & npm

macOS (Homebrew):

# Homebrew 설치 (없는 경우)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Node.js 설치
brew install node@20

# 버전 확인
node --version  # v20.x.x
npm --version   # 10.x.x

Ubuntu/Debian:

# NodeSource repository 추가
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -

# Node.js 설치
sudo apt-get install -y nodejs

# 버전 확인
node --version
npm --version

Windows:

• Node.js 공식 사이트에서 LTS 버전 다운로드 및 설치

2. Git

macOS:

brew install git

Ubuntu/Debian:

sudo apt-get install git

Windows:

• Git for Windows 다운로드

설정:

git config --global user.name "Your Name"
git config --global user.email "your.email@example.com"

3. Docker & Docker Compose

macOS:

# Docker Desktop 설치
brew install --cask docker

# Docker Desktop 실행 후 확인
docker --version
docker-compose --version

Ubuntu/Debian:

# Docker 설치
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# Docker Compose 설치
sudo apt-get install docker-compose-plugin

# 사용자를 docker 그룹에 추가
sudo usermod -aG docker $USER
newgrp docker

# 버전 확인
docker --version
docker compose version

Windows:

• Docker Desktop for Windows 설치

4. MySQL Client (선택사항)

macOS:

brew install mysql-client

Ubuntu/Debian:

sudo apt-get install mysql-client

---

프로젝트 설정

1. 저장소 클론

# HTTPS
git clone https://github.com/your-org/TK-FB-Project.git

# 또는 SSH
git clone git@github.com:your-org/TK-FB-Project.git

# 프로젝트 디렉토리로 이동
cd TK-FB-Project

2. 환경 변수 설정

# .env.example 복사
cp .env.example .env

# .env 파일 편집
nano .env  # 또는 vi, code 등

.env 파일 설정:

# Database
DB_HOST=localhost
DB_PORT=3306
DB_NAME=hyungi
DB_USER=hyungi
DB_PASSWORD=your_secure_password_here
DB_ROOT_PASSWORD=your_root_password_here

# API
API_PORT=20005
NODE_ENV=development

# JWT
JWT_SECRET=your_jwt_secret_key_at_least_32_characters
JWT_REFRESH_SECRET=your_refresh_secret_key_at_least_32_characters

# Email (선택사항)
EMAIL_HOST=smtp.gmail.com
EMAIL_PORT=587
EMAIL_USER=your-email@gmail.com
EMAIL_PASSWORD=your-app-password

# OpenAI (선택사항)
OPENAI_API_KEY=your_openai_api_key

보안 참고:

# 강력한 랜덤 비밀번호 생성
openssl rand -base64 32

# 또는
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

3. 백엔드 의존성 설치

cd api.hyungi.net
npm install

주요 의존성:

• express: 웹 프레임워크
• mysql2: MySQL 드라이버
• jsonwebtoken: JWT 인증
• bcryptjs: 비밀번호 해싱
• cors: CORS 미들웨어
• dotenv: 환경변수 관리

4. 프론트엔드 설정

cd ../web-ui
# 프론트엔드는 Vanilla JS이므로 별도 빌드 불필요

---

데이터베이스 설정

방법 1: Docker Compose (권장)

# 프로젝트 루트에서
cd /path/to/TK-FB-Project

# Docker 컨테이너 시작
docker-compose up -d db

# 로그 확인
docker-compose logs -f db

# MySQL 준비 확인 (약 30초 소요)
docker-compose exec db mysqladmin ping -h localhost

초기 데이터 로드:

# SQL 파일 임포트
docker-compose exec -T db mysql -u hyungi -p hyungi < hyungi.sql

# 비밀번호 입력: .env 파일의 DB_PASSWORD

방법 2: 로컬 MySQL 설치

macOS:

# MySQL 설치
brew install mysql@8.0

# MySQL 시작
brew services start mysql@8.0

# 보안 설정
mysql_secure_installation

Ubuntu/Debian:

# MySQL 설치
sudo apt-get install mysql-server

# MySQL 시작
sudo systemctl start mysql
sudo systemctl enable mysql

# 보안 설정
sudo mysql_secure_installation

데이터베이스 생성:

# MySQL 접속
mysql -u root -p

# SQL 실행
CREATE DATABASE hyungi CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'hyungi'@'localhost' IDENTIFIED BY 'your_password';
GRANT ALL PRIVILEGES ON hyungi.* TO 'hyungi'@'localhost';
FLUSH PRIVILEGES;
EXIT;

# 데이터 임포트
mysql -u hyungi -p hyungi < hyungi.sql

데이터베이스 확인

# Docker 사용 시
docker-compose exec db mysql -u hyungi -p hyungi

# 로컬 MySQL 사용 시
mysql -u hyungi -p hyungi

-- 테이블 확인
SHOW TABLES;

-- 사용자 확인
SELECT * FROM users LIMIT 5;

-- 데이터 확인
SELECT COUNT(*) FROM daily_work_reports;

---

애플리케이션 실행

개발 모드 (Docker Compose)

# 전체 서비스 시작
docker-compose up

# 백그라운드 실행
docker-compose up -d

# 로그 확인
docker-compose logs -f

# 특정 서비스 로그
docker-compose logs -f api
docker-compose logs -f web

# 서비스 중지
docker-compose down

# 볼륨 포함 완전 삭제
docker-compose down -v

개발 모드 (로컬 실행)

터미널 1 - 백엔드:

cd api.hyungi.net

# 개발 모드 (nodemon 사용)
npm run dev

# 또는 일반 실행
npm start

터미널 2 - 프론트엔드:

cd web-ui

# 간단한 HTTP 서버 실행
python3 -m http.server 8080

# 또는 Node.js http-server
npx http-server -p 8080

# 또는 PHP
php -S localhost:8080

접속 확인

• 프론트엔드: http://localhost:8080
• 백엔드 API: http://localhost:20005/api
• 데이터베이스: localhost:3306

API 테스트:

# Health check
curl http://localhost:20005/api/health

# 로그인 테스트
curl -X POST http://localhost:20005/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"your_password"}'

---

개발 도구

1. VSCode 확장 프로그램

필수:

• ESLint
• Prettier - Code formatter
• MySQL (cweijan.vscode-mysql-client2)
• Docker

권장:

• GitLens
• Thunder Client (API 테스트)
• Live Server
• JavaScript (ES6) code snippets

설치:

# VSCode에서
Cmd/Ctrl + Shift + X → 확장 프로그램 검색 및 설치

2. VSCode 설정

.vscode/settings.json:

{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  },
  "javascript.suggest.autoImports": true,
  "javascript.updateImportsOnFileMove.enabled": "always",
  "[javascript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  }
}

3. 디버깅 설정

.vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Launch API Server",
      "skipFiles": ["<node_internals>/**"],
      "program": "${workspaceFolder}/api.hyungi.net/index.js",
      "env": {
        "NODE_ENV": "development"
      }
    }
  ]
}

4. 유용한 명령어

# 패키지 업데이트 확인
npm outdated

# 보안 취약점 확인
npm audit

# 보안 취약점 자동 수정
npm audit fix

# 캐시 정리
npm cache clean --force

# node_modules 재설치
rm -rf node_modules package-lock.json
npm install

---

문제 해결

일반적인 문제

1. Port already in use

증상:

Error: listen EADDRINUSE: address already in use :::20005

해결:

# 포트 사용 중인 프로세스 확인
lsof -i :20005

# 프로세스 종료
kill -9 <PID>

# 또는 다른 포트 사용
# .env 파일에서 API_PORT 변경

2. MySQL 연결 실패

증상:

Error: connect ECONNREFUSED 127.0.0.1:3306

해결:

# Docker 사용 시
docker-compose ps  # db 컨테이너 상태 확인
docker-compose up -d db  # db 재시작

# 로컬 MySQL 사용 시
sudo systemctl status mysql  # 상태 확인
sudo systemctl start mysql   # MySQL 시작

# 연결 테스트
mysql -h localhost -u hyungi -p

3. Permission denied

증상:

Error: EACCES: permission denied

해결:

# Docker 권한 문제
sudo usermod -aG docker $USER
newgrp docker

# 파일 권한 문제
sudo chown -R $USER:$USER /path/to/project

4. Module not found

증상:

Error: Cannot find module 'express'

해결:

# node_modules 재설치
cd api.hyungi.net
rm -rf node_modules package-lock.json
npm install

5. JWT 토큰 오류

증상:

Error: jwt malformed
Error: invalid signature

해결:

# .env 파일 확인
# JWT_SECRET이 올바르게 설정되어 있는지 확인

# 토큰 재발급
# 로그아웃 후 다시 로그인

데이터베이스 문제

MySQL 8.0 호환성

증상:

Error: ER_NOT_SUPPORTED_AUTH_MODE

해결:

-- MySQL 접속
mysql -u root -p

-- 인증 방식 변경
ALTER USER 'hyungi'@'localhost' IDENTIFIED WITH mysql_native_password BY 'your_password';
FLUSH PRIVILEGES;

한글 깨짐

해결:

-- 데이터베이스 문자셋 확인
SHOW VARIABLES LIKE 'character_set%';

-- 테이블 문자셋 변경
ALTER TABLE daily_work_reports CONVERT TO CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

Docker 문제

컨테이너 재시작

# 컨테이너 재시작
docker-compose restart

# 특정 서비스만
docker-compose restart api

# 완전 재빌드
docker-compose down
docker-compose build --no-cache
docker-compose up -d

볼륨 문제

# 볼륨 확인
docker volume ls

# 볼륨 삭제 (주의: 데이터 손실)
docker-compose down -v

# 특정 볼륨만 삭제
docker volume rm tk-fb-project_mysql_data

---

추가 리소스

공식 문서

• Node.js
• Express
• MySQL
• Docker

내부 문서

• 아키텍처 개요
• API 문서
• 코딩 스타일 가이드
• 문제 해결 가이드

커뮤니티

• Node.js GitHub
• Stack Overflow

---

체크리스트

설정 완료 확인:

• Node.js 설치 (v20+)
• Git 설치 및 설정
• Docker 설치 및 실행
• 프로젝트 클론
• .env 파일 생성 및 설정
• npm install 완료
• 데이터베이스 생성 및 데이터 로드
• 백엔드 서버 실행 확인
• 프론트엔드 서버 실행 확인
• API 테스트 성공
• 로그인 성공
• VSCode 확장 프로그램 설치

---

도움이 필요하면: 프로젝트 관리자에게 문의하세요.

마지막 업데이트: 2025-12-11