Self-hosted personal planning and todo management
English | 简体中文
Features · Interface · Quick Start · Configuration · Development · Notifications · Clients
Self-hosted personal planning and todo management with a five-level structure: folders, boards, panels, lists and cards. Multi-user with isolated data, real-time sync across devices, designed for desktop, tablet and phone.
- Five-level structure: folders → boards → panels (tabs) → lists → cards; folders nest up to 16 levels, drag to reorder
- Real-time sync: every change is pushed over WebSocket to the user's other devices instantly
- Card content: Markdown description, multiple labels, priority levels, three-level tasks, attachments (image/PDF/audio/video/text preview), quick links, timer, action log
- List rules: create / move-in / move-out of a card can adjust labels and start/finish times; each list sorts independently
- Remind and due: notifications are sent through gmsg when the time arrives; missed ones are delivered after recovery, failures retry automatically
- Archive system: boards, panels, lists and cards can each be archived, viewed and restored; archives cannot be emptied
- File management: attachments are deduplicated by sha256 with reference counting; unreferenced files are cleaned manually; a file can be referenced only after its full content has been uploaded, and re-uploads by the same user are instant
- Search and filter: within a panel by title, description, labels, priorities, members and dates; "today only" dims the rest
- Responsive + PWA: layouts for desktop, tablet and phone; add to the home screen for full screen; three themes (Clean / Night / Paper)
- Chinese & English: switch the interface language in personal settings, or follow the system; notifications use the same language
- Multi-user: the admin creates accounts with isolated data; username, nickname, password, time zone and shortcuts are per user; one browser can stay signed in to several accounts and switch between them under "Accounts" in the sidebar
| Board | Sidebar |
|---|---|
| Card detail | Night theme |
|---|---|
| Phone |
|---|
git clone https://github.com/Akvicor/kanban
cd kanban
docker compose -f docker-compose.sqlite.yml up -dOn first start data/config.yaml is generated automatically; the database and attachments live in the data directory. Open http://localhost:3000.
The image is ghcr.io/akvicor/kanban for linux/amd64 and linux/arm64: latest points to the newest stable release, or pin a version such as ghcr.io/akvicor/kanban:v1.2.0.
cp config.postgres.yaml.example data/config.yaml
# set the database password in data/config.yaml to match docker-compose.postgres.yml
docker compose -f docker-compose.postgres.yml up -dDownload kanban-<os>-<arch>.tar.gz for your system (Linux, macOS; amd64 / arm64) from Releases and extract it, or build from source:
make build # produces build/kanban with the frontend embedded
./build/kanban migrate -c ./data/config.yaml # create or upgrade schema, init admin
./build/kanban server -c ./data/config.yamlAfter upgrading, always run
kanban migratebefore starting the server. The server does not upgrade the schema on startup; skipping this step breaks features that use new columns.
migrate creates the initial admin from environment variables when the database has no users. Additional accounts are created by the admin on the user management page.
The configuration file is YAML, see config.sqlite.yaml.example (SQLite) or config.postgres.yaml.example (PostgreSQL):
| Section | Description |
|---|---|
server |
listen address, port, HTTPS certificates, frontend directory, trusted reverse proxies |
database |
sqlite or postgres and the matching connection parameters |
storage |
directory for attachments, thumbnails and unfinished uploads |
log |
log file switch, levels and flags |
Behind a reverse proxy, list the proxy addresses (CIDR or single IP) in server.trusted-proxies. The client IP is then read from the X-Forwarded-For sent by these proxies, and login rate limiting counts by it; when empty, the connection's source address is used.
All writes are synced to the user's other devices in real time (except device last-active time). A device with no request or sync connection for 90 days is signed out and has to log in again.
make dev # migrate + start the server (debug mode reads frontend files live)
make verify # frontend tests + backend verification + dependency audit
make format # format frontend and backend codebackend/: Go server — HTTP API, WebSocket sync, gmsg notifications, attachmentsfrontend/: React + TypeScript + Vite, built assets are embedded into the binary- Interface texts live in
frontend/src/i18n(messages.*.tsper language); API error codes are mapped inerrors.*.tsand kept in sync withbackend/.../respbyerrors.test.ts
Notifications are sent only through gmsg. Each channel has its own API, token, sign and content format (text / Markdown) and sends with SendBySign; the channels page can send a test message. Remind and due bodies are templates with placeholders, and inserted content can be escaped for Markdown channels.
A channel API is the address of a gmsg service (internal addresses are allowed) without ? or #; requests go to <API>/api/send and redirects are not followed. Failed sends record only the HTTP status code and the error returned by gmsg.
The desktop client for Linux, Windows and macOS lives in the kanban-app repository. Its window loads this server's address directly, so the interface updates with the server. The client relies on the following contract; keep kanban-app in sync when changing it:
- The health check
GET /api/sys/info/healthreturns 200 with{"status": "...", "checks": {...}}(503 when a dependency is not ready); the client uses it to confirm the address is a Kanban server. - The client appends
KanbanApp/<version>to the User-Agent; the frontend uses it to show the device as "Desktop app · " (frontend/src/session/deviceName.ts). - The client only grants the clipboard-write and fullscreen web permissions; when the frontend starts using a new browser permission, the client must allow it as well.
This project is released under the GNU General Public License v3.0.
- Derivative works must be distributed under GPLv3 as well
- Distributing binaries requires providing the complete corresponding source code
- No warranty is provided
See LICENSE for the full text.