init & setup

새 프로젝트를 만들고 처음 세팅하는 명령입니다. 포트 옵션과 자주 나는 문제를 설명합니다.

init

템플릿(frontend, backend, docker-compose.yml)을 새 폴더에 펼칩니다. 설치나 실행은 하지 않습니다.

bash

npx create-meerkit my-app
# 또는
npx @snackcup/meerkit init my-app

폴더 이름은 소문자, 숫자, -, _만 쓸 수 있고 문자나 숫자로 시작해야 합니다.
이미 있는 폴더라면 비어 있어야 합니다.

setup

프로젝트 폴더 안에서 실행합니다. 세팅 6단계를 순서대로 진행하고, 끝나면 서버까지 켭니다.

bash

cd my-app
npx @snackcup/meerkit setup

단계	하는 일
점검	Node, npm, uv, Docker, 디스크 여유 공간, 사용할 포트를 확인합니다
1/6	프론트엔드 라이브러리 설치 (npm install)
2/6	백엔드 라이브러리 설치 (uv sync)
3/6	backend/.env, frontend/.env.local을 만들고 비밀키를 채웁니다. 이미 있으면 덮어쓰지 않습니다
4/6	데이터베이스를 켭니다 (docker compose)
5/6	데이터베이스 테이블을 만듭니다 (마이그레이션)
6/6	로컬용 관리자 계정을 만듭니다

옵션	설명
`--port <번호>`	프론트엔드 포트 (기본 3000)
`--api-port <번호>`	백엔드 포트 (기본 8000)
`--no-start`	서버는 켜지 않고 세팅만 합니다
`--dir <폴더>`	다른 폴더의 프로젝트를 대상으로 합니다

예시

bash

# 서버는 켜지 않고 세팅만
npx @snackcup/meerkit setup --no-start

# 3000, 8000 포트를 다른 프로그램이 쓰고 있을 때
npx @snackcup/meerkit setup --port 3100 --api-port 8100

포트는 1024~65535 사이이고 두 포트가 같으면 안 됩니다. 브라우저가 막는 포트(예: 6000)는 피하세요.
.env 파일은 고치지 않고, 서로를 가리키는 주소(CORS, API 프록시)가 이번 실행에 맞춰 함께 바뀝니다.
전체 로그는 프로젝트 폴더의 meerkit-setup.log에 남습니다. 비밀 값은 기록하지 않습니다.

관리자 계정은 로컬 개발용입니다. 아이디와 비밀번호는 backend/.env의 SEED_ADMIN_USER_ID, SEED_ADMIN_PASSWORD에 있고, 운영에서는 반드시 바꾸세요. 기본 포트가 아니면 Google 같은 소셜 로그인은 등록한 주소와 달라 동작하지 않을 수 있습니다.

자주 나는 문제

증상	확인할 것
Docker Desktop이 켜져 있는데 "응답이 없음"	디스크가 가득 차면 Docker가 멈춥니다. 공간을 확보하고 Docker Desktop을 재시작하세요.
Docker Desktop "실행 중이 아님"	Docker Desktop을 실행하고 완전히 켜질 때까지 기다린 뒤 다시 실행하세요.
"이미 사용 중" 포트 오류	안내에 나온 프로그램을 종료하거나 --port, --api-port로 다른 포트를 쓰세요.
한 단계에서 멈춤	화면에 나온 원인과 해결 방법을 따른 뒤 같은 setup 명령을 다시 실행하면 그 단계부터 이어집니다.
npm install 중 ENOSPC	디스크 공간 부족입니다. 공간을 확보한 뒤 다시 실행하세요.

init & setup

새 프로젝트를 만들고 처음 세팅하는 명령입니다. 포트 옵션과 자주 나는 문제를 설명합니다.

init

템플릿(frontend, backend, docker-compose.yml)을 새 폴더에 펼칩니다. 설치나 실행은 하지 않습니다.

bash

npx create-meerkit my-app
# 또는
npx @snackcup/meerkit init my-app

폴더 이름은 소문자, 숫자, -, _만 쓸 수 있고 문자나 숫자로 시작해야 합니다.
이미 있는 폴더라면 비어 있어야 합니다.

setup

프로젝트 폴더 안에서 실행합니다. 세팅 6단계를 순서대로 진행하고, 끝나면 서버까지 켭니다.

bash

cd my-app
npx @snackcup/meerkit setup

단계	하는 일
점검	Node, npm, uv, Docker, 디스크 여유 공간, 사용할 포트를 확인합니다
1/6	프론트엔드 라이브러리 설치 (npm install)
2/6	백엔드 라이브러리 설치 (uv sync)
3/6	backend/.env, frontend/.env.local을 만들고 비밀키를 채웁니다. 이미 있으면 덮어쓰지 않습니다
4/6	데이터베이스를 켭니다 (docker compose)
5/6	데이터베이스 테이블을 만듭니다 (마이그레이션)
6/6	로컬용 관리자 계정을 만듭니다

옵션	설명
`--port <번호>`	프론트엔드 포트 (기본 3000)
`--api-port <번호>`	백엔드 포트 (기본 8000)
`--no-start`	서버는 켜지 않고 세팅만 합니다
`--dir <폴더>`	다른 폴더의 프로젝트를 대상으로 합니다

예시

bash

# 서버는 켜지 않고 세팅만
npx @snackcup/meerkit setup --no-start

# 3000, 8000 포트를 다른 프로그램이 쓰고 있을 때
npx @snackcup/meerkit setup --port 3100 --api-port 8100

포트는 1024~65535 사이이고 두 포트가 같으면 안 됩니다. 브라우저가 막는 포트(예: 6000)는 피하세요.
.env 파일은 고치지 않고, 서로를 가리키는 주소(CORS, API 프록시)가 이번 실행에 맞춰 함께 바뀝니다.
전체 로그는 프로젝트 폴더의 meerkit-setup.log에 남습니다. 비밀 값은 기록하지 않습니다.

자주 나는 문제

증상	확인할 것
Docker Desktop이 켜져 있는데 "응답이 없음"	디스크가 가득 차면 Docker가 멈춥니다. 공간을 확보하고 Docker Desktop을 재시작하세요.
Docker Desktop "실행 중이 아님"	Docker Desktop을 실행하고 완전히 켜질 때까지 기다린 뒤 다시 실행하세요.
"이미 사용 중" 포트 오류	안내에 나온 프로그램을 종료하거나 --port, --api-port로 다른 포트를 쓰세요.
한 단계에서 멈춤	화면에 나온 원인과 해결 방법을 따른 뒤 같은 setup 명령을 다시 실행하면 그 단계부터 이어집니다.
npm install 중 ENOSPC	디스크 공간 부족입니다. 공간을 확보한 뒤 다시 실행하세요.