litmers-dev/litpage

Litpage

Litpage는 직접 운영하는 오픈소스 워크스페이스입니다. 블록 에디터로 글을 쓰고, 페이지와 팀을 정리하고, 다양한 뷰를 갖춘 데이터베이스로 작업을 추적하고, 세밀한 권한으로 공유하며, 자신의 AI 키를 연결해 채팅, 에이전트, 글쓰기 도움을 받을 수 있습니다. 앱 전체가 하나의 Node.js 프로세스와 하나의 SQLite 파일로 동작하며, 노트북이나 단일 서버에서 돌릴 수 있을 만큼 작습니다.

데모 체험: litpage-demo-production.up.railway.app 을 열고 Try the demo를 클릭하면 가입 없이 사용할 수 있습니다.

샘플 페이지가 포함된 자신만의 워크스페이스가 주어지고, 다른 사람은 볼 수 없으며, 4시간 후 삭제됩니다. 데모에서는 AI가 연결되지 않습니다.

Litpage를 쓰는 이유

• 셀프 호스팅, 그리고 작음. 프로세스 하나, SQLite 데이터베이스 하나(node:sqlite와 전문 검색), 파일은 한 폴더에 모입니다. Postgres, Redis, 큐를 따로 돌릴 필요가 없습니다.
• 문서와 데이터가 함께. 페이지, 블록 에디터, 데이터베이스가 같은 트리에 있으므로 프로젝트 브리프와 그 작업 보드가 나란히 위치합니다.
• 진짜 협업. WebSocket 기반 실시간 다중 사용자 편집, 댓글과 수정 제안, 버전 기록, 팀, 페이지 수준 및 필드 수준 권한, 공개 공유와 사이트 게시를 지원합니다.
• 내 조건대로 쓰는 AI. 채팅, 커스텀 에이전트, AI 블록, 자동 채우기, 회의록 요약은 직접 설정한 제공자와 키로 동작합니다. 키가 없어도 나머지 기능은 모두 작동합니다.
• 내 도구에 열려 있음. 웹훅이 있는 REST API와 AI 클라이언트용 MCP 엔드포인트를 제공하며, 토큰은 직접 관리합니다.
• 두 가지 언어. 인터페이스는 영어와 한국어를 지원합니다.

기능 둘러보기

• 블록 에디터. 41가지 블록 타입, 슬래시 메뉴, 마크다운 단축키, 드래그 앤 드롭, 멘션, 댓글과 수정 제안.
• 데이터베이스. 타입이 있는 필드, 필터, 정렬, 그룹, 수식, 관계, 롤업, 템플릿, 버튼, 자동화.
• 같은 데이터의 다양한 뷰. 테이블, 보드, 리스트, 갤러리, 캘린더, 타임라인, 차트, 대시보드, 피드, 폼, 지도.
• 차트와 대시보드. 데이터베이스에서 바로 세로 막대, 가로 막대, 선, 도넛, 숫자 차트를 만듭니다.
• 워크스페이스를 아는 AI. 페이지에 대해 질문하고, 글을 초안 작성·편집하고, 데이터베이스 필드를 채우고, 커스텀 에이전트를 일정이나 트리거로 실행합니다.
• 영어와 한국어. 설정에서 인터페이스 언어를 바꿀 수 있습니다.

포함된 모든 것

