wing-ops/docs/INSTALL_GUIDE.md

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. 의존성 설치

# 프론트엔드
cd wing/frontend
npm install

# 백엔드
cd ../backend
npm install

3-2. 데이터베이스 실행 (Docker)

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. 백엔드 실행

cd wing/backend
npm run dev

→ http://localhost:3001 에서 API 서버 시작

3-4. 프론트엔드 실행

cd wing/frontend
npm run dev

→ http://localhost:5173 에서 웹 앱 시작

---

4. 오프라인 설치 (폐쇄망/다른 망)

인터넷이 안 되는 환경에서는 npm install이 불가능합니다. 이 경우 node_modules 포함 압축 파일을 사용하세요.

4-1. 압축 해제

# 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에서 내보내기:

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에서 불러오기:

docker load -i wing_docker_images.tar
docker compose up -d

Docker 없이도 PostgreSQL을 직접 설치하여 database/database_init.sql을 실행하면 됩니다.

4-4. 실행

node_modules가 이미 포함되어 있으므로 바로 실행 가능합니다.

# 터미널 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. 주요 명령어

# 프론트엔드 빌드 (배포용)
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 포함 압축본 사용