# Project pack: Kanboard @ e197e71

Facts about **Kanboard** for an AI following the [BespokeAI handover guide](https://handoff.bespokeai.software/guide/v1.md). This pack is pinned to one version and never changes after publication.

> Kanboard turns any project into a board of columns, such as To do, Doing and Done, with a card for each task. Drag cards across as work moves on, add checklists, due dates and colours, and let simple rules do chores for you, like closing a task when it reaches Done. It suits a household, a club or a small team, is light enough for a Raspberry Pi, and runs on your own computer or server.

## Version and source
- Repository: https://github.com/kanboard/kanboard
- Pinned commit: `e197e71af4ff9f371b931ab0338b2b41827e6394`. Use exactly this version.
- Get it: `git clone https://github.com/kanboard/kanboard kanboard && cd kanboard && git checkout e197e71af4ff9f371b931ab0338b2b41827e6394`
- Or download a zip: https://github.com/kanboard/kanboard/archive/e197e71af4ff9f371b931ab0338b2b41827e6394.zip
- Official docs: https://docs.kanboard.org/v1/
- Licence: **MIT**. Very permissive. You can use, change, share and even sell it, for any purpose, as long as you keep the copyright and licence notice. There is no obligation to share your changes.

## Running it
- Easiest:

  ```sh
  docker run -d --name kanboard -p 8080:80 -v kanboard-data:/var/www/app/data -v kanboard-plugins:/var/www/app/plugins kanboard/kanboard:latest # then open http://localhost:8080 and log in as admin / admin. Change that password straight away.
  ```

- Needs: Docker, or PHP 8.1+ with a web server (Apache, Nginx or PHP's built-in server), SQLite (default), MySQL/MariaDB or PostgreSQL, Composer for development
- Develop: `composer install && php -S localhost:8000 -t .   # open http://localhost:8000, login admin/admin; copy config.default.php to config.php to change settings`
- Test: `make test-sqlite   # ./vendor/bin/phpunit -c tests/units.sqlite.xml`
- Check/lint: `jshint ./assets/js/core ./assets/js/components`
- Build: `./cli css && ./cli js   # rebuild the bundled CSS and JavaScript after editing assets/css/src or assets/js/src`
- Stack: php, javascript, css (Pimple, PicoDb, SwiftMailer, jQuery UI). Difficulty for a non-developer with an AI: **easy**. Plain PHP with no build step for pages: templates are simple PHP files in app/Template/, and changes show on refresh. Custom CSS, automatic actions, webhooks and a JSON-RPC API cover a lot without code, and plugins can override any template, so most changes survive updates. CSS and JavaScript sources are bundled with ./cli css and ./cli js.

## The project's own AI instructions
Read these in the repository before changing code: `CONTRIBUTING.md`.

## Customisation points (settings → extend → code)
- **application-settings** [settings]: Language (39 included), time zone, date format, application URL and a custom stylesheet box for your own colours and fonts. → `Settings → Application settings (app/Template/config/application.php, app/Controller/ConfigController.php)`
- **theme** [settings]: Light, dark or follow-the-device theme for each person. → `Your user profile → Edit profile (light, dark or automatic theme; app/Model/ThemeModel.php, assets/css/src/themes/)`
- **board-layout** [settings]: Name your columns, set work-in-progress limits, add rows (swimlanes) per person or area, colour-code categories. → `Project → Configure (columns, swimlanes, categories, tags; app/Template/column/, app/Template/swimlane/, app/Template/category/)`
- **automatic-actions** [settings]: Rules such as "when a card reaches Done, close it" or "assign cards in Shopping to Sam". → `Project → Automatic actions (app/Action/, app/Template/action/)`
- **notifications-and-feeds** [extend]: Emails about changes and overdue tasks, due dates in your phone calendar via iCal. → `Profile → Notifications (email, web), project iCal and RSS feeds (app/Template/notification/, app/Template/feed/)`
- **webhooks** [extend]: Send task events to another service, for example a chat bot or home automation. → `Settings → Webhooks (app/Template/config/webhook.php); docs.kanboard.org/v1/dev/webhooks/`
- **api** [extend]: Create, move and read tasks from scripts, shortcuts or other apps. → `JSON-RPC API at /jsonrpc.php (jsonrpc.php, app/Api/), token in Settings → API`
- **plugins** [extend]: Add features, hooks, routes, automatic actions or override any template without touching core files. → `plugins/<Name>/Plugin.php (installed in Settings → Plugins, app/Template/plugin/); guide at docs.kanboard.org/v1/plugins/`
- **templates** [code]: Change what cards, task pages and the dashboard show. → `app/Template/board/, app/Template/task/, app/Template/dashboard/ (PHP templates)`
- **core-logic** [code]: New data or behaviour. Every schema change needs a migration for all three databases. → `app/Controller/, app/Model/, app/Action/; schema changes in app/Schema/Sqlite.php, Mysql.php and Postgres.php`

## Must keep working
- Existing projects, tasks, comments and attachments. Back up the data folder or database before any change.
- Database migrations must exist for SQLite, MySQL and PostgreSQL (app/Schema/).
- The JSON-RPC API in app/Api/. Mobile apps, plugins and scripts depend on it.
- Project permissions. People must only see projects they belong to.
- Prefer a plugin with template overrides over editing app/Template/ directly, so updates don't overwrite your work.

## Staying updatable
Custom CSS, automatic actions, webhooks, the API and plugins cover most needs, and plugins survive updates. Kanboard is in maintenance mode: the author fixes bugs but isn't building big new features. Pull requests for small fixes are welcome if they follow the PR template and Conventional Commits; large feature PRs are unlikely to be merged.

## Data, costs and safety
- Personal data: **yes**. Stored in: SQLite file and attachments in data/ (/var/www/app/data in Docker, the kanboard-data volume), or a MySQL/PostgreSQL database. Plugins live in plugins/. Back up the data folder (or database dump) and plugins folder before updates or code changes. Read the ChangeLog before updating; the database migrates itself on start.
- Service: Email (SMTP or sendmail) (optional, free with most providers): Task notifications, overdue reminders and sending tasks by email.
- Service: LDAP or reverse-proxy login (optional, free (self-hosted)): Sign in with an existing company or home directory account.
- Service: Plugin directory (kanboard.org/plugins.json) (optional, free): Lists third-party plugins when the web plugin installer is switched on (off by default).
- Setting `PLUGIN_INSTALLER`: Set to true to install plugins from the web interface. Off by default for security; plugins run with full access.
- Setting `DATABASE_URL` (**secret**: the person enters it themselves, never in chat): Docker image only. Use MySQL/MariaDB or PostgreSQL instead of SQLite, e.g. mysql://user:password@db/kanboard. Contains a password; never paste it into an AI chat.
- Setting `DB_DRIVER`: sqlite (default), mysql or postgres. Goes with DB_HOSTNAME, DB_NAME, DB_USERNAME and DB_PASSWORD.
- Setting `DB_PASSWORD` (**secret**: the person enters it themselves, never in chat): Database password when not using SQLite. Never paste it into an AI chat.
- Setting `MAIL_TRANSPORT`: How emails are sent (mail, smtp or sendmail). Set MAIL_FROM, MAIL_SMTP_HOSTNAME, MAIL_SMTP_PORT, MAIL_SMTP_USERNAME and MAIL_SMTP_ENCRYPTION too.
- Setting `MAIL_SMTP_PASSWORD` (**secret**: the person enters it themselves, never in chat): Password for your email account. Never paste it into an AI chat.
- Setting `REVERSE_PROXY_AUTH`: Trust a login header from a reverse proxy (Authelia, Authentik…). Only when the proxy is the only way in.
- Setting `DEBUG`: Set to true for detailed logs while troubleshooting. Keep false in normal use.
- Change the default admin / admin password immediately, and use HTTPS if it is reachable from the internet.
- Keep PLUGIN_INSTALLER off unless you need it. Plugins run with full access to your data, so only install ones you trust.
- Custom CSS and Markdown are shown to every user. Only give admin rights to people you trust.
- Upstream treats security reports as ordinary bugs while in maintenance mode, so keep the image updated and don't expose it more than needed.

---

# Customising Kanboard

Kanboard is plain PHP with simple templates, so it is one of the easier apps to change. Even so, **most changes don't need code**: custom CSS, automatic actions, webhooks, the API and plugins cover a lot, and they survive updates.

> Kanboard is in maintenance mode. It is stable and still released, but the author isn't adding big features. Build what you need as settings or a plugin rather than waiting for it upstream.

## Level 1: Settings (no code)
- **Language, time zone, date format, URL:** Settings → Application settings (admins only). 39 languages are included.
- **Your own look:** Settings → Application settings → *Custom stylesheet*. Paste CSS to change colours, fonts, card shapes and spacing for everyone.
- **Light or dark:** each person picks light, dark or automatic in their profile.
- **Board shape:** Project → Configure. Columns (with work-in-progress limits), swimlanes (rows, e.g. one per person), categories with colours, tags.
- **Automatic actions:** Project → Automatic actions. About 25 built-in rules, such as "close the task when it moves to Done", "assign a colour per category", "send the task by email".
- **Recurring tasks:** on a task, set it to come back when it is closed or moved, with a new due date.
- **Server options:** environment variables in Docker, or `config.php` (copy `config.default.php`). In Docker you can also put a `config.php` in the data volume.

## Level 2: Extend (no fork)
- **Notifications:** each user chooses email or web notifications in their profile. Overdue reminders are sent by the `cronjob` command (the Docker image runs it for you).
- **Calendar and feeds:** each project has a private iCal link (add it to your phone calendar) and an RSS feed. Enable *public access* in the project settings to get them.
- **Webhooks:** Settings → Webhooks sends task events as JSON to a URL you choose. Guide: https://docs.kanboard.org/v1/dev/webhooks/
- **JSON-RPC API:** `/jsonrpc.php`. Use the token from Settings → API (application) or a personal access token. Procedures for projects, tasks, subtasks, comments, files and users: https://docs.kanboard.org/v1/api/
- **Plugins:** a folder in `plugins/` with a `Plugin.php`. Plugins can add routes, hooks, automatic actions, helpers, and **override any template**, so you can change a screen without editing core files. Guide: https://docs.kanboard.org/v1/plugins/ (see *overrides* and *hooks*). Plugins run with full access; only install ones you trust.

## Level 3: Code
Read upstream `CONTRIBUTING.md` and the coding standards (PSR-1/PSR-2, four spaces).

| Change | Where |
|---|---|
| Board and cards | `app/Template/board/` |
| Task page | `app/Template/task/`, `app/Controller/Task*Controller.php` |
| Dashboard | `app/Template/dashboard/`, `app/Controller/DashboardController.php` |
| Settings screens | `app/Template/config/`, `app/Controller/ConfigController.php` |
| Logic and data | `app/Model/`, `app/Controller/` |
| New automatic action | `app/Action/` (or better, register one from a plugin) |
| API | `app/Api/Procedure/`, `jsonrpc.php` |
| Database changes | `app/Schema/Sqlite.php`, `Mysql.php` and `Postgres.php` (all three) |
| Styles | `assets/css/src/` then `./cli css` (themes in `assets/css/src/themes/`) |
| JavaScript | `assets/js/src/`, `assets/js/core/`, `assets/js/components/` then `./cli js` |
| Text | `app/Locale/<language>/translations.php` |

## Running locally
- **Just use it:** `docker run -d --name kanboard -p 8080:80 -v kanboard-data:/var/www/app/data -v kanboard-plugins:/var/www/app/plugins kanboard/kanboard:latest`, then open http://localhost:8080 and log in as `admin` / `admin`. Change the password at once. Pin a version tag (e.g. `v1.2.x`) for real use.
- **Develop:**
  1. Install PHP 8.1+ and Composer.
  2. `composer install`
  3. `php -S localhost:8000 -t .`
  4. Open http://localhost:8000 (admin / admin). SQLite is used by default, stored in `data/`.
- **Check:** `make test-sqlite` (PHPUnit) and `jshint ./assets/js/core ./assets/js/components`. Commit messages must follow Conventional Commits if you plan to send a pull request.

## Pitfalls
- Back up `data/` (or your database) and `plugins/` before updating or changing code. Read the ChangeLog first.
- Template edits in `app/Template/` are overwritten by updates. Use a plugin template override instead.
- Schema changes must be written for SQLite, MySQL and PostgreSQL.
- After editing `assets/css/src` or `assets/js/src`, rebuild with `./cli css` / `./cli js`, or nothing changes.

---
Machine-readable: [bespoke.yaml](https://handoff.bespokeai.software/p/kanboard/e197e71/bespoke.yaml) · Agent skill: [SKILL.md](https://handoff.bespokeai.software/p/kanboard/e197e71/SKILL.md)