• 에디터: 리치 텍스트, 41가지 블록 타입, 슬래시 메뉴, 마크다운 단축키, 드래그 앤 드롭, 멘션, 수식, 구문 강조가 있는 코드 블록, 임베드, 댓글과 수정 제안, 버전 기록, 실시간 협업.
• 워크스페이스: 페이지와 하위 페이지, 즐겨찾기와 최근 항목이 있는 사이드바, 팀, 공유와 권한, 게시된 사이트, 가져오기(Markdown, CSV, HTML, Word, PDF)와 내보내기, 받은편지함과 알림, 리마인더, 휴지통, 라이트·다크 테마.
• 데이터베이스: 테이블, 보드, 리스트, 갤러리, 캘린더, 타임라인, 차트, 대시보드, 피드, 폼, 지도 뷰; 필터, 정렬, 그룹, 수식, 관계, 롤업, 고유 ID, 자동화, 버튼, 템플릿, 필드 수준 접근 규칙.
• AI(선택): 워크스페이스 검색이 포함된 채팅, 트리거와 일정이 있는 커스텀 에이전트, 글쓰기 어시스턴트, AI 블록, 데이터베이스 자동 채우기, 수식 어시스턴트, 요약이 포함된 회의록, 제공자가 지원하는 경우 이미지 생성.
• 관리자: 워크스페이스 설정, 멤버와 게스트, 보안 정책, 감사 로그, 분석, 패스키와 2단계 인증.
• 개발자: 개인 액세스 토큰과 통합이 있는 REST API, 웹훅, MCP 엔드포인트.

빠른 시작

Docker 사용

docker build -t litpage.
docker run -d --name litpage -p 3001:3001 -v litpage-data:/data \
  -e [email protected] -e NC_BOOTSTRAP_PASSWORD='change-me' \
  litpage

http://localhost:3001 을 열고 해당 이메일과 비밀번호로 로그인합니다("Continue with a password"). 데이터(SQLite 데이터베이스와 업로드된 파일)는 litpage-data 볼륨에 저장됩니다.

소스에서 실행

요구 사항: Node.js 26 이상과 pnpm 10(npm install -g [email protected]).

pnpm install
pnpm dev            # API on http://127.0.0.1:3001, web app on http://127.0.0.1:5173

http://127.0.0.1:5173 을 열고 아무 이메일 주소나 입력합니다. 개발 모드에서는 로그인 코드가 화면에 표시되고, 온보딩에서 첫 워크스페이스를 만듭니다. 데이터는 apps/server/data/에 저장됩니다.

API 서버가 3001 포트에서 제공하는 프로덕션 빌드의 경우:

pnpm build && pnpm start

설정

다음 항목을 환경 변수로 설정합니다(개발 환경에서는 apps/server/.env.local도 읽으며, 이 파일은 git에서 무시됩니다).

데모 모드

NCDEMOMODE=1로 설정하면 공개 데모를 게시합니다. 로그인 페이지에 Try the demo가 표시되며, 한 번 클릭하면 임시 계정과 "Litpage Demo"라는 워크스페이스가 만들어집니다. 여기에는 "Start here" 페이지와 샘플 페이지(Roadmap, Projects, Meeting notes, Team wiki)가 포함되고 방문자가 로그인됩니다. 각 방문자는 자신의 워크스페이스만 볼 수 있으며, 생성 후 NCDEMOSANDBOX_HOURS가 지나면 페이지, 댓글, 기록, 검색 항목, 파일 등 모든 내용과 함께 삭제됩니다. 백그라운드 작업이 몇 분마다 확인합니다. 알림 바의 "Start over"는 새 워크스페이스로 교체합니다. 클라이언트 주소당 워크스페이스 수, 활성 워크스페이스 수, 레코드, 업로드에는 제한이 있습니다(위 표 참고).

서버는 계정 신원, 워크스페이스 관리, 초대, 공유 및 게시, 통합과 토큰, 웹훅, 공개 폼, AI 및 기타 외부로 나가는 작업, 그리고 다른 방문자에게 도달할 수 있는 모든 것을 거부합니다. NCBOOTSTRAPEMAIL과 NCBOOTSTRAPPASSWORD가 설정되어 있으면 로그인 페이지에 이메일 폼도 유지되어 해당 공유 계정으로 이전처럼 로그인할 수 있습니다. 설정하지 않으면 이메일 폼은 숨겨집니다. NCDEMORESET_HOURS는 추가로 시작 시 데이터 디렉터리를 지우고 주기적으로 프로세스를 재시작합니다. 모든 데모 데이터는 일회용으로 취급하고, 플랫폼이 종료 시 재시작하도록 설정하십시오.

자신의 키로 쓰는 AI

모든 AI 기능은 서버에 설정된 하나의 제공자를 통해 동작합니다. 키는 서버에만 남습니다. 브라우저로 전송되지 않으며 로그와 오류에서 마스킹됩니다.

node scripts/tools/openai-smoke.mjs는 몇 개의 짧은 요청을 보내 실제 엔드포인트를 확인합니다. 테스트와 엔드투엔드 스크립트는 로컬 모의 서버와만 통신합니다.

API와 통합

• REST API는 /v1에서 페이지, 데이터베이스, 데이터 소스, 블록, 댓글, 사용자, 검색을 제공합니다. 설정에서 개인 액세스 토큰이나 통합을 만든 뒤:

  curl http://localhost:3001/v1/search \
    -H "Authorization: Bearer $LITPAGE_TOKEN" \
    -H "Litpage-Version: 2026-10-01" \
    -H "Content-Type: application/json" \
    -d '{"page_size": 10}'

• 웹훅은 페이지, 데이터베이스, 댓글 이벤트에 대해 제공되며 HMAC-SHA256으로 서명되고 실패 시 재시도됩니다.
• MCP 엔드포인트는 /api/mcp에 있어 Model Context Protocol을 지원하는 AI 클라이언트가 접근 권한이 있는 페이지를 검색·편집할 수 있으며, 앱과 동일한 권한 검사를 적용합니다.

Litpage-Version 헤더는 선택 사항이며 기본값은 현재 버전입니다.

아키텍처

flowchart LR
  subgraph Browser
    UI["React 19 app<br/>editor, databases, AI panel"]
  end
  subgraph Server["One Node.js process"]
    RPC["JSON RPC<br/>/api/rpc"]
    WS["Real-time sync<br/>WebSocket"]
    REST["REST API and webhooks<br/>/v1"]
    MCP["MCP endpoint<br/>/api/mcp"]
    AI["AI service<br/>chat, agents, autofill"]
    DB[("SQLite<br/>with full-text search")]
    FILES[("Uploaded files")]
  end
  PROVIDER["Your AI provider<br/>OpenAI compatible or Anthropic"]
  TOOLS["Your scripts and tools"]
  CLIENTS["MCP clients"]
  UI --> RPC
  UI <--> WS
  RPC --> DB
  RPC --> FILES
  WS --> DB
  REST --> DB
  TOOLS --> REST
  CLIENTS --> MCP
  MCP --> AI
  RPC --> AI
  AI --> PROVIDER

packages/shared   records, operations, rich text, permissions, database query and formula engine
apps/server       Node 26 + Hono + node:sqlite + WebSocket
apps/web          React 19 + Vite
e2e               end-to-end scripts (Chrome via playwright-core)
docs              architecture.md, how-it-was-built.md

자세한 내용은 docs/architecture.md 참고.

개발

pnpm typecheck
pnpm test                                               # unit tests: shared, server, web
cd e2e && NC_BASE=http://127.0.0.1:5173 node smoke.mjs  # end-to-end, one script per area

엔드투엔드 스크립트는 개발 서버를 대상으로 Google Chrome(기본 macOS 경로는 e2e/lib.mjs)을 구동합니다. 이 문서의 이미지는 scripts/readme/에서 생성됩니다(캡처 후 에셋 빌드).

어떻게 만들어졌나

Litpage는 YouTube 시리즈를 위한 실험으로 시작했습니다. AI 코딩 에이전트가 블록 기반 워크스페이스 앱 전체를 만들 때 어디까지 가능할까? 리드 Claude Code 세션이 작업을 영역별로 나누고 서브에이전트를 조율했으며, 단위 테스트와 엔드투엔드 테스트를 가드레일로 삼았습니다. 그 이야기는 docs/how-it-was-built.md에 있습니다. Litpage는 연구 및 시연 프로젝트이며 있는 그대로 제공됩니다.