htlee
fb556fad9e
- frontend: React 19 + Vite 7 + Leaflet + Tailwind + Zustand - backend: Express + better-sqlite3 + TypeScript - database: PostgreSQL 초기화 스크립트 - .gitignore: 대용량 참고자료(scat, 참고용) 및 바이너리 파일 제외 - .env.example: API 키 템플릿 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
187 lines
4.9 KiB
Markdown
Executable File
187 lines
4.9 KiB
Markdown
Executable File
# WING 해양환경 위기대응 통합시스템 - 설치 매뉴얼
|
|
|
|
## 1. 필수 소프트웨어
|
|
|
|
| 소프트웨어 | 최소 버전 | 용도 | 다운로드 |
|
|
|-----------|----------|------|---------|
|
|
| Node.js | v20 이상 (권장 v25) | 프론트엔드/백엔드 실행 | https://nodejs.org |
|
|
| npm | v10 이상 | 패키지 관리 | Node.js에 포함 |
|
|
| Docker Desktop | v4.0 이상 | PostgreSQL + pgAdmin 실행 | https://www.docker.com/products/docker-desktop |
|
|
|
|
> **오프라인 환경**: 인터넷이 안 되는 망에서는 `node_modules`가 포함된 압축 파일을 사용하세요 (아래 "오프라인 설치" 참고).
|
|
|
|
---
|
|
|
|
## 2. 프로젝트 구조
|
|
|
|
```
|
|
wing/
|
|
├── frontend/ # React + Vite 프론트엔드 (포트 5173)
|
|
│ ├── src/
|
|
│ │ ├── components/ # UI 컴포넌트
|
|
│ │ ├── data/ # 정적 데이터
|
|
│ │ ├── hooks/ # 커스텀 훅
|
|
│ │ ├── types/ # TypeScript 타입 정의
|
|
│ │ ├── utils/ # 유틸리티 함수
|
|
│ │ └── store/ # 상태관리
|
|
│ └── package.json
|
|
├── backend/ # Express 백엔드 API (포트 3001)
|
|
│ ├── src/
|
|
│ │ ├── routes/ # API 라우트
|
|
│ │ ├── middleware/ # 미들웨어 (보안 등)
|
|
│ │ ├── db/ # DB 시드 데이터
|
|
│ │ └── server.ts # 서버 엔트리
|
|
│ └── package.json
|
|
├── database/ # DB 초기화 SQL
|
|
│ ├── database_init.sql
|
|
│ └── init.sql
|
|
├── docker-compose.yml # PostgreSQL + pgAdmin 컨테이너
|
|
└── INSTALL_GUIDE.md # 이 파일
|
|
```
|
|
|
|
---
|
|
|
|
## 3. 온라인 설치 (인터넷 가능한 환경)
|
|
|
|
### 3-1. 의존성 설치
|
|
|
|
```bash
|
|
# 프론트엔드
|
|
cd wing/frontend
|
|
npm install
|
|
|
|
# 백엔드
|
|
cd ../backend
|
|
npm install
|
|
```
|
|
|
|
### 3-2. 데이터베이스 실행 (Docker)
|
|
|
|
```bash
|
|
cd wing
|
|
docker compose up -d
|
|
```
|
|
|
|
실행 확인:
|
|
- PostgreSQL: `localhost:5432` (ID: `wing_admin` / PW: `wing_secure_2026`)
|
|
- pgAdmin: `http://localhost:5050` (ID: `admin@wing.kr` / PW: `admin1234`)
|
|
|
|
### 3-3. 백엔드 실행
|
|
|
|
```bash
|
|
cd wing/backend
|
|
npm run dev
|
|
```
|
|
|
|
→ `http://localhost:3001` 에서 API 서버 시작
|
|
|
|
### 3-4. 프론트엔드 실행
|
|
|
|
```bash
|
|
cd wing/frontend
|
|
npm run dev
|
|
```
|
|
|
|
→ `http://localhost:5173` 에서 웹 앱 시작
|
|
|
|
---
|
|
|
|
## 4. 오프라인 설치 (폐쇄망/다른 망)
|
|
|
|
인터넷이 안 되는 환경에서는 `npm install`이 불가능합니다.
|
|
이 경우 **node_modules 포함 압축 파일**을 사용하세요.
|
|
|
|
### 4-1. 압축 해제
|
|
|
|
```bash
|
|
# wing_full.tar.gz 파일을 작업 폴더에 복사한 뒤:
|
|
tar -xzf wing_full.tar.gz
|
|
```
|
|
|
|
### 4-2. Node.js 설치
|
|
|
|
대상 PC에 Node.js가 없으면 오프라인 설치 파일(.msi 또는 .pkg)을 미리 준비하여 설치합니다.
|
|
|
|
- Windows: `node-v25.x.x-x64.msi`
|
|
- macOS: `node-v25.x.x.pkg`
|
|
|
|
### 4-3. Docker 이미지 (선택)
|
|
|
|
DB를 Docker로 실행하려면 이미지를 미리 저장해서 가져갑니다.
|
|
|
|
**원래 PC에서 내보내기:**
|
|
```bash
|
|
docker pull postgis/postgis:16-3.4
|
|
docker pull dpage/pgadmin4:latest
|
|
docker save postgis/postgis:16-3.4 dpage/pgadmin4:latest -o wing_docker_images.tar
|
|
```
|
|
|
|
**대상 PC에서 불러오기:**
|
|
```bash
|
|
docker load -i wing_docker_images.tar
|
|
docker compose up -d
|
|
```
|
|
|
|
> Docker 없이도 PostgreSQL을 직접 설치하여 `database/database_init.sql`을 실행하면 됩니다.
|
|
|
|
### 4-4. 실행
|
|
|
|
node_modules가 이미 포함되어 있으므로 바로 실행 가능합니다.
|
|
|
|
```bash
|
|
# 터미널 1 - 백엔드
|
|
cd wing/backend
|
|
npm run dev
|
|
|
|
# 터미널 2 - 프론트엔드
|
|
cd wing/frontend
|
|
npm run dev
|
|
```
|
|
|
|
---
|
|
|
|
## 5. 접속 정보 요약
|
|
|
|
| 서비스 | URL | 비고 |
|
|
|--------|-----|------|
|
|
| 프론트엔드 (WING) | http://localhost:5173 | Vite dev server |
|
|
| 백엔드 API | http://localhost:3001 | Express |
|
|
| PostgreSQL | localhost:5432 | DB: `wing`, User: `wing_admin` |
|
|
| pgAdmin | http://localhost:5050 | Email: `admin@wing.kr` |
|
|
|
|
---
|
|
|
|
## 6. 주요 명령어
|
|
|
|
```bash
|
|
# 프론트엔드 빌드 (배포용)
|
|
cd frontend && npm run build # dist/ 폴더에 정적 파일 생성
|
|
|
|
# 백엔드 빌드
|
|
cd backend && npm run build # dist/ 폴더에 JS 생성
|
|
|
|
# DB 시드 데이터 입력
|
|
cd backend && npm run db:seed
|
|
|
|
# TypeScript 타입 체크
|
|
cd frontend && npx tsc --noEmit
|
|
|
|
# Docker 중지
|
|
docker compose down
|
|
|
|
# Docker 데이터 포함 삭제
|
|
docker compose down -v
|
|
```
|
|
|
|
---
|
|
|
|
## 7. 트러블슈팅
|
|
|
|
| 증상 | 해결 |
|
|
|------|------|
|
|
| `npm run dev` 실행 시 포트 충돌 | `lsof -i :5173` 또는 `lsof -i :3001`로 확인 후 프로세스 종료 |
|
|
| `EACCES` 권한 오류 | `sudo chown -R $(whoami) wing/` |
|
|
| Docker 컨테이너 안 뜸 | `docker compose logs` 로 로그 확인 |
|
|
| 프론트엔드에서 API 호출 실패 | 백엔드(`localhost:3001`)가 실행 중인지 확인 |
|
|
| `MODULE_NOT_FOUND` 오류 | `npm install` 재실행 (온라인) 또는 node_modules 포함 압축본 사용 |
|