Skip to main content

로컬 개발 환경

LinkBoard는 Docker Compose로 전체 스택(DB · Redis · EMQX · 백엔드 · 프론트엔드)을 한 번에 띄울 수 있습니다. 모든 서비스가 bind mount + hot-reload로 구성되어 있어, 코드를 수정하면 바로 반영됩니다.

사전 준비​

  • Docker Engine + Docker Compose v2

기동​

git clone <저장소 URL>      # 소스 접근은 내부적으로 제공됩니다
cd linkboard
cp .env.example .env      # 개발은 기본값으로도 동작합니다

docker compose up -d                       # db, redis, emqx, backend, frontend 전부 기동
docker compose exec backend alembic upgrade head
docker compose exec backend python scripts/seed_admin.py       # SystemAdmin + 기본 테넌트/TenantAdmin
docker compose exec backend python scripts/seed_templates.py   # 대시보드 템플릿 시딩

기동 후 접속:

서비스주소
프론트엔드http://localhost:5173
API 문서(Swagger)http://localhost:8000/api/docs
EMQX 대시보드http://localhost:18083

재빌드가 필요한 경우​

Dockerfile을 바꿨거나 새 npm/pip 의존성을 추가했다면:

docker compose build backend frontend
docker compose up -d --force-recreate backend frontend

알려진 함정​

  • frontend 서비스는 node_modules를 익명 볼륨으로 마운트합니다. 이미지를 재빌드해도 기존 컨테이너의 볼륨이 재사용되어 새 의존성이 반영되지 않을 수 있습니다 — 재생성 후 아래로 확인/보정하세요.

    docker compose exec frontend npm install   # 신규 의존성이 안 보이면 실행
    docker compose restart frontend            # Vite 의존성 캐시 재최적화

  • Windows에서 Docker 볼륨을 통한 파일 감시(inotify)가 동작하지 않을 수 있습니다 (코드 수정이 반영되지 않음) — 이 경우 docker compose restart backend frontend로 강제 반영하세요.