planner.sori.studio/README.md

10 Minute Planner

Vue 3 + TailwindCSS + Fastify + PostgreSQL 기반의 10분 플래너 다이어리 프로젝트다.

시작 전에

이 프로젝트는 Docker와 Docker Compose가 설치된 환경을 기준으로 실행한다.

NAS나 서버에서 처음 올리는 경우 흐름은 아래처럼 생각하면 된다.

1. 프로젝트를 받을 폴더로 이동한다.
2. git clone으로 저장소를 내려받는다.
3. 내려받은 프로젝트 폴더로 들어간다.
4. docker compose로 컨테이너를 빌드하고 실행한다.

예시:

cd /volume1/docker
git clone https://git.sori.studio/zenn/planner.sori.studio.git
cd planner.sori.studio
docker compose up -d --build

처음 한 번은 이미지 빌드 때문에 시간이 걸릴 수 있다.

초보자용 빠른 실행

1. 프로젝트 받기

원하는 작업 폴더로 이동한 뒤 저장소를 내려받는다.

cd /원하는/폴더
git clone https://git.sori.studio/zenn/planner.sori.studio.git
cd planner.sori.studio

2. 배포용으로 바로 실행하기

실제 동작 확인이나 NAS 상시 실행은 아래 명령으로 시작한다.

docker compose up -d --build

의미:

• up: 컨테이너를 실행한다.
• -d: 백그라운드에서 실행한다.
• --build: 이미지가 없거나 코드가 바뀌었을 때 다시 빌드한다.

브라우저 접속 주소:

• 프론트엔드: http://NAS주소:48081
• PostgreSQL: NAS주소:45432

현재 docker-compose.yml 기준 내부 구성:

• 프론트엔드 nginx
• 백엔드 Fastify
• PostgreSQL

3. 실행 상태 확인하기

docker compose ps

로그를 보고 싶으면:

docker compose logs -f

특정 서비스만 보고 싶으면:

docker compose logs -f frontend
docker compose logs -f backend
docker compose logs -f postgres

4. 종료하기

docker compose down

데이터베이스 볼륨까지 완전히 지우고 처음부터 다시 시작하고 싶을 때만 아래 명령을 사용한다.

docker compose down -v

주의:

• -v는 PostgreSQL 데이터까지 지울 수 있으니 정말 초기화가 필요할 때만 사용한다.

5. 코드 수정 후 다시 반영하기

배포용 compose는 코드가 자동 반영되지 않는다.

코드를 수정했다면 프로젝트 폴더 안에서 다시 실행한다.

docker compose up -d --build

즉, NAS에서 배포용으로 돌릴 때는 보통 아래 순서를 반복한다.

cd /volume1/docker/planner.sori.studio
git pull
docker compose up -d --build

실행 방법

개발용

코드를 수정하면서 자동 새로고침까지 보려면 개발용 compose를 사용한다.

docker compose -f docker-compose.dev.yml up

개발용도 처음 시작할 때는 아래처럼 프로젝트 폴더 안에서 실행하면 된다.

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를 사용한다.

docker compose up -d --build

배포용 포트:

• 프론트엔드: http://localhost:48081
• PostgreSQL: localhost:45432

배포용 특징:

• 프론트는 빌드 결과물을 nginx로 서빙한다.
• 브라우저에서는 /api 경로로 백엔드에 접근한다.
• 수정 사항 반영 시에는 다시 빌드가 필요하다.

문서

• 작업 규칙: AGENTS.md
• 진행 상태 / 체크리스트: TODO.md
• 인수인계 메모: HANDOFF.md

현재 방향

• 기본 UX는 1페이지 + 우측 정보 패널
• 보조 모드는 2페이지 펼침 보기
• 스타일링은 Vue + TailwindCSS
• 장기적으로는 Docker 기반으로 UGREEN NAS 배포 예정