운영자 시작하기

Loafacto Hub 인스턴스를 처음 띄우는 운영자(관리자) 를 위한 설치 가이드입니다. 한 대의 서버(또는 로컬 PC)에 web · backend · 데이터베이스(Supabase)를 모두 띄우고, 브라우저에서 설치 마법사로 마무리하는 흐름입니다.

사용자(끝사용자)가 어떻게 사용하는지는 사용자 가이드를 참고하세요. 코드를 직접 만지는 개발자는 개발 가이드에서 시작합니다.

1. 사전 준비물

항목	권장 버전 / 값
Node.js	20 LTS 이상
npm	10 이상 (또는 pnpm/yarn)
Python	3.11 이상
Git	최신
Docker / Docker Compose	(서버 배포 시) v2 이상
Supabase 프로젝트	supabase.com 무료 플랜으로 충분

추가로 사용할 예정이라면:

• OpenAI / Anthropic API 키 — 챗봇·RAG에 사용 (/admin/ai에서 등록)
• GitHub / Gitea Personal Access Token — /feature/github 저장소 연동
• MCP 서버 — /admin/ai에서 등록

2. 소스 받기

git clone https://github.com/qpang/loafacto-hub.git
cd loafacto-hub

리포지터리는 모노레포 구조이며 다음 3개 앱으로 구성됩니다.

apps/
├── web-ui/          # Vue 3 + Vuetify 프론트엔드
├── backend-server/  # FastAPI + LangGraph 백엔드
└── web-docs/        # 문서 사이트 (지금 보고 있는 것)

3. Supabase 프로젝트 생성

1. Supabase 로그인 → New project 생성
2. 프로젝트 Settings → API에서 다음을 복사
   • Project URL → VITE_SUPABASE_URL / SUPABASE_URL
   • anon public 키 → VITE_SUPABASE_ANON_KEY
   • service_role 키 → SUPABASE_SERVICE_KEY (백엔드 전용, 외부 노출 금지)

SQL 스키마는 4단계의 설치 마법사가 자동으로 안내합니다. 수동 실행이 필요한 경우 resources/supabase/를 참고하세요.

4. 백엔드 실행 (backend-server)

cd apps/backend-server
python -m venv .venv
source .venv/bin/activate    # Windows: .venv\Scripts\activate
pip install -r requirements.txt

apps/backend-server/.env 작성:

SUPABASE_URL=https://<your-project>.supabase.co
SUPABASE_SERVICE_KEY=<service_role 키>
# 선택
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...

서버 시작:

python -m uvicorn app.main:app --reload --port 8000

기동 확인: http://localhost:8000/docs (FastAPI Swagger)

5. 프론트엔드 실행 (web-ui)

cd apps/web-ui
npm install

apps/web-ui/.env 작성:

VITE_SUPABASE_URL=https://<your-project>.supabase.co
VITE_SUPABASE_ANON_KEY=<anon public 키>
VITE_API_URL=http://localhost:8000
# 선택: 문서 공동편집(Tiptap + Yjs) y-websocket 주소
VITE_COLLAB_WS_URL=ws://localhost:1234

개발 서버 시작:

npm run dev

브라우저: http://localhost:5173

6. 설치 마법사 (/setup) 진행

처음 접속하면 라우터 가드가 자동으로 /setup으로 이동시킵니다. 단계별로 다음을 입력하세요.

Step	내용
0	Supabase URL / anon / service key 입력 → 스키마 자동 생성 안내
1	첫 super_admin 관리자 계정 생성 (이메일 + 비밀번호)
2	사이트명, 로고, 기본 언어, 점검 모드 등
3	시스템 에이전트 / MCP / LLM 모델 등록 (스킵 가능)
4	입력 요약 확인 → 설치 완료

설치가 끝나면 자동으로 홈(/)으로 이동합니다.

7. 첫 로그인 후 할 일

1. AI 운영 (/admin/ai) — 사용할 LLM 모델·MCP 서버·RAG 파이프라인 등록
2. 에이전트 관리 (/admin/agents) — 에이전트 시작 (필요 시)
3. 기능 빌더 (/admin/feature-builder) — 노출할 기능 카테고리(챗봇·커뮤니티·태스크·저장소·문서) 활성화·레이아웃 편집
4. 사용자 관리 (/admin/users) — 동료를 초대하고 역할(super_admin / operator / 일반) 부여
5. 공지·배너 (/admin/notices, /admin/banners) — 첫 공지·배너 등록

8. 도커로 전체 배포 (선택)

운영 서버에 한 번에 띄우려면 CI/CD 가이드를 참고하세요. GitHub Actions가 main 브랜치 push 시 GHCR 이미지를 빌드하고 서버에 자동 배포합니다.

서버 ~/docker/
├── docker-compose.yml
├── compositions/
│   ├── traefik.yml
│   ├── supabase.yml
│   └── loafacto-hub.yml      # web + api
└── volumes/

다음으로

• 앱 개요 — 기술 스택과 모노레포 구조
• 페이지 및 라우트 — 전체 라우트 흐름
• 관리자 기능 — 운영 기능 한눈에
• API 키 & MCP 가이드 — 외부 모델·도구 연결