The Markdown Wiki — empower the team with sharing your knowledge.
Caution
Crowi v2 — codename Reignite — is in active prerelease.
- Alpha prereleases are published and support an in-place upgrade from a v1 MongoDB. There is no stable v2 yet, so the API / config surface can still change between alphas — pin a specific version from the releases and read the notes. For a real deployment use a published release, not this branch's HEAD.
- Crowi v1.x is deprecated and unmaintained.
- Track progress in
TODO.md, the docs, and the v2 announcement on Zenn.
Crowi is a Markdown Wiki for team knowledge sharing. URL paths are the
page hierarchy, so /team/handbook/onboarding reads exactly the way it's
written. v2 ("Reignite") rebuilds the stack from Express + Swig + jQuery
to a Hono API + Next.js 16 (App Router) + React 19, while keeping v1's
MongoDB data shape intact — your existing wiki migrates over.
v2 highlights: real-time collaborative editing (Yjs / Hocuspocus), an
embedded Model Context Protocol (MCP) server for AI agents, OAuth 2.0 +
personal access tokens, a pluggable storage / search / renderer / mail
architecture, sensitive-config encryption (AES-256-GCM), dark mode, and the
@crowi/cli end-user CLI.
This repository is a Turborepo + pnpm workspace.
crowi/
├── apps/
│ ├── crowi-runner/ # Reference runner project (@crowi/runner-app): dev launch
│ │ # point + build source for the full Docker image. Owns
│ │ # @crowi/api + the full plugin set + crowi.config.json.
│ ├── crowi-runner-slim/ # Minimal runner project: build source for the slim Docker
│ │ # image (core + a minimal plugin set)
│ └── crowi-site/ # crowi.wiki LP + docs (Next.js + Fumadocs, port 4303)
├── .env.example # Dev runtime env template (copy to .env)
└── packages/
├── api/ # Hono 4 API library (port 4301)
├── api-contract/ # Shared Hono (@hono/zod-openapi) contracts + Zod schemas
├── web/ # Next.js 16 frontend (port 4302)
├── collab/ # Realtime collab server (Yjs / Hocuspocus), attached to the api
├── runner/ # Config loader + plugin resolver (used by @crowi/api boot)
├── cli/ # `@crowi/cli` end-user CLI (read / write / search over the HTTP API)
├── admin-cli/ # `crowi-admin` CLI (init / migrate / re-encrypt; DB-direct)
├── plugin-api/ # Plugin SDK (CrowiPlugin / registries / context)
├── plugin-aws/ # Shared AWS credentials base plugin
├── plugin-storage-local/ # Default-on local FS storage driver
├── plugin-storage-aws-s3/ # S3 storage driver
├── plugin-search-elasticsearch/ # Elasticsearch search driver
├── plugin-search-opensearch/ # OpenSearch search driver
├── plugin-search-mongo/ # MongoDB-native search driver (no external service)
├── plugin-mail-smtp/ # SMTP mail transport
├── plugin-mail-resend/ # Resend mail transport
├── plugin-mail-aws-ses/ # AWS SES mail transport
├── plugin-renderer-katex/ # KaTeX math renderer
├── plugin-renderer-plantuml/ # PlantUML diagram renderer
└── plugin-renderer-crowi-legacy/ # v1-era wikilinks / strikethrough / etc.
The API package is plugin-agnostic at runtime — @crowi/runner
resolves plugin npm names against the runner project's node_modules/
via createRequire(<projectDir>/package.json). Operators add a plugin
by declaring it in their runner's package.json deps and listing it
in crowi.config.json:plugins; the api never needs to be rebuilt.
- API: Hono 4 +
@hono/zod-openapi+ Mongoose + JWT auth (jwtAuthmiddleware); OAuth 2.0 + PAT; embedded MCP server - Realtime: Yjs + Hocuspocus, attached to the api process (
@crowi/collab) - Web: Next.js 16 (App Router, Turbopack) + React 19 + Tailwind CSS v4 + shadcn/ui + @tanstack/react-query
- Site: Next.js 16 (static export) + Fumadocs UI + i18n (ja / en)
- Shared: TypeScript 5.x strict, pnpm workspaces, Turborepo
- Lint / Format: Biome (format) + ESLint (lint), lefthook hooks
- Tests: Jest + supertest + mongodb-memory-server (API + collab)
- Node.js 24.x
- pnpm 10.x (pinned via
packageManagerinpackage.json) - MongoDB
- Redis
- A search backend (optional, plugin-driven): Elasticsearch / OpenSearch, or the external-service-free MongoDB driver
- Docker / Docker Compose (for local infrastructure)
# 1. Install dependencies pnpm install # 2. Start dependency services (MongoDB / Redis / Elasticsearch / PlantUML) docker compose up -d # 3. Set up env file at the repo root. `pnpm dev` boots the api with cwd = # apps/crowi-runner (the runner projectDir), so its dev script loads this # repo-root .env via `--env-file-if-exists=../../.env`. (In production / an # external runner project, the api reads the .env in its own cwd via dotenv.) cp .env.example .env # Edit MONGO_URI / REDIS_URL / PASSWORD_SEED / CROWI_ENCRYPTION_KEY etc. # 4. Run everything (api on :4301, web on :4302). Workspace libs/plugins are # built ONCE up front (turbo-cached); only api, web and api-contract stay # under a live watch — see the note below to watch a specific one back. pnpm dev
Other targeted scripts:
pnpm dev:api # just the API + plugins (no Next.js) pnpm dev:web # just the Next.js frontend pnpm dev:site # crowi.wiki LP + docs (port 4303)
pnpm dev keeps only @crowi/api (tsx), @crowi/web (next) and
@crowi/api-contract under a persistent watch — api-contract JS-only, since its
.d.ts rollup worker alone holds several GiB resident. Every other library /
plugin is compiled once at startup. When you're editing one of them, watch it
back with --watch (repeatable; short or scoped name):
pnpm dev --watch plugin-slack # or @crowi/plugin-slack pnpm dev --watch collab --watch runner # repeatable pnpm dev --watch @crowi/api-contract # also regenerates its .d.ts live
.env.example (at the repo root) lists the full set. Highlights:
| Variable | Purpose |
|---|---|
MONGO_URI |
MongoDB connection string |
REDIS_URL |
Coordination for realtime-collab pub/sub, the editor-cap counter, presence, notification invalidation, Config sync, rate limiting, and LRU (use rediss:// for TLS) |
PASSWORD_SEED |
Legacy password hashing seed (still used for fallback verification) |
CLIENT_URL |
CORS allowlist origin in production (defaults allow localhost in dev) |
CROWI_ENCRYPTION_KEY |
Base64-encoded 32-byte AES-256 key for sensitive Config encryption. Generate via openssl rand -base64 32 or pnpm --filter @crowi/api crypto:gen-key. Strongly recommended to set; missing key falls back to plaintext (legacy behaviour) with a startup warning. |
PORT |
API server port (default 4301) |
NODE_ENV |
production or development |
See Redis licensing and engine support policy for supported Redis versions, image pinning, and ACL security guidance covering every REDIS_URL consumer above.
Storage backend selection is driven by the runner's crowi.config.json
(storage.driver: 'local' | 's3' | ...) plus the corresponding
@crowi/plugin-storage-* package — there is no FILE_UPLOAD env any
more.
Published on Docker Hub. Alpha prereleases carry a moving alpha channel
tag that always points at the newest alpha (the latest tag is reserved for a
future stable release), so you can follow the channel without chasing version
numbers — or pin an exact 2.0.0-alpha.N tag for a reproducible deploy.
| Image | Contents |
|---|---|
crowi/crowi |
Full api / runner — core + all first-party plugins |
crowi/crowi:...-slim |
Slim runner — core + a minimal plugin set (same image repo) |
crowi/crowi-web |
Next.js frontend renderer |
docker pull crowi/crowi:alpha # full api / runner (newest alpha) docker pull crowi/crowi:alpha-slim # slim variant docker pull crowi/crowi-web:alpha # web frontend
See the deployment and self-hosting guides for reverse-proxy, env, and Docker Compose setup.
pnpm test # all apps pnpm --filter @crowi/api test # api only pnpm type-check # api + web + site pnpm lint # all apps; errors=0 required pnpm build # all pnpm --filter @crowi/api-contract build # required after editing contracts
Format runs automatically via lefthook on commit (Biome).
Manual: pnpm format / pnpm format:check.
Plugins are regular npm packages declared in the runner project's
dependencies and listed in crowi.config.json:plugins. The shipped
first-party plugins live under packages/plugin-*/:
- Storage:
plugin-storage-local(default),plugin-storage-aws-s3 - Search:
plugin-search-elasticsearch,plugin-search-opensearch,plugin-search-mongo(no external service) - Mail:
plugin-mail-smtp,plugin-mail-resend,plugin-mail-aws-ses - Renderers:
plugin-renderer-katex,plugin-renderer-plantuml,plugin-renderer-crowi-legacy
Write your own by depending on @crowi/plugin-api, exporting a default
CrowiPlugin, and adding the package name to your runner's
crowi.config.json.
The MIT License (MIT). See LICENSE.