The easiest way to deploy Kan is through Railway. We've partnered with Railway to maintain an official template that supports the development of the project.
Alternatively, you can self-host Kan with Docker Compose. This will set up everything for you including your postgres database and automatically run migrations.
```bash
docker compose up -d --build
```
1. Create a `.env` file with your environment variables (see [Environment Variables](#environment-variables-) section below)
2. Use the provided `docker-compose.yml` file or create your own with the following configuration:
仓库自带的 `docker-compose.yml` 使用本地镜像标签：
```yaml
services:
migrate:
image:ghcr.io/kanbn/kan-migrate:latest
container_name:kan-migrate
networks:
- kan-network
environment:
- POSTGRES_URL=${POSTGRES_URL}
depends_on:
postgres:
condition:service_healthy
restart:"no"
image:kan-migrate:local
build:
context:.
dockerfile:./apps/web/Dockerfile
target:migrate
web:
image:ghcr.io/kanbn/kan:latest
container_name:kan-web
ports:
- "${WEB_PORT:-3000}:3000"
networks:
- kan-network
env_file:
- .env
environment:
- NEXT_PUBLIC_BASE_URL=${NEXT_PUBLIC_BASE_URL}
- BETTER_AUTH_SECRET=${BETTER_AUTH_SECRET}
- POSTGRES_URL=${POSTGRES_URL}
- NEXT_PUBLIC_ALLOW_CREDENTIALS=true
depends_on:
migrate:
condition:service_completed_successfully
restart:unless-stopped
postgres:
image:postgres:15
container_name:kan-db
environment:
- POSTGRES_DB=kan_db
- POSTGRES_USER=kan
- POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
ports:
- 5432:5432
volumes:
- kan_postgres_data:/var/lib/postgresql/data
healthcheck:
test:["CMD-SHELL","pg_isready -U kan -d kan_db"]
interval:5s
timeout:5s
retries:10
restart:unless-stopped
networks:
- kan-network
networks:
kan-network:
volumes:
kan_postgres_data:
image:kan:local
build:
context:.
dockerfile:./apps/web/Dockerfile
target:web
```
3. Start the containers in detached mode:
不会拉取远端 Web 镜像。数据库迁移会在 Web 服务启动前自动执行。启动完成后访问 <http://localhost:3000>。如修改端口，请同步修改 `WEB_PORT` 和 `NEXT_PUBLIC_BASE_URL`。
### 常用命令
```bash
docker compose up -d
# 查看状态
docker compose ps
# 查看 Web 日志
docker compose logs -f web
# 查看迁移日志
docker compose logs -f migrate
# 停止服务
docker compose down
# 停止服务并删除数据库卷（会删除本地数据）
docker compose down -v
```
The `migrate` service will automatically run database migrations before the web service starts. The application will be available at http://localhost:3000 (or the port specified in `WEB_PORT`).
检查 API 健康状态：
**Managing containers:**
```bash
curl http://localhost:3000/api/v1/health
```
- To stop the containers: `docker compose down`
- To view logs: `docker compose logs -f`
- To view logs for a specific service: `docker compose logs -f web` or `docker compose logs -f migrate`
- To restart the containers: `docker compose restart`
- To rebuild after code changes: `docker compose up -d --build`
预期返回：
For the complete Docker Compose configuration with all optional features, see [docker-compose.yml](./docker-compose.yml) in the repository.
| `NEXT_PUBLIC_DISABLE_SIGN_UP` | Disable sign up | For authentication | `false` |
| `NEXT_PUBLIC_WHITE_LABEL_HIDE_POWERED_BY` | Hide “Powered by kan.bn” on public boards (self-host) | For white labelling | `true` |
| `KAN_ADMIN_API_KEY` | Admin API key for stats and admin endpoints | For admin/monitoring | `your-secret-admin-key` |
| `LOG_LEVEL` | Log verbosity level (debug, info, warn, error) | No (defaults to debug in dev, info in prod) | `info` |
```bash
pnpm typecheck
pnpm lint
pnpm format
```
See `.env.example` for a complete list of supported environment variables.
## 环境变量
## MCP Server (AI Control) 🤖
完整变量列表见 [`.env.example`](.env.example)。
Kan ships with a [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server that lets any MCP-compatible AI client — GitHub Copilot, Claude Desktop, Cursor, Codex, and others — read and control your Kan instance using natural language.
- A Kan API key (Settings → API Keys → Create key)
Kan 仓库内置了基于 Model Context Protocol 的 MCP 服务。连接后，Claude Desktop、Cursor、VS Code、Codex 等 MCP 客户端可以通过自然语言读取和管理 Kan 数据。
### Installation
### 先看这里
You do **not** need to clone this repository. The recommended way is to use `npx`, which runs the server on-demand and always uses the latest version — no global install required:
Proudly sponsored by [TestMu AI (formerly LambdaTest)](https://www.testmuai.com) - an AI-native testing cloud platform built for modern engineering teams. Covering everything from autonomous test creation and fast execution to testing AI agents like chatbots and voice assistants. If you're serious about testing, go check them out.
## License 📝
Kan is licensed under the [AGPLv3 license](LICENSE).
## Contact 📧
For support or to get in touch, please email [henry@kan.bn](mailto:henry@kan.bn) or join our [Discord server](https://discord.gg/e6ejRb6CmT).
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
