190 lines
5.0 KiB
Markdown
190 lines
5.0 KiB
Markdown
# 10 Minute Planner
|
|
|
|
Vue 3 + TailwindCSS + Fastify + PostgreSQL 기반의 `10분 플래너 다이어리` 프로젝트다.
|
|
|
|
## 시작 전에
|
|
|
|
이 프로젝트는 `Docker`와 `Docker Compose`가 설치된 환경을 기준으로 실행한다.
|
|
|
|
NAS나 서버에서 처음 올리는 경우 흐름은 아래처럼 생각하면 된다.
|
|
|
|
1. 프로젝트를 받을 폴더로 이동한다.
|
|
2. `git clone`으로 저장소를 내려받는다.
|
|
3. 내려받은 프로젝트 폴더로 들어간다.
|
|
4. `docker compose`로 컨테이너를 빌드하고 실행한다.
|
|
|
|
예시:
|
|
|
|
```bash
|
|
cd /volume1/docker
|
|
git clone https://git.sori.studio/zenn/planner.sori.studio.git .
|
|
cd planner.sori.studio
|
|
cp .env.example .env
|
|
docker compose up -d --build
|
|
```
|
|
|
|
처음 한 번은 이미지 빌드 때문에 시간이 걸릴 수 있다.
|
|
실행 전에 `.env`의 DB와 관리자 계정 환경변수는 운영자만 아는 값으로 반드시 바꾼다.
|
|
|
|
## 초보자용 빠른 실행
|
|
|
|
### 1. 프로젝트 받기
|
|
|
|
원하는 작업 폴더로 이동한 뒤 저장소를 내려받는다.
|
|
|
|
```bash
|
|
cd /원하는/폴더
|
|
git clone https://git.sori.studio/zenn/planner.sori.studio.git
|
|
cd planner.sori.studio
|
|
```
|
|
|
|
### 2. 배포용으로 바로 실행하기
|
|
|
|
실제 동작 확인이나 NAS 상시 실행은 아래 명령으로 시작한다.
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
# .env에서 POSTGRES_*, DATABASE_URL, ADMIN_ACCOUNT_* 값을 비공개 운영 값으로 수정한다.
|
|
docker compose up -d --build
|
|
```
|
|
|
|
의미:
|
|
|
|
- `up`: 컨테이너를 실행한다.
|
|
- `-d`: 백그라운드에서 실행한다.
|
|
- `--build`: 이미지가 없거나 코드가 바뀌었을 때 다시 빌드한다.
|
|
|
|
브라우저 접속 주소:
|
|
|
|
- 프론트엔드: `http://NAS주소:48081`
|
|
- PostgreSQL: `NAS주소:45432`
|
|
|
|
관리자 계정은 백엔드 시작 시 `.env`의 `ADMIN_ACCOUNT_*` 값으로 자동 생성된다.
|
|
관리자 아이디와 비밀번호는 저장소 문서에 적지 말고, 운영자만 접근 가능한 비공개 환경변수 파일에서 관리한다.
|
|
일반 사용자는 회원가입 후 이메일 인증을 완료해야 로그인할 수 있다.
|
|
운영 서버에서는 비밀번호 재설정/이메일 인증용 미리보기 링크가 API 응답에 노출되지 않도록 유지한다.
|
|
|
|
현재 `docker-compose.yml` 기준 내부 구성:
|
|
|
|
- 프론트엔드 nginx
|
|
- 백엔드 Fastify
|
|
- PostgreSQL
|
|
- 배포/개발 컨테이너 시간대: `Asia/Seoul`
|
|
|
|
### 3. 실행 상태 확인하기
|
|
|
|
```bash
|
|
docker compose ps
|
|
```
|
|
|
|
로그를 보고 싶으면:
|
|
|
|
```bash
|
|
docker compose logs -f
|
|
```
|
|
|
|
특정 서비스만 보고 싶으면:
|
|
|
|
```bash
|
|
docker compose logs -f frontend
|
|
docker compose logs -f backend
|
|
docker compose logs -f postgres
|
|
```
|
|
|
|
### 4. 종료하기
|
|
|
|
```bash
|
|
docker compose down
|
|
```
|
|
|
|
데이터베이스 볼륨까지 완전히 지우고 처음부터 다시 시작하고 싶을 때만 아래 명령을 사용한다.
|
|
|
|
```bash
|
|
docker compose down -v
|
|
```
|
|
|
|
주의:
|
|
|
|
- `-v`는 PostgreSQL 데이터까지 지울 수 있으니 정말 초기화가 필요할 때만 사용한다.
|
|
|
|
### 5. 코드 수정 후 다시 반영하기
|
|
|
|
배포용 compose는 코드가 자동 반영되지 않는다.
|
|
|
|
코드를 수정했다면 프로젝트 폴더 안에서 다시 실행한다.
|
|
|
|
```bash
|
|
docker compose up -d --build
|
|
```
|
|
|
|
즉, NAS에서 배포용으로 돌릴 때는 보통 아래 순서를 반복한다.
|
|
|
|
```bash
|
|
cd /volume1/docker/planner.sori.studio
|
|
git pull
|
|
docker compose up -d --build
|
|
```
|
|
|
|
## 실행 방법
|
|
|
|
### 개발용
|
|
|
|
코드를 수정하면서 자동 새로고침까지 보려면 개발용 compose를 사용한다.
|
|
|
|
```bash
|
|
docker compose -f docker-compose.dev.yml up
|
|
```
|
|
|
|
개발용도 처음 시작할 때는 아래처럼 프로젝트 폴더 안에서 실행하면 된다.
|
|
|
|
```bash
|
|
cd /원하는/폴더
|
|
git clone https://git.sori.studio/zenn/planner.sori.studio.git
|
|
cd planner.sori.studio
|
|
docker compose -f docker-compose.dev.yml up
|
|
```
|
|
|
|
개발용 포트:
|
|
|
|
- 프론트엔드: `http://localhost:5173`
|
|
- 백엔드 API: `http://localhost:3001`
|
|
- PostgreSQL: `localhost:5432`
|
|
|
|
개발용 특징:
|
|
|
|
- 프론트는 Vite HMR로 저장 즉시 화면이 반영된다.
|
|
- 백엔드는 `node --watch`로 파일 변경 시 자동 재시작된다.
|
|
- 즉, 개발 중에는 매번 새로 빌드할 필요 없이 `docker compose -f docker-compose.dev.yml up`만 켜두면 된다.
|
|
|
|
### 배포용
|
|
|
|
실서비스나 최종 확인용으로는 배포용 compose를 사용한다.
|
|
|
|
```bash
|
|
docker compose up -d --build
|
|
```
|
|
|
|
배포용 포트:
|
|
|
|
- 프론트엔드: `http://localhost:48081`
|
|
- PostgreSQL: `localhost:45432`
|
|
|
|
배포용 특징:
|
|
|
|
- 프론트는 빌드 결과물을 nginx로 서빙한다.
|
|
- 브라우저에서는 `/api` 경로로 백엔드에 접근한다.
|
|
- 수정 사항 반영 시에는 다시 빌드가 필요하다.
|
|
|
|
## 문서
|
|
|
|
- 작업 규칙: [`AGENTS.md`](./AGENTS.md)
|
|
- 진행 상태 / 체크리스트: [`TODO.md`](./TODO.md)
|
|
- 인수인계 메모: [`HANDOFF.md`](./HANDOFF.md)
|
|
|
|
## 현재 방향
|
|
|
|
- 기본 UX는 `1페이지 + 우측 정보 패널`
|
|
- 보조 모드는 `2페이지 펼침 보기`
|
|
- 스타일링은 Vue + TailwindCSS
|
|
- 장기적으로는 Docker 기반으로 UGREEN NAS 배포 예정
|