⚡ Project management that doesn't become the project. Boards, Gantt charts, and GitHub integration. Self-host it or use Kaneo Cloud.
TypeScript honoissue-managementissue-trackerjira-alternativekanbanlinear-alternativemcpproject-managementreactself-hostedtypescript
docs: rebuild guides around current Kaneo workflows (#1814)
Tin Sever2f2bdf314841
diff --git a/.env.sample b/.env.sampleindex f449953bb..e8adc145b 100644--- a/.env.sample+++ b/.env.sample@@ -1,6 +1,6 @@# General URLsKANEO_CLIENT_URL=http://localhost:5173-# KANEO_API_URL=http://localhost:1337 # optional - defaults to KANEO_CLIENT_URL/api+# KANEO_API_URL=http://localhost:1337 # set for host-native API; bundled image derives CLIENT_URL/api# KANEO_INTERNAL_API_URL=http://127.0.0.1:1337 # optional - internal MCP tool requests only# CORS_ORIGINS= # optional - comma-separated; defaults to KANEO_CLIENT_URL@@ -34,7 +34,8 @@ POSTGRES_PASSWORD=# Authentication# Generate with: openssl rand -hex 32-# If unset, a random secret is generated at startup (sessions won't survive restarts)+# Required for host-native startup. Bundled image generates a temporary one if unset.+# Keep it stable: it protects authentication sessions.AUTH_SECRET=# GitHub SSO (Sign in with GitHub, OAuth App)@@ -64,16 +65,16 @@ SMTP_REQUIRE_TLS=# Cloud-mode abuse mitigations (only enable on hosted multi-tenant instances).# When KANEO_CLOUD=true: signup with disposable-email providers is blocked,-# Turnstile is required on /sign-up/email, guest accounts cannot send-# workspace invites, and per-IP rate limits apply to signup + invite paths.+# guest accounts cannot send workspace invites, and tighter rate limits apply.+# Turnstile verification is controlled separately by TURNSTILE_SECRET_KEY.#KANEO_CLOUD=false-# Cloudflare Turnstile (signup captcha). Set the secret key to enforce;+# Cloudflare Turnstile (authentication CAPTCHA). Set the secret key to enforce;# leave unset to skip verification (self-hosted).#TURNSTILE_SECRET_KEY=# Web container: the production image bakes "KANEO_TURNSTILE_SITE_KEY" as a# placeholder and apps/web/env.sh substitutes it at container start from this-# env var. For local dev (vite), set VITE_TURNSTILE_SITE_KEY in apps/web/.env.+# env var. For local dev (vite), set VITE_TURNSTILE_SITE_KEY in apps/web/.env.local.#KANEO_TURNSTILE_SITE_KEY=# Sentry error tracking (Optional): errors are only reported when a DSN is set@@ -95,3 +96,26 @@ SMTP_REQUIRE_TLS=# CREEM_PRODUCT_TEAM_ANNUAL=# BILLING_TRIAL_DAYS=14# BILLING_FOUNDING_CUTOFF= # ISO date; workspaces created on/before keep free access++# Private uploads: Silo or another S3-compatible provider (Optional)+# S3_ENDPOINT=https://files.example.com # reachable by the API and browser+# S3_BUCKET=kaneo+# S3_ACCESS_KEY_ID=+# S3_SECRET_ACCESS_KEY=+# S3_REGION=us-east-1+# S3_FORCE_PATH_STYLE=true+# S3_MAX_IMAGE_UPLOAD_BYTES=10485760+# S3_PRESIGN_TTL_SECONDS=300+# S3_KEY_PREFIX=++# Access policy (Optional)+# DISABLE_REGISTRATION=false+# DISABLE_PASSWORD_REGISTRATION=false+# DISABLE_LOGIN_FORM=false+# DISABLE_GUEST_ACCESS=false+# DISABLE_WORKSPACE_CREATION=false+# DEVICE_AUTH_CLIENT_IDS=kaneo-cli,kaneo-mcp+# KANEO_ALLOW_PRIVATE_WEBHOOK_DESTINATIONS=false++# Required when saving personal notification tokens or signing secrets. Keep stable.+# NOTIFICATION_SECRET_ENCRYPTION_KEY=diff --git a/ENVIRONMENT_SETUP.md b/ENVIRONMENT_SETUP.mdindex b0826d753..9d13d43c5 100644--- a/ENVIRONMENT_SETUP.md+++ b/ENVIRONMENT_SETUP.md@@ -1,238 +1,85 @@-# Environment Setup Guide+# Local development setup-This guide will help you set up the Kaneo development environment and troubleshoot common issues.+Use Node.js 24 or newer and pnpm 10.32.1, as declared in the root `package.json`. You also need a local PostgreSQL database. Redis and object storage are optional.-## Quick Start+## Configure the API-1. **Create a `.env` file** in the root of the project with the required environment variables (see the [documentation](https://kaneo.app/docs/core/installation/environment-variables) for the complete list).+Create `.env` in the repository root. If you copy `.env.sample`, replace its empty secrets and choose a database address that the API can reach.-2. **Start the development servers**:- ```bash- pnpm dev- ```+```env+KANEO_CLIENT_URL=http://localhost:5173+KANEO_API_URL=http://localhost:1337+DATABASE_URL=postgresql://kaneo:YOUR_LOCAL_PASSWORD@localhost:5432/kaneo+AUTH_SECRET=REPLACE_WITH_A_RANDOM_SECRET+```-This starts both the API (port 1337) and web app (port 5173). Both will automatically reload when you make changes.+Generate the authentication secret with `openssl rand -hex 32`. Keep it stable between runs. It protects authentication.-> **Tip**: The web app at http://localhost:5173 will automatically connect to the API at http://localhost:1337+Create the database and user before starting the API. The API applies committed migrations at startup. Use a development database, never a production database.-## Environment Variables+An explicit `DATABASE_URL` takes precedence over `POSTGRES_*`. You do not need both. If you choose derived configuration, set `POSTGRES_PASSWORD` and `POSTGRES_HOST=localhost` for a host-native API. The default hostname `postgres` is for containers sharing a Compose network. `POSTGRES_DB` and `POSTGRES_USER` alone do not enable derivation.-Kaneo uses a **single `.env` file** in the root of the project for all environment variables. This file is shared by both the API and web services.+The bundled Docker image derives `KANEO_API_URL` from `KANEO_CLIENT_URL`. Host-native development does not run that entrypoint, so set the two URLs explicitly as above.-### Required Variables+## Configure the browser-For development, you'll need at minimum:+The API reads the root `.env`. Vite reads frontend overrides from `apps/web/.env.local`.-- `KANEO_CLIENT_URL` - The URL of the web application (e.g., `http://localhost:5173`)-- `KANEO_API_URL` - The URL of the API (e.g., `http://localhost:1337`)-- `AUTH_SECRET` - **Required.** Secret key for JWT token generation (**must be at least 32 characters long**; use a long, random value in production). The API refuses to start without it, because an unset secret would fall back to a publicly known default and make every session cookie forgeable. The Docker entrypoint generates a random one per session if you do not set it, so sessions will not survive a restart until you do. Generate one with `openssl rand -hex 32`.-- `DEVICE_AUTH_CLIENT_IDS` - **Optional.** Comma-separated list of allowed device-flow OAuth client IDs. When unset, Kaneo implicitly allows `kaneo-cli` and `kaneo-mcp` by default (no extra configuration for the CLI or MCP). Override only when you need additional trusted clients, for example `kaneo-cli,kaneo-mcp,my-desktop-app`.-- `DATABASE_URL` - PostgreSQL connection string-- `POSTGRES_DB` - PostgreSQL database name-- `POSTGRES_USER` - PostgreSQL username-- `POSTGRES_PASSWORD` - PostgreSQL password+The default development API address is `http://localhost:1337`. To change it, create:-If your app uses a device client ID that is not included in the defaults, set `DEVICE_AUTH_CLIENT_IDS` to the full comma-separated list of allowed IDs (including any defaults you still need), so it includes the client ID your app sends to `/api/auth/device/code`.+```env+# apps/web/.env.local+VITE_API_URL=http://localhost:1337+```-### Development-Specific Variables+Only put public browser configuration in `VITE_*` variables. Never put database passwords, API keys, or provider secrets there. Restart Vite after changing the file.-For local development, the web app also supports:-- `VITE_API_URL` - API URL for development (defaults to `http://localhost:1337` if not set)-- `VITE_APP_URL` - App URL for generating links (optional)+The production containers use different names: their startup script replaces `KANEO_API_URL`, `KANEO_CLIENT_URL`, and `KANEO_TURNSTILE_SITE_KEY` in the built assets. Editing `VITE_API_URL` in a running container does not change its API address.-### Optional Variables+## Install and start-Kaneo supports many optional configuration options including:-- `KANEO_INTERNAL_API_URL` - API origin used only for server-side requests from the built-in HTTP MCP endpoint. Defaults to `http://127.0.0.1:1337`; override it only if the API is not reachable there from its own process.-- SSO providers (GitHub OAuth via `GITHUB_OAUTH_CLIENT_ID` / `GITHUB_OAUTH_CLIENT_SECRET`, Google, Discord, Custom OAuth/OIDC)-- GitHub repository integration (GitHub App: `GITHUB_APP_ID`, `GITHUB_PRIVATE_KEY`, `GITHUB_WEBHOOK_SECRET`, optional `GITHUB_APP_NAME`), separate from GitHub SSO-- SMTP configuration for email-- Access control settings-- CORS configuration-- Redis for horizontal scaling-- Private-network notification receivers (`KANEO_ALLOW_PRIVATE_WEBHOOK_DESTINATIONS=true` lets ntfy/Gotify/webhook destinations and self-managed Gitea/GitLab instances resolve to private addresses; off by default to prevent SSRF)+From the repository root:-#### Redis Configuration+```bash+pnpm install+pnpm dev+```-Kaneo supports three Redis deployment modes for WebSocket Pub/Sub. When any Redis mode is configured, WebSocket broadcasts use Redis Pub/Sub, allowing multiple API instances to relay real-time updates. When none are set, an in-memory adapter is used (single-instance only).+Open http://localhost:5173. Check API readiness separately:-**Standalone (single server):**-- `REDIS_URL` - Redis connection string (e.g., `redis://localhost:6379`)+```bash+curl --fail http://localhost:1337/api/health+```-**Sentinel (high-availability with automatic failover):**-- `REDIS_SENTINELS` - Comma-separated list of Sentinel nodes (e.g., `sentinel-1:26379,sentinel-2:26379,sentinel-3:26379`)-- `REDIS_SENTINEL_MASTER_NAME` - Name of the Sentinel master group (default: `mymaster`)-- `REDIS_SENTINEL_PASSWORD` - Password for Sentinel instances, if different from the Redis password (optional)-- `REDIS_SENTINEL_TLS` - Set to `true` to enable TLS for Sentinel connections (default: `false`)+The first non-guest account completes instance setup. Keep this local instance private until you have created it.-**Cluster (horizontal sharding):**-- `REDIS_CLUSTER_NODES` - Comma-separated list of cluster seed nodes (e.g., `node-1:6379,node-2:6379,node-3:6379`)+## Optional features-**Shared (used by Sentinel and Cluster modes):**-- `REDIS_PASSWORD` - Password for the Redis data nodes (used by both Sentinel and Cluster modes, not for Sentinel auth itself; use `REDIS_SENTINEL_PASSWORD` for that)+Use the [environment reference](https://kaneo.app/docs/core/installation/environment-variables) for server settings and defaults.-> **Note:** Only one mode should be configured at a time. If multiple are set, the priority is: Cluster > Sentinel > Standalone.+- **Uploads:** configure S3-compatible storage. [Silo](https://kaneo.app/docs/core/installation/silo) is the documented self-hosted option. The API and browser must both reach its endpoint.+- **Email:** configure SMTP. Email verification codes become the default sign-in method; `DISABLE_EMAIL_OTP_SIGN_IN=true` keeps password sign-in. Invitations and password resets still use SMTP.+- **Sign-in providers:** configure OAuth credentials on the API and register the local callback URL with the provider.+- **MCP:** the built-in endpoint uses `KANEO_INTERNAL_API_URL`, defaulting to `http://127.0.0.1:1337`, for internal tool requests. Device authorization allows `kaneo-cli` and `kaneo-mcp` by default.+- **Private-network connections:** `KANEO_ALLOW_PRIVATE_WEBHOOK_DESTINATIONS=true` permits internal ntfy, Gotify, webhook, Gitea, and GitLab destinations. Only enable it on a trusted deployment.+- **Redis:** only needed to relay live updates between multiple API instances. Leave it unset for one local API process.+- **CAPTCHA:** set `TURNSTILE_SECRET_KEY` in the root `.env` and the matching `VITE_TURNSTILE_SITE_KEY` in `apps/web/.env.local`. The secret enables verification independently of cloud mode. Configure a widget that accepts your development hostname.+- **Sentry:** `SENTRY_DSN` enables API reporting. A browser build reads `VITE_SENTRY_DSN`; the current container renderer does not substitute `KANEO_SENTRY_DSN` at runtime. Leave reporting unset if you do not need it.-#### SMTP Configuration--For sending emails (workspace invitations, magic links, etc.), configure these variables:-- `SMTP_HOST` - SMTP server hostname-- `SMTP_PORT` - SMTP server port-- `SMTP_USER` - SMTP username-- `SMTP_PASSWORD` - SMTP password-- `SMTP_FROM` - From email address-- `SMTP_SECURE` - Use TLS immediately (default: `true`, typically port 465). Set to `false` for STARTTLS, typically on port 587.-- `SMTP_REQUIRE_TLS` - Require a STARTTLS upgrade when `SMTP_SECURE=false` (default: `true`). Sending fails if the server cannot upgrade. Only set to `false` for an intentionally unencrypted local development relay.-- `SMTP_IGNORE_TLS` - Removed: `true` is rejected because this option disabled STARTTLS and could send credentials and emails in plaintext.--For a private SMTP certificate authority, configure Node's `NODE_EXTRA_CA_CERTS` with the path to a trusted CA PEM file before starting the API. Fix expired certificates or hostname mismatches instead of bypassing validation. When upgrading an existing installation, remove `SMTP_IGNORE_TLS=true` and check SMTP delivery with the corrected trust configuration before rollout.--When SMTP is configured, sign-in uses email verification codes by default. Set `DISABLE_EMAIL_OTP_SIGN_IN=true` to use email/password sign-in instead (workspace invitation emails still use SMTP).--After initial setup, when `DISABLE_REGISTRATION=true`, sign-in emails (OTP codes and magic links) are only sent to addresses that already have an account or hold a pending workspace invitation — unknown addresses get a generic success response with no email. When `DISABLE_PASSWORD_REGISTRATION=true`, only existing accounts receive them. An empty instance with `DISABLE_REGISTRATION=true` still accepts sign-in emails for any address until the first non-guest account is created.+After initial setup, when `DISABLE_REGISTRATION=true`, sign-in emails (OTP codes and magic links) are only sent to addresses that already have an account or hold a pending workspace invitation; unknown addresses get a generic success response with no email. When `DISABLE_PASSWORD_REGISTRATION=true`, only existing accounts receive them. An empty instance with `DISABLE_REGISTRATION=true` still accepts sign-in emails for any address until the first non-guest account is created.Sign-in email eligibility checks and delivery run in the API process after the request is accepted, so the response does not wait for SMTP. Pending sends are given up to 10 seconds to finish during graceful shutdown; they are not persisted across a process crash.-#### Cloud-mode abuse mitigations--Hosted multi-tenant instances should enable the cloud abuse gates. Self-hosted instances can leave these unset.--- `KANEO_CLOUD` - Set to `true` to enable cloud-only protections: disposable-email signup block, Turnstile captcha enforcement, guest-account invite block, and tightened rate limits on `/sign-up/email` and `/organization/invite-member`.-- `TURNSTILE_SECRET_KEY` - Cloudflare Turnstile secret key (API container, server-side verification). When unset, captcha verification is skipped.-- `KANEO_TURNSTILE_SITE_KEY` - Cloudflare Turnstile site key, on the **web container**. The production web image bakes the literal placeholder `KANEO_TURNSTILE_SITE_KEY` into the bundle; `apps/web/env.sh` swaps it for the runtime value when the container starts.-- `VITE_TURNSTILE_SITE_KEY` - Local dev only. Set in `apps/web/.env` when running `pnpm dev`; Vite reads this at build/dev time. Not used in the production image.--#### Sentry (error monitoring)--All Sentry integration is opt-in; leave these unset for zero telemetry.--- `SENTRY_DSN` - Sentry DSN for the API. When unset, the Sentry SDK never initializes.-- `SENTRY_ENVIRONMENT` - Environment tag for API events (defaults to `NODE_ENV`).-- `SENTRY_TRACES_SAMPLE_RATE` - Fraction of API requests to trace for performance monitoring, `0`-`1` (default: `0`, tracing off).-- `KANEO_SENTRY_DSN` - Sentry DSN for the **web container** (browser errors, tracing, session replay). Same runtime-placeholder mechanism as `KANEO_TURNSTILE_SITE_KEY`.-- `VITE_SENTRY_DSN` - Local dev only. Set in `apps/web/.env` when running `pnpm dev`.--For a complete list of all environment variables, their descriptions, and configuration options, see the [official documentation](https://kaneo.app/docs/core/installation/environment-variables).--## Common Issues & Troubleshooting--### CORS Errors--**Symptoms:**-- "Failed to fetch" errors in browser console-- Network errors when making API requests-- "Access to fetch at '...' from origin '...' has been blocked by CORS policy"--**Solutions:**--1. **Check URL Configuration:**- - Ensure `KANEO_API_URL` matches your API server URL- - Ensure `KANEO_CLIENT_URL` matches your web app URL- - For development, you can also set `VITE_API_URL` in your `.env` file--2. **Configure CORS Origins:**- - Add your frontend URL to `CORS_ORIGINS` in your `.env`:- ```- CORS_ORIGINS=http://localhost:5173,https://yourdomain.com- ```- - In development, unconfigured HTTP CORS may reflect origins. WebSocket connections always require an allowed origin (`KANEO_CLIENT_URL`, `KANEO_API_URL`, or an explicit `CORS_ORIGINS` entry).- - **Note:** `CORS_ORIGINS` should match `KANEO_CLIENT_URL` for proper authentication--3. **Check Protocol Consistency:**- - Ensure both frontend and API use the same protocol (http/https)- - Don't mix http and https in development--4. **Verify Server Accessibility:**- - Test if the API is accessible: `curl http://localhost:1337/config`- - Check if the server is running on the correct port--### Database Connection Issues--**Symptoms:**-- "Database connection failed" errors-- API server won't start--**Solutions:**--1. **Check PostgreSQL:**- - Ensure PostgreSQL is running- - Verify database exists and credentials are correct- - Test connection: `psql $DATABASE_URL`--2. **Update DATABASE_URL:**- - Ensure the connection string format is correct- - Check username, password, host, port, and database name--3. **Match the hostname to where the API runs:**- - Use `postgres` only when the API container is on the same Docker Compose network as the Postgres service- - Use `localhost` when the API runs directly on your host machine- - If you see `getaddrinfo EAI_AGAIN postgres`, the API is trying to resolve the Compose hostname from the wrong network context--4. **Use the right configuration mode:**- - For host-native development, prefer an explicit `DATABASE_URL`- - If you derive from `POSTGRES_*`, set `POSTGRES_HOST=localhost` when running the API on your host- - `POSTGRES_DB` and `POSTGRES_USER` by themselves do not switch Kaneo into derived connection mode--### Authentication Issues--**Symptoms:**-- "Authentication failed" errors-- Users can't sign in--**Solutions:**--1. **Check Authentication Configuration:**- - Ensure `AUTH_SECRET` is set in your `.env` file- - Use a strong secret in production- - Verify `KANEO_CLIENT_URL` and `KANEO_API_URL` are correctly configured--2. **Clear Browser Data:**- - Clear cookies and local storage- - Try in incognito/private mode--### Network Errors--**Symptoms:**-- "Network error" messages-- API requests timeout--**Solutions:**--1. **Check Server Status:**- - Verify API server is running- - Check server logs for errors--2. **Check Firewall/Proxy:**- - Ensure ports are not blocked- - Check if proxy settings interfere--3. **Verify URLs:**- - Check that all URLs are accessible- - Test with curl or browser--## Development vs Production--### Development-- Use `http://localhost` for both frontend and API-- Set `KANEO_CLIENT_URL` and `KANEO_API_URL` to your local URLs; list any additional frontend origins in `CORS_ORIGINS`. WebSocket origins are checked even in development (defaults are `http://localhost:5173` and `http://localhost:1337` when the corresponding URL is unset).-- Use simple secrets for `AUTH_SECRET` (not for production)-- The web app will use `VITE_API_URL` if set, otherwise defaults to `http://localhost:1337`--### Production-- Use HTTPS for both frontend and API-- Set specific `CORS_ORIGINS` for security (should match `KANEO_CLIENT_URL`)-- Use strong, unique secrets for `AUTH_SECRET`-- Configure proper database credentials-- Ensure `KANEO_CLIENT_URL` and `KANEO_API_URL` are set to your production URLs--## Getting Help--If you're still experiencing issues:+## Troubleshooting-1. Check the browser console for detailed error messages-2. Review the API server logs-3. Verify all environment variables are set correctly-4. Ensure all services (PostgreSQL, API, Frontend) are running-5. Consult the [official documentation](https://kaneo.app/docs) for detailed guides and troubleshooting+| Symptom | Check |+| --- | --- |+| API cannot resolve `postgres` | Use `localhost` in the database URL when the API runs on your host. |+| Database authentication fails | Confirm the database exists and the URL matches its actual user and password. |+| Browser requests reach the wrong API | Check `apps/web/.env.local`, then restart Vite. |+| CORS or WebSocket origin error | Set `KANEO_CLIENT_URL` to the exact browser origin. Put additional allowed origins in the comma-separated `CORS_ORIGINS` value. |+| OAuth returns to the wrong address | Check `KANEO_API_URL` and the provider callback URL. |+| Sign-in breaks after restarting | Keep `AUTH_SECRET` unchanged and ensure every API process uses the same value. |+| Upload URL cannot be reached | Use an endpoint the browser can resolve, not a Docker-only storage hostname. |-For the most up-to-date information on environment variables and configuration, always refer to the [official documentation](https://kaneo.app/docs/core/installation/environment-variables).+For deployed instances, use the [self-hosting guide](https://kaneo.app/docs/core/installation) and [operations troubleshooting](https://kaneo.app/docs/core/operations/troubleshooting).diff --git a/apps/docs/CONTRIBUTING.md b/apps/docs/CONTRIBUTING.mdindex 8863ee48f..b87fba296 100644--- a/apps/docs/CONTRIBUTING.md+++ b/apps/docs/CONTRIBUTING.md@@ -1,34 +1,29 @@-> **Customize this file**: Tailor this template to your project by noting specific contribution types you're looking for, adding a Code of Conduct, or adjusting the writing guidelines to match your style.+# Contribute to the docs-# Contribute to the documentation+Read the implementation behind a feature before documenting it. Test the instructions from the reader's starting point, including how they get any IDs, credentials, or files the example needs.-Thank you for your interest in contributing to our documentation! This guide will help you get started.+## Write for the person doing the work-## How to contribute+- Use everyday English, short paragraphs, and sentence-case headings.+- Start with what the reader can accomplish and what they need first.+- Use the actual labels in the interface. Explain a term before relying on it.+- Avoid marketing filler, unnecessary warnings, and em dashes.+- Explain the result of an action, plus how to change or undo it when relevant.+- Keep setup tutorials separate from detailed configuration references.+- Use example.com domains and fictional people. Never include live credentials or private project data.-### Option 1: Edit directly on GitHub+## Add useful images-1. Navigate to the page you want to edit-2. Click the "Edit this file" button (the pencil icon)-3. Make your changes and submit a pull request+Use real app screenshots with fictional data. Include both themes where available, descriptive alt text, and a caption that tells readers what to notice. Put the image next to the step it explains. Use diagrams for system relationships instead of inventing screenshots of an interface.-### Option 2: Local development+See [the screenshot guide](images/product/README.md) for reproduction. Verify the page at desktop and mobile widths, and check that the right screenshot appears in each theme.-1. Fork and clone this repository-2. Install the Mintlify CLI: `npm i -g mint`-3. Create a branch for your changes-4. Make changes-5. Navigate to the docs directory and run `mint dev`-6. Preview your changes at `http://localhost:3000`-7. Commit your changes and submit a pull request+## Check your change-For more details on local development, see our [development guide](development.mdx).+From `apps/docs`, run `pnpm dlx mint validate` and `pnpm dlx mint broken-links`. Preview with `pnpm dlx mint dev` and follow the updated navigation and instructions in a browser.-## Writing guidelines+Keep existing page URLs where possible. When a URL must change, add a redirect in `docs.json` and update internal links. Add new guide pages to the appropriate navigation group.-- **Use active voice**: "Run the command" not "The command should be run"-- **Address the reader directly**: Use "you" instead of "the user"-- **Keep sentences concise**: Aim for one idea per sentence-- **Lead with the goal**: Start instructions with what the user wants to accomplish-- **Use consistent terminology**: Don't alternate between synonyms for the same concept-- **Include examples**: Show, don't just tell+API route and schema changes require `pnpm openapi:check:fix` from the repository root. Do not hand-edit generated endpoint contracts to conceal a mismatch. Older links under `api-reference/endpoints/` are kept as thin pages pointing at the same schema; update their method and path when a route moves, and let OpenAPI supply their descriptions.++In your pull request, say which instructions you executed and which you only reviewed. A successful docs build does not prove an installation or restore works.diff --git a/apps/docs/README.md b/apps/docs/README.mdindex 9c923c38b..9d6b0e2b1 100644--- a/apps/docs/README.md+++ b/apps/docs/README.md@@ -1,33 +1,26 @@-# Kaneo Mintlify Docs+# Kaneo documentation-This directory contains Kaneo documentation powered by Mintlify.+The docs are authored in MDX and rendered by Mintlify. `docs.json` owns navigation; `openapi.json` supplies the generated API reference.-## Monorepo setup+## Preview and validate-- Repository: `kaneo`-- Docs root for Mintlify: `/apps/docs`-- Main config: `apps/docs/docs.json`-- OpenAPI source file: `apps/docs/openapi.json`--## Local preview--1. Install Mintlify CLI:+From `apps/docs`:```bash-npm i -g mint+pnpm dlx mint dev+pnpm dlx mint validate+pnpm dlx mint broken-links```-2. Run from this directory:+The preview runs at `http://localhost:3000`. Use `--port 3107` if that port is busy. Search in the local preview may require a Mintlify login.-```bash-mint dev-```+## Organization-3. Open `http://localhost:3000`.+- **Using Kaneo:** first project, task views, team management, account settings.+- **Self-hosting:** installation, configuration, sign-in, backups, upgrades, troubleshooting.+- **Integrations:** repositories, team channels, webhooks, and MCP.+- **Developers:** first API request, authentication, protocol details, endpoint reference.-## Content structure+Existing `core/` page paths are retained so external links keep working. Put a page in the navigation where readers expect to find it rather than moving its URL for cosmetic consistency.-- `index.mdx`: docs landing page-- `core/**`: product and deployment guides-- `api-reference/**`: overview/auth pages-- API endpoints are generated from the local OpenAPI file in `docs.json`+See [CONTRIBUTING.md](CONTRIBUTING.md) for writing and image guidelines. Product captures and regeneration instructions live in [images/product/README.md](images/product/README.md).diff --git a/apps/docs/api-reference/authentication.mdx b/apps/docs/api-reference/authentication.mdxindex e4cf3bb4d..422a8e938 100644--- a/apps/docs/api-reference/authentication.mdx+++ b/apps/docs/api-reference/authentication.mdx@@ -1,101 +1,44 @@----title: Authentication-description: Learn how to authenticate API requests using API keys or the device authorization flow+title: "Authentication"+description: "Use an API key for scripts or device authorization for interactive clients."---+Most application requests need an `Authorization: Bearer` credential. Your credential is still subject to workspace membership and permissions.-All API endpoints require authentication. Kaneo currently supports two authentication patterns for API access:+## API keys-- API keys for scripts, services, and long-lived integrations-- Device authorization for CLIs and external apps that need browser-based sign-in+1. Sign in and open **Settings → Account → API Keys**, under the Developer section.+2. Create a key and give it a name that identifies the script or service using it.+3. Copy the full key when it is shown. You cannot retrieve it again later.+4. Store it in a secret manager or private environment variable.-## Choose an Authentication Method--### API keys--Use API keys when you control secret storage and want a stable credential for a single Kaneo instance.--### Device authorization--Use the device flow when you are building a CLI, desktop app, or other client that should send the user to the browser to approve access.--The device flow follows RFC 8628 and returns a Bearer token that can be used against that Kaneo instance's API.--## Creating an API Key--<Steps>-<Step>-**Sign in to Kaneo**--Sign in to your Kaneo instance using your account credentials.-</Step>--<Step>-**Navigate to Settings**--Go to your account settings by clicking on your profile or navigating to the Settings page.-</Step>--<Step>-**Open the Account Tab**--In the Settings page, click on the **Account** tab to view your account settings.-</Step>--<Step>-**Access API Keys Section**--Scroll down to the **API Keys** section in the Account tab. This section is located under the Developer Settings.-</Step>--<Step>-**Create a New API Key**--Click the **Create API Key** button to generate a new API key. You'll be prompted to provide a name for your API key to help you identify it later.-</Step>--<Step>-**Save Your API Key**--After creating the API key, you'll be shown the full API key value. **Copy and save this key immediately** - it will not be shown again for security reasons.--<Warning>-**Important**: Store your API key securely. If you lose it, you'll need to create a new one. The API key cannot be retrieved after creation.-</Warning>-</Step>-</Steps>--## Using Your API Key--Once you have your API key, include it in the `Authorization` header of all API requests using the Bearer token format:+Send it with each request:```bash-Authorization: Bearer your-api-key-here+curl --fail-with-body 'https://kaneo.example.com/api/task/tasks/PROJECT_ID' \+ -H "Authorization: Bearer $KANEO_API_KEY"```-### Example Request+Replace `PROJECT_ID` with the ID from a project URL. See [Make your first API request](/api-reference/introduction) for the complete sequence.-Here's an example of making an authenticated API request using curl:+### JavaScript on a server-```bash-curl -X GET https://your-kaneo-instance.com/api/task?workspaceId=your-workspace-id \- -H "Authorization: Bearer your-api-key-here" \- -H "Content-Type: application/json"+```javascript+const response = await fetch(+ 'https://kaneo.example.com/api/task/tasks/PROJECT_ID',+ { headers: { Authorization: `Bearer ${process.env.KANEO_API_KEY}` } }+);+if (!response.ok) {+ throw new Error(`Kaneo request failed: ${response.status}`);+}+const board = await response.json();```-### Example with JavaScript+### Revoke or rotate a key-```javascript-const response = await fetch('https://your-kaneo-instance.com/api/task?workspaceId=your-workspace-id', {- method: 'GET',- headers: {- 'Authorization': 'Bearer your-api-key-here',- 'Content-Type': 'application/json'- }-});-```+Return to **API Keys** to remove a credential you no longer use. To rotate one, create a replacement, update the service that uses it, check a request succeeds, then revoke the old key.-## Using Device Authorization+## Device authorizationBy default, self-hosted Kaneo allows the built-in device clients `kaneo-cli` and `kaneo-mcp`.@@ -113,9 +56,9 @@ If you want to use a different device client ID, the instance operator must allo### Request a device code```bash-curl -X POST https://your-kaneo-instance.com/api/auth/device/code \+curl -X POST https://kaneo.example.com/api/auth/device/code \-H "Content-Type: application/json" \- -d '{"client_id":"your-app-id"}'+ -d '{"client_id":"kaneo-cli"}'```Example response:@@ -124,8 +67,8 @@ Example response:{"device_code": "dev_123","user_code": "ABCD-1234",- "verification_uri": "https://your-kaneo-instance.com/device",- "verification_uri_complete": "https://your-kaneo-instance.com/device?user_code=ABCD-1234",+ "verification_uri": "https://kaneo.example.com/device",+ "verification_uri_complete": "https://kaneo.example.com/device?user_code=ABCD-1234","interval": 5,"expires_in": 600}@@ -134,12 +77,12 @@ Example response:### Poll for a token```bash-curl -X POST https://your-kaneo-instance.com/api/auth/device/token \+curl -X POST https://kaneo.example.com/api/auth/device/token \-H "Content-Type: application/json" \-d '{"grant_type":"urn:ietf:params:oauth:grant-type:device_code","device_code":"dev_123",- "client_id":"your-app-id"+ "client_id":"kaneo-cli"}'```@@ -162,20 +105,15 @@ Once approved, Kaneo returns an access token:### Use the returned token```bash-curl -X GET https://your-kaneo-instance.com/api/task?workspaceId=your-workspace-id \+curl -X GET https://kaneo.example.com/api/task/tasks/PROJECT_ID \-H "Authorization: Bearer your-access-token"```-## Security Best Practices-- **Keep your API keys secret**: Never commit API keys to version control or share them publicly-- **Use descriptive names**: Name your API keys clearly so you can identify their purpose (e.g., "Production Script", "Development Testing")-- **Rotate keys regularly**: Periodically create new API keys and revoke old ones-- **Limit key scope**: Only grant API keys to trusted applications and services-- **Monitor usage**: Regularly review your API keys and remove any that are no longer needed-- **Allow only trusted device clients**: Keep `DEVICE_AUTH_CLIENT_IDS` limited to approved client IDs on self-hosted deployments-- **Treat Bearer device tokens like secrets**: Do not print or log them unnecessarily in production clients+The examples use the built-in `kaneo-cli` client ID so they work with the default allowlist. A separately named client needs its own allowed ID in `DEVICE_AUTH_CLIENT_IDS`.++Respect the polling interval returned by the server. On `slow_down`, increase the interval; stop when the code expires or access is denied. Do not log device codes or access tokens.++## Keep credentials private-<Warning>-If you suspect your API key has been compromised, immediately revoke it in the API Keys section and create a new one.-</Warning>+Use a different key for each integration so you can revoke one without interrupting the others. If a key leaks, revoke it immediately and replace it in the affected service. Device access tokens are secrets too.diff --git a/apps/docs/api-reference/endpoints/activity/createActivity.mdx b/apps/docs/api-reference/endpoints/activity/createActivity.mdxindex 30340703b..a3f2df857 100644--- a/apps/docs/api-reference/endpoints/activity/createActivity.mdx+++ b/apps/docs/api-reference/endpoints/activity/createActivity.mdx@@ -1,5 +1,4 @@----title: createActivity-description: Create a new activity (system-generated event)-openapi: 'POST /activity/create'+title: "Create activity"+openapi: "POST /activity/create"---diff --git a/apps/docs/api-reference/endpoints/activity/createComment.mdx b/apps/docs/api-reference/endpoints/activity/createComment.mdxindex ecc00605e..d33c2b443 100644--- a/apps/docs/api-reference/endpoints/activity/createComment.mdx+++ b/apps/docs/api-reference/endpoints/activity/createComment.mdx@@ -1,5 +1,4 @@----title: createComment-description: Create a new comment on a task-openapi: 'POST /activity/comment'+title: "Create comment"+openapi: "POST /activity/comment"---diff --git a/apps/docs/api-reference/endpoints/activity/deleteComment.mdx b/apps/docs/api-reference/endpoints/activity/deleteComment.mdxindex f1c7869e5..899cba05d 100644--- a/apps/docs/api-reference/endpoints/activity/deleteComment.mdx+++ b/apps/docs/api-reference/endpoints/activity/deleteComment.mdx@@ -1,5 +1,4 @@----title: deleteComment-description: Delete a comment-openapi: 'DELETE /activity/comment'+title: "Delete comment"+openapi: "DELETE /activity/comment"---diff --git a/apps/docs/api-reference/endpoints/activity/getActivities.mdx b/apps/docs/api-reference/endpoints/activity/getActivities.mdxindex cd8722ba3..3431082df 100644--- a/apps/docs/api-reference/endpoints/activity/getActivities.mdx+++ b/apps/docs/api-reference/endpoints/activity/getActivities.mdx@@ -1,5 +1,4 @@----title: getActivities-description: Get all activities for a specific task-openapi: 'GET /activity/{taskId}'+title: "Get task activity"+openapi: "GET /activity/{taskId}"---diff --git a/apps/docs/api-reference/endpoints/activity/updateComment.mdx b/apps/docs/api-reference/endpoints/activity/updateComment.mdxindex 630964eb1..2575e691d 100644--- a/apps/docs/api-reference/endpoints/activity/updateComment.mdx+++ b/apps/docs/api-reference/endpoints/activity/updateComment.mdx@@ -1,5 +1,4 @@----title: updateComment-description: Update an existing comment-openapi: 'PUT /activity/comment'+title: "Update comment"+openapi: "PUT /activity/comment"---diff --git a/apps/docs/api-reference/endpoints/columns/createColumn.mdx b/apps/docs/api-reference/endpoints/columns/createColumn.mdxindex 001a08eed..28a2ac208 100644--- a/apps/docs/api-reference/endpoints/columns/createColumn.mdx+++ b/apps/docs/api-reference/endpoints/columns/createColumn.mdx@@ -1,5 +1,4 @@----title: createColumn-description: Create a new column in a project-openapi: 'POST /column/{projectId}'+title: "Create column"+openapi: "POST /column/{projectId}"---diff --git a/apps/docs/api-reference/endpoints/columns/deleteColumn.mdx b/apps/docs/api-reference/endpoints/columns/deleteColumn.mdxindex 4dfe3123d..d398c89e4 100644--- a/apps/docs/api-reference/endpoints/columns/deleteColumn.mdx+++ b/apps/docs/api-reference/endpoints/columns/deleteColumn.mdx@@ -1,5 +1,4 @@----title: deleteColumn-description: Delete a column-openapi: 'DELETE /column/{id}'+title: "Delete column"+openapi: "DELETE /column/{id}"---diff --git a/apps/docs/api-reference/endpoints/columns/getColumns.mdx b/apps/docs/api-reference/endpoints/columns/getColumns.mdxindex 08475de83..46cac522b 100644--- a/apps/docs/api-reference/endpoints/columns/getColumns.mdx+++ b/apps/docs/api-reference/endpoints/columns/getColumns.mdx@@ -1,5 +1,4 @@----title: getColumns-description: Get all columns for a project-openapi: 'GET /column/{projectId}'+title: "Get columns"+openapi: "GET /column/{projectId}"---diff --git a/apps/docs/api-reference/endpoints/columns/reorderColumns.mdx b/apps/docs/api-reference/endpoints/columns/reorderColumns.mdxindex 4512838c3..a13213246 100644--- a/apps/docs/api-reference/endpoints/columns/reorderColumns.mdx+++ b/apps/docs/api-reference/endpoints/columns/reorderColumns.mdx@@ -1,5 +1,4 @@----title: reorderColumns-description: Reorder columns in a project-openapi: 'PUT /column/reorder/{projectId}'+title: "Reorder columns"+openapi: "PUT /column/reorder/{projectId}"---diff --git a/apps/docs/api-reference/endpoints/columns/updateColumn.mdx b/apps/docs/api-reference/endpoints/columns/updateColumn.mdxindex ad9d24acc..7157f7b59 100644--- a/apps/docs/api-reference/endpoints/columns/updateColumn.mdx+++ b/apps/docs/api-reference/endpoints/columns/updateColumn.mdx@@ -1,5 +1,4 @@----title: updateColumn-description: Update a column-openapi: 'PUT /column/{id}'+title: "Update column"+openapi: "PUT /column/{id}"---diff --git a/apps/docs/api-reference/endpoints/config/getConfig.mdx b/apps/docs/api-reference/endpoints/config/getConfig.mdxindex 2a6833ac7..6a421ef2a 100644--- a/apps/docs/api-reference/endpoints/config/getConfig.mdx+++ b/apps/docs/api-reference/endpoints/config/getConfig.mdx@@ -1,5 +1,4 @@----title: getConfig-description: Get application settings and configuration-openapi: 'GET /config'+title: "Get config"+openapi: "GET /config"---diff --git a/apps/docs/api-reference/endpoints/external-links/getExternalLinksByTask.mdx b/apps/docs/api-reference/endpoints/external-links/getExternalLinksByTask.mdxindex fe56ba9da..bcee58cd8 100644--- a/apps/docs/api-reference/endpoints/external-links/getExternalLinksByTask.mdx+++ b/apps/docs/api-reference/endpoints/external-links/getExternalLinksByTask.mdx@@ -1,5 +1,4 @@----title: getExternalLinksByTask-description: Get all external links for a task-openapi: 'GET /external-link/task/{taskId}'+title: "Get task external links"+openapi: "GET /external-link/task/{taskId}"---diff --git a/apps/docs/api-reference/endpoints/github/createGitHubIntegration.mdx b/apps/docs/api-reference/endpoints/github/createGitHubIntegration.mdxindex 0294d18aa..01407c086 100644--- a/apps/docs/api-reference/endpoints/github/createGitHubIntegration.mdx+++ b/apps/docs/api-reference/endpoints/github/createGitHubIntegration.mdx@@ -1,8 +1,6 @@----title: createGitHubIntegration-description: Create a new GitHub integration for a project-openapi: 'POST /github-integration/project/{projectId}'+title: "Create GitHub integration"+openapi: "POST /github-integration/project/{projectId}"-----Connecting a different repository while one is already linked returns **409**. Disconnect the current integration first so its old issue and pull-request numbers cannot be reused against the new repository. Local tasks remain; old external links and saved import progress are removed by disconnecting. Reverification of the same numeric repository preserves existing links and preferences, including when its name or installation changes. Concurrent configuration changes also return409; refresh before retrying.+Connecting a different repository while one is already linked returns **409**. Disconnect the current integration first so its old issue and pull-request numbers cannot be reused against the new repository. Local tasks remain; old external links and saved import progress are removed by disconnecting. Reverification of the same numeric repository preserves existing links and preferences, including when its name or installation changes. Concurrent configuration changes also return 409; refresh before retrying.diff --git a/apps/docs/api-reference/endpoints/github/deleteGitHubIntegration.mdx b/apps/docs/api-reference/endpoints/github/deleteGitHubIntegration.mdxindex 146fd8363..d738bc961 100644--- a/apps/docs/api-reference/endpoints/github/deleteGitHubIntegration.mdx+++ b/apps/docs/api-reference/endpoints/github/deleteGitHubIntegration.mdx@@ -1,5 +1,4 @@----title: deleteGitHubIntegration-description: Delete GitHub integration for a project-openapi: 'DELETE /github-integration/project/{projectId}'+title: "Delete GitHub integration"+openapi: "DELETE /github-integration/project/{projectId}"---diff --git a/apps/docs/api-reference/endpoints/github/getGitHubAppInfo.mdx b/apps/docs/api-reference/endpoints/github/getGitHubAppInfo.mdxindex da3f55dda..a907c82e1 100644--- a/apps/docs/api-reference/endpoints/github/getGitHubAppInfo.mdx+++ b/apps/docs/api-reference/endpoints/github/getGitHubAppInfo.mdx@@ -1,5 +1,4 @@----title: getGitHubAppInfo-description: Get GitHub app configuration information-openapi: 'GET /github-integration/app-info'+title: "Get GitHub app info"+openapi: "GET /github-integration/app-info"---diff --git a/apps/docs/api-reference/endpoints/github/getGitHubIntegration.mdx b/apps/docs/api-reference/endpoints/github/getGitHubIntegration.mdxindex aaf6a0c61..baec27164 100644--- a/apps/docs/api-reference/endpoints/github/getGitHubIntegration.mdx+++ b/apps/docs/api-reference/endpoints/github/getGitHubIntegration.mdx@@ -1,5 +1,4 @@----title: getGitHubIntegration-description: Get GitHub integration for a project-openapi: 'GET /github-integration/project/{projectId}'+title: "Get GitHub integration"+openapi: "GET /github-integration/project/{projectId}"---diff --git a/apps/docs/api-reference/endpoints/github/importGitHubIssues.mdx b/apps/docs/api-reference/endpoints/github/importGitHubIssues.mdxindex 6b44368fa..4d03eefe4 100644--- a/apps/docs/api-reference/endpoints/github/importGitHubIssues.mdx+++ b/apps/docs/api-reference/endpoints/github/importGitHubIssues.mdx@@ -1,10 +1,8 @@----title: importGitHubIssues-description: Import GitHub issues as tasks-openapi: 'POST /github-integration/import-issues'+title: "Import GitHub issues"+openapi: "POST /github-integration/import-issues"----This endpoint processes at most four provider pages per request. It returns **202** while work remains and **200** when the run is complete. Send the returned `runId` with the same `projectId` on each continuation. Retrying a completed `runId` returns its final summary without starting another run.Without `runId`, the endpoint resumes an unfinished run or starts a new run after the previous one completes. `GET /github-integration/project/{projectId}` exposes the saved `importProgress` summary, including its `runId` and `pending` flag. Provider cursors remain on the server. Workspace access and task creation permission are checked on every request.diff --git a/apps/docs/api-reference/endpoints/github/listGitHubRepositories.mdx b/apps/docs/api-reference/endpoints/github/listGitHubRepositories.mdxindex e84b82e5d..4802621c4 100644--- a/apps/docs/api-reference/endpoints/github/listGitHubRepositories.mdx+++ b/apps/docs/api-reference/endpoints/github/listGitHubRepositories.mdx@@ -1,5 +1,4 @@----title: listGitHubRepositories-description: List all accessible GitHub repositories-openapi: 'GET /github-integration/repositories'+title: "List GitHub repositories"+openapi: "GET /github-integration/repositories/{projectId}"---diff --git a/apps/docs/api-reference/endpoints/github/updateGitHubIntegration.mdx b/apps/docs/api-reference/endpoints/github/updateGitHubIntegration.mdxindex 14c5e4e96..fde86f718 100644--- a/apps/docs/api-reference/endpoints/github/updateGitHubIntegration.mdx+++ b/apps/docs/api-reference/endpoints/github/updateGitHubIntegration.mdx@@ -1,5 +1,4 @@----title: updateGitHubIntegration-description: Update GitHub integration settings-openapi: 'PATCH /github-integration/project/{projectId}'+title: "Update GitHub integration"+openapi: "PATCH /github-integration/project/{projectId}"---diff --git a/apps/docs/api-reference/endpoints/github/verifyGitHubInstallation.mdx b/apps/docs/api-reference/endpoints/github/verifyGitHubInstallation.mdxindex 56772f0ac..99a70e18f 100644--- a/apps/docs/api-reference/endpoints/github/verifyGitHubInstallation.mdx+++ b/apps/docs/api-reference/endpoints/github/verifyGitHubInstallation.mdx@@ -1,5 +1,4 @@----title: verifyGitHubInstallation-description: Verify GitHub app installation for a repository-openapi: 'POST /github-integration/verify'+title: "Verify GitHub installation"+openapi: "POST /github-integration/verify"---diff --git a/apps/docs/api-reference/endpoints/invitations/getInvitationDetails.mdx b/apps/docs/api-reference/endpoints/invitations/getInvitationDetails.mdxindex 36d58369d..0a8ab378c 100644--- a/apps/docs/api-reference/endpoints/invitations/getInvitationDetails.mdx+++ b/apps/docs/api-reference/endpoints/invitations/getInvitationDetails.mdx@@ -1,5 +1,4 @@----title: getInvitationDetails-description: Get details of a specific invitation by ID-openapi: 'GET /invitation/{id}'+title: "Get invitation details"+openapi: "GET /invitation/{id}"---diff --git a/apps/docs/api-reference/endpoints/invitations/getUserPendingInvitations.mdx b/apps/docs/api-reference/endpoints/invitations/getUserPendingInvitations.mdxindex 25eba9c32..0cc4efa25 100644--- a/apps/docs/api-reference/endpoints/invitations/getUserPendingInvitations.mdx+++ b/apps/docs/api-reference/endpoints/invitations/getUserPendingInvitations.mdx@@ -1,5 +1,4 @@----title: getUserPendingInvitations-description: Get all pending invitations for the current user-openapi: 'GET /invitation/pending'+title: "Get pending invitations"+openapi: "GET /invitation/pending"---diff --git a/apps/docs/api-reference/endpoints/labels/createLabel.mdx b/apps/docs/api-reference/endpoints/labels/createLabel.mdxindex adc9cb5b3..05b51b6ca 100644--- a/apps/docs/api-reference/endpoints/labels/createLabel.mdx+++ b/apps/docs/api-reference/endpoints/labels/createLabel.mdx@@ -1,5 +1,4 @@----title: createLabel-description: Create a new label in a workspace-openapi: 'POST /label'+title: "Create label"+openapi: "POST /label"---diff --git a/apps/docs/api-reference/endpoints/labels/deleteLabel.mdx b/apps/docs/api-reference/endpoints/labels/deleteLabel.mdxindex d8edbd962..0f945aee8 100644--- a/apps/docs/api-reference/endpoints/labels/deleteLabel.mdx+++ b/apps/docs/api-reference/endpoints/labels/deleteLabel.mdx@@ -1,7 +1,6 @@----title: deleteLabel-description: Delete a label by ID-openapi: 'DELETE /label/{id}'+title: "Delete label"+openapi: "DELETE /label/{id}"---Workspace label deletion runs in steps of at most 25 task assignments. After adiff --git a/apps/docs/api-reference/endpoints/labels/getLabel.mdx b/apps/docs/api-reference/endpoints/labels/getLabel.mdxindex 611763a19..6a75c8ba5 100644--- a/apps/docs/api-reference/endpoints/labels/getLabel.mdx+++ b/apps/docs/api-reference/endpoints/labels/getLabel.mdx@@ -1,5 +1,4 @@----title: getLabel-description: Get a specific label by ID-openapi: 'GET /label/{id}'+title: "Get label"+openapi: "GET /label/{id}"---diff --git a/apps/docs/api-reference/endpoints/labels/getTaskLabels.mdx b/apps/docs/api-reference/endpoints/labels/getTaskLabels.mdxindex 6488815c1..9e6a2630e 100644--- a/apps/docs/api-reference/endpoints/labels/getTaskLabels.mdx+++ b/apps/docs/api-reference/endpoints/labels/getTaskLabels.mdx@@ -1,5 +1,4 @@----title: getTaskLabels-description: Get all labels assigned to a specific task-openapi: 'GET /label/task/{taskId}'+title: "Get task labels"+openapi: "GET /label/task/{taskId}"---diff --git a/apps/docs/api-reference/endpoints/labels/getWorkspaceLabels.mdx b/apps/docs/api-reference/endpoints/labels/getWorkspaceLabels.mdxindex 30867faa3..e71422068 100644--- a/apps/docs/api-reference/endpoints/labels/getWorkspaceLabels.mdx+++ b/apps/docs/api-reference/endpoints/labels/getWorkspaceLabels.mdx@@ -1,5 +1,4 @@----title: getWorkspaceLabels-description: Get all labels for a specific workspace-openapi: 'GET /label/workspace/{workspaceId}'+title: "Get workspace labels"+openapi: "GET /label/workspace/{workspaceId}"---diff --git a/apps/docs/api-reference/endpoints/labels/updateLabel.mdx b/apps/docs/api-reference/endpoints/labels/updateLabel.mdxindex bd20b8419..da7594679 100644--- a/apps/docs/api-reference/endpoints/labels/updateLabel.mdx+++ b/apps/docs/api-reference/endpoints/labels/updateLabel.mdx@@ -1,5 +1,4 @@----title: updateLabel-description: Update an existing label-openapi: 'PUT /label/{id}'+title: "Update label"+openapi: "PUT /label/{id}"---diff --git a/apps/docs/api-reference/endpoints/notifications/clearAllNotifications.mdx b/apps/docs/api-reference/endpoints/notifications/clearAllNotifications.mdxindex 1b1f67f7e..1b6b4ca6d 100644--- a/apps/docs/api-reference/endpoints/notifications/clearAllNotifications.mdx+++ b/apps/docs/api-reference/endpoints/notifications/clearAllNotifications.mdx@@ -1,5 +1,4 @@----title: clearAllNotifications-description: Clear all notifications for the current user-openapi: 'DELETE /notification/clear-all'+title: "Clear all"+openapi: "DELETE /notification/clear-all"---diff --git a/apps/docs/api-reference/endpoints/notifications/createNotification.mdx b/apps/docs/api-reference/endpoints/notifications/createNotification.mdxindex 15c96ae7d..74ecf764e 100644--- a/apps/docs/api-reference/endpoints/notifications/createNotification.mdx+++ b/apps/docs/api-reference/endpoints/notifications/createNotification.mdx@@ -1,5 +1,4 @@----title: createNotification-description: Create a new notification for a user-openapi: 'POST /notification'+title: "Create notification"+openapi: "POST /notification"---diff --git a/apps/docs/api-reference/endpoints/notifications/listNotifications.mdx b/apps/docs/api-reference/endpoints/notifications/listNotifications.mdxindex 4817b6650..3b1307e57 100644--- a/apps/docs/api-reference/endpoints/notifications/listNotifications.mdx+++ b/apps/docs/api-reference/endpoints/notifications/listNotifications.mdx@@ -1,5 +1,4 @@----title: listNotifications-description: Get all notifications for the current user-openapi: 'GET /notification'+title: "List notifications"+openapi: "GET /notification"---diff --git a/apps/docs/api-reference/endpoints/notifications/markAllNotificationsAsRead.mdx b/apps/docs/api-reference/endpoints/notifications/markAllNotificationsAsRead.mdxindex e4bdc1f86..140a98c17 100644--- a/apps/docs/api-reference/endpoints/notifications/markAllNotificationsAsRead.mdx+++ b/apps/docs/api-reference/endpoints/notifications/markAllNotificationsAsRead.mdx@@ -1,5 +1,4 @@----title: markAllNotificationsAsRead-description: Mark all notifications as read for the current user-openapi: 'PATCH /notification/read-all'+title: "Mark all read"+openapi: "PATCH /notification/read-all"---diff --git a/apps/docs/api-reference/endpoints/notifications/markNotificationAsRead.mdx b/apps/docs/api-reference/endpoints/notifications/markNotificationAsRead.mdxindex 7edc59259..dca3a971b 100644--- a/apps/docs/api-reference/endpoints/notifications/markNotificationAsRead.mdx+++ b/apps/docs/api-reference/endpoints/notifications/markNotificationAsRead.mdx@@ -1,5 +1,4 @@----title: markNotificationAsRead-description: Mark a specific notification as read-openapi: 'PATCH /notification/{id}/read'+title: "Mark notification read"+openapi: "PATCH /notification/{id}/read"---diff --git a/apps/docs/api-reference/endpoints/projects/createProject.mdx b/apps/docs/api-reference/endpoints/projects/createProject.mdxindex 238492551..e818a11a6 100644--- a/apps/docs/api-reference/endpoints/projects/createProject.mdx+++ b/apps/docs/api-reference/endpoints/projects/createProject.mdx@@ -1,5 +1,4 @@----title: createProject-description: Create a new project in a workspace-openapi: 'POST /project'+title: "Create project"+openapi: "POST /project"---diff --git a/apps/docs/api-reference/endpoints/projects/deleteProject.mdx b/apps/docs/api-reference/endpoints/projects/deleteProject.mdxindex 8449b69cd..400929290 100644--- a/apps/docs/api-reference/endpoints/projects/deleteProject.mdx+++ b/apps/docs/api-reference/endpoints/projects/deleteProject.mdx@@ -1,5 +1,4 @@----title: deleteProject-description: Delete a project by ID-openapi: 'DELETE /project/{id}'+title: "Delete project"+openapi: "DELETE /project/{id}"---diff --git a/apps/docs/api-reference/endpoints/projects/getProject.mdx b/apps/docs/api-reference/endpoints/projects/getProject.mdxindex c5cef6ff7..ad745fac0 100644--- a/apps/docs/api-reference/endpoints/projects/getProject.mdx+++ b/apps/docs/api-reference/endpoints/projects/getProject.mdx@@ -1,5 +1,4 @@----title: getProject-description: Get a specific project by ID-openapi: 'GET /project/{id}'+title: "Get project"+openapi: "GET /project/{id}"---diff --git a/apps/docs/api-reference/endpoints/projects/listProjects.mdx b/apps/docs/api-reference/endpoints/projects/listProjects.mdxindex ca2ce14ec..5a0ea6fae 100644--- a/apps/docs/api-reference/endpoints/projects/listProjects.mdx+++ b/apps/docs/api-reference/endpoints/projects/listProjects.mdx@@ -1,5 +1,4 @@----title: listProjects-description: Get all projects in a workspace-openapi: 'GET /project'+title: "List projects"+openapi: "GET /project"---diff --git a/apps/docs/api-reference/endpoints/projects/updateProject.mdx b/apps/docs/api-reference/endpoints/projects/updateProject.mdxindex 4e0301c4d..73f9d9c02 100644--- a/apps/docs/api-reference/endpoints/projects/updateProject.mdx+++ b/apps/docs/api-reference/endpoints/projects/updateProject.mdx@@ -1,5 +1,4 @@----title: updateProject-description: Update an existing project-openapi: 'PUT /project/{id}'+title: "Update project"+openapi: "PUT /project/{id}"---diff --git a/apps/docs/api-reference/endpoints/search/globalSearch.mdx b/apps/docs/api-reference/endpoints/search/globalSearch.mdxindex 994273cdc..9eac86788 100644--- a/apps/docs/api-reference/endpoints/search/globalSearch.mdx+++ b/apps/docs/api-reference/endpoints/search/globalSearch.mdx@@ -1,5 +1,4 @@----title: globalSearch-description: Search across tasks, projects, workspaces, comments, and activities-openapi: 'GET /search'+title: "Global search"+openapi: "GET /search"---diff --git a/apps/docs/api-reference/endpoints/tasks/createTask.mdx b/apps/docs/api-reference/endpoints/tasks/createTask.mdxindex 129f65d18..cda4c6006 100644--- a/apps/docs/api-reference/endpoints/tasks/createTask.mdx+++ b/apps/docs/api-reference/endpoints/tasks/createTask.mdx@@ -1,5 +1,4 @@----title: createTask-description: Create a new task in a project-openapi: 'POST /task/{projectId}'+title: "Create task"+openapi: "POST /task/{projectId}"---diff --git a/apps/docs/api-reference/endpoints/tasks/deleteTask.mdx b/apps/docs/api-reference/endpoints/tasks/deleteTask.mdxindex 48f53a3b2..7c2f5b622 100644--- a/apps/docs/api-reference/endpoints/tasks/deleteTask.mdx+++ b/apps/docs/api-reference/endpoints/tasks/deleteTask.mdx@@ -1,5 +1,4 @@----title: deleteTask-description: Delete a task by ID-openapi: 'DELETE /task/{id}'+title: "Delete task"+openapi: "DELETE /task/{id}"---diff --git a/apps/docs/api-reference/endpoints/tasks/exportTasks.mdx b/apps/docs/api-reference/endpoints/tasks/exportTasks.mdxindex 1d291e70d..1b18c7947 100644--- a/apps/docs/api-reference/endpoints/tasks/exportTasks.mdx+++ b/apps/docs/api-reference/endpoints/tasks/exportTasks.mdx@@ -1,5 +1,4 @@----title: exportTasks-description: Export all tasks from a project-openapi: 'GET /task/export/{projectId}'+title: "Export tasks"+openapi: "GET /task/export/{projectId}"---diff --git a/apps/docs/api-reference/endpoints/tasks/getTask.mdx b/apps/docs/api-reference/endpoints/tasks/getTask.mdxindex 98f893878..db28aeb36 100644--- a/apps/docs/api-reference/endpoints/tasks/getTask.mdx+++ b/apps/docs/api-reference/endpoints/tasks/getTask.mdx@@ -1,5 +1,4 @@----title: getTask-description: Get a specific task by ID-openapi: 'GET /task/{id}'+title: "Get task"+openapi: "GET /task/{id}"---diff --git a/apps/docs/api-reference/endpoints/tasks/importTasks.mdx b/apps/docs/api-reference/endpoints/tasks/importTasks.mdxindex b20ff2118..6b8c78a3f 100644--- a/apps/docs/api-reference/endpoints/tasks/importTasks.mdx+++ b/apps/docs/api-reference/endpoints/tasks/importTasks.mdx@@ -1,5 +1,4 @@----title: importTasks-description: Import multiple tasks into a project-openapi: 'POST /task/import/{projectId}'+title: "Import tasks"+openapi: "POST /task/import/{projectId}"---diff --git a/apps/docs/api-reference/endpoints/tasks/listTasks.mdx b/apps/docs/api-reference/endpoints/tasks/listTasks.mdxindex d70da023f..09f203bbb 100644--- a/apps/docs/api-reference/endpoints/tasks/listTasks.mdx+++ b/apps/docs/api-reference/endpoints/tasks/listTasks.mdx@@ -1,10 +1,8 @@----title: listTasks-description: Get a bounded page of tasks for a specific project-openapi: 'GET /task/tasks/{projectId}'+title: "List tasks"+openapi: "GET /task/tasks/{projectId}"----Every response is paginated: the default is **50 tasks**, with a maximum `limit` of **100**. Inspect `pagination.totalPages` and request subsequent `page` values to retrieve the entire project. Filters and sorting are applied before pagination. The page includes tasks across regular columns, planned tasks and archived tasks; it is not a separate limit for every column.The web app fetches these pages sequentially and combines them for its board, list, calendar and Gantt views. Custom clients that previously omitted pagination to receive every task must now follow the pagination metadata. MCP `list_tasks` uses the same paginated contract.diff --git a/apps/docs/api-reference/endpoints/tasks/updateTask.mdx b/apps/docs/api-reference/endpoints/tasks/updateTask.mdxindex 81cc4e580..e702247d0 100644--- a/apps/docs/api-reference/endpoints/tasks/updateTask.mdx+++ b/apps/docs/api-reference/endpoints/tasks/updateTask.mdx@@ -1,5 +1,4 @@----title: updateTask-description: Update all fields of a task-openapi: 'PUT /task/{id}'+title: "Update task"+openapi: "PUT /task/{id}"---diff --git a/apps/docs/api-reference/endpoints/tasks/updateTaskAssignee.mdx b/apps/docs/api-reference/endpoints/tasks/updateTaskAssignee.mdxindex 9299f1f58..e3054debc 100644--- a/apps/docs/api-reference/endpoints/tasks/updateTaskAssignee.mdx+++ b/apps/docs/api-reference/endpoints/tasks/updateTaskAssignee.mdx@@ -1,5 +1,4 @@----title: updateTaskAssignee-description: Assign or unassign a task to a user-openapi: 'PUT /task/assignee/{id}'+title: "Update task assignee"+openapi: "PUT /task/assignee/{id}"---diff --git a/apps/docs/api-reference/endpoints/tasks/updateTaskDescription.mdx b/apps/docs/api-reference/endpoints/tasks/updateTaskDescription.mdxindex 93be96d98..b9aa06b58 100644--- a/apps/docs/api-reference/endpoints/tasks/updateTaskDescription.mdx+++ b/apps/docs/api-reference/endpoints/tasks/updateTaskDescription.mdx@@ -1,5 +1,4 @@----title: updateTaskDescription-description: Update only the description of a task-openapi: 'PUT /task/description/{id}'+title: "Update task description"+openapi: "PUT /task/description/{id}"---diff --git a/apps/docs/api-reference/endpoints/tasks/updateTaskDueDate.mdx b/apps/docs/api-reference/endpoints/tasks/updateTaskDueDate.mdxindex 166b050e6..a0fd09804 100644--- a/apps/docs/api-reference/endpoints/tasks/updateTaskDueDate.mdx+++ b/apps/docs/api-reference/endpoints/tasks/updateTaskDueDate.mdx@@ -1,5 +1,4 @@----title: updateTaskDueDate-description: Update only the due date of a task-openapi: 'PUT /task/due-date/{id}'+title: "Update task due date"+openapi: "PUT /task/due-date/{id}"---diff --git a/apps/docs/api-reference/endpoints/tasks/updateTaskPriority.mdx b/apps/docs/api-reference/endpoints/tasks/updateTaskPriority.mdxindex 850cc69d3..95be0cd00 100644--- a/apps/docs/api-reference/endpoints/tasks/updateTaskPriority.mdx+++ b/apps/docs/api-reference/endpoints/tasks/updateTaskPriority.mdx@@ -1,5 +1,4 @@----title: updateTaskPriority-description: Update only the priority of a task-openapi: 'PUT /task/priority/{id}'+title: "Update task priority"+openapi: "PUT /task/priority/{id}"---diff --git a/apps/docs/api-reference/endpoints/tasks/updateTaskStatus.mdx b/apps/docs/api-reference/endpoints/tasks/updateTaskStatus.mdxindex 687bb97a2..96d55846a 100644--- a/apps/docs/api-reference/endpoints/tasks/updateTaskStatus.mdx+++ b/apps/docs/api-reference/endpoints/tasks/updateTaskStatus.mdx@@ -1,5 +1,4 @@----title: updateTaskStatus-description: Update only the status of a task-openapi: 'PUT /task/status/{id}'+title: "Update task status"+openapi: "PUT /task/status/{id}"---diff --git a/apps/docs/api-reference/endpoints/tasks/updateTaskTitle.mdx b/apps/docs/api-reference/endpoints/tasks/updateTaskTitle.mdxindex e7eb34697..443067331 100644--- a/apps/docs/api-reference/endpoints/tasks/updateTaskTitle.mdx+++ b/apps/docs/api-reference/endpoints/tasks/updateTaskTitle.mdx@@ -1,5 +1,4 @@----title: updateTaskTitle-description: Update only the title of a task-openapi: 'PUT /task/title/{id}'+title: "Update task title"+openapi: "PUT /task/title/{id}"---diff --git a/apps/docs/api-reference/endpoints/time-entries/createTimeEntry.mdx b/apps/docs/api-reference/endpoints/time-entries/createTimeEntry.mdxindex c543962b0..5121b574c 100644--- a/apps/docs/api-reference/endpoints/time-entries/createTimeEntry.mdx+++ b/apps/docs/api-reference/endpoints/time-entries/createTimeEntry.mdx@@ -1,5 +1,4 @@----title: createTimeEntry-description: Create a new time entry for a task-openapi: 'POST /time-entry'+title: "Create time entry"+openapi: "POST /time-entry"---diff --git a/apps/docs/api-reference/endpoints/time-entries/getTaskTimeEntries.mdx b/apps/docs/api-reference/endpoints/time-entries/getTaskTimeEntries.mdxindex d5327ae48..1dd2a2518 100644--- a/apps/docs/api-reference/endpoints/time-entries/getTaskTimeEntries.mdx+++ b/apps/docs/api-reference/endpoints/time-entries/getTaskTimeEntries.mdx@@ -1,5 +1,4 @@----title: getTaskTimeEntries-description: Get all time entries for a specific task-openapi: 'GET /time-entry/task/{taskId}'+title: "Get task time entries"+openapi: "GET /time-entry/task/{taskId}"---diff --git a/apps/docs/api-reference/endpoints/time-entries/getTimeEntry.mdx b/apps/docs/api-reference/endpoints/time-entries/getTimeEntry.mdxindex 6c777527d..496dab093 100644--- a/apps/docs/api-reference/endpoints/time-entries/getTimeEntry.mdx+++ b/apps/docs/api-reference/endpoints/time-entries/getTimeEntry.mdx@@ -1,5 +1,4 @@----title: getTimeEntry-description: Get a specific time entry by ID-openapi: 'GET /time-entry/{id}'+title: "Get time entry"+openapi: "GET /time-entry/{id}"---diff --git a/apps/docs/api-reference/endpoints/time-entries/updateTimeEntry.mdx b/apps/docs/api-reference/endpoints/time-entries/updateTimeEntry.mdxindex 2d11aef7a..eedd9fa74 100644--- a/apps/docs/api-reference/endpoints/time-entries/updateTimeEntry.mdx+++ b/apps/docs/api-reference/endpoints/time-entries/updateTimeEntry.mdx@@ -1,5 +1,4 @@----title: updateTimeEntry-description: Update an existing time entry-openapi: 'PUT /time-entry/{id}'+title: "Update time entry"+openapi: "PUT /time-entry/{id}"---diff --git a/apps/docs/api-reference/endpoints/workflow-rules/deleteWorkflowRule.mdx b/apps/docs/api-reference/endpoints/workflow-rules/deleteWorkflowRule.mdxindex 1775ecc40..c52f160d8 100644--- a/apps/docs/api-reference/endpoints/workflow-rules/deleteWorkflowRule.mdx+++ b/apps/docs/api-reference/endpoints/workflow-rules/deleteWorkflowRule.mdx@@ -1,5 +1,4 @@----title: deleteWorkflowRule-description: Delete a workflow rule-openapi: 'DELETE /workflow-rule/{id}'+title: "Delete workflow rule"+openapi: "DELETE /workflow-rule/{id}"---diff --git a/apps/docs/api-reference/endpoints/workflow-rules/getWorkflowRules.mdx b/apps/docs/api-reference/endpoints/workflow-rules/getWorkflowRules.mdxindex a10e8db8e..d02f8a1ae 100644--- a/apps/docs/api-reference/endpoints/workflow-rules/getWorkflowRules.mdx+++ b/apps/docs/api-reference/endpoints/workflow-rules/getWorkflowRules.mdx@@ -1,5 +1,4 @@----title: getWorkflowRules-description: Get all workflow rules for a project-openapi: 'GET /workflow-rule/{projectId}'+title: "Get workflow rules"+openapi: "GET /workflow-rule/{projectId}"---diff --git a/apps/docs/api-reference/endpoints/workflow-rules/upsertWorkflowRule.mdx b/apps/docs/api-reference/endpoints/workflow-rules/upsertWorkflowRule.mdxindex 14bc21838..3a6a562a6 100644--- a/apps/docs/api-reference/endpoints/workflow-rules/upsertWorkflowRule.mdx+++ b/apps/docs/api-reference/endpoints/workflow-rules/upsertWorkflowRule.mdx@@ -1,5 +1,4 @@----title: upsertWorkflowRule-description: Create or update a workflow rule-openapi: 'PUT /workflow-rule/{projectId}'+title: "Upsert workflow rule"+openapi: "PUT /workflow-rule/{projectId}"---diff --git a/apps/docs/api-reference/introduction.mdx b/apps/docs/api-reference/introduction.mdxindex 2221c9477..e1bdc784d 100644--- a/apps/docs/api-reference/introduction.mdx+++ b/apps/docs/api-reference/introduction.mdx@@ -1,26 +1,65 @@----title: API Reference-description: Complete API reference for Kaneo+title: "Make your first API request"+description: "Authenticate, find a project, and read its tasks."----## Overview+Use the Kaneo API for scripts and integrations. Requests go to your instance's public API URL, usually `https://kaneo.example.com/api`.-Kaneo API endpoint pages are generated automatically from our OpenAPI specification.+## 1. Create an API key-<Card- title="OpenAPI Specification"- icon="code"- href="https://cloud.kaneo.app/api/openapi"->- View the canonical OpenAPI schema powering this documentation.-</Card>+Open **Settings → Account → API Keys** in Kaneo and create a key for your script. Copy it when it is shown. See [Authentication](/api-reference/authentication) for API keys and device authorization.-## Authentication+Keep keys in server-side scripts or secret storage. Do not put a personal API key in frontend JavaScript shipped to other users.-All API endpoints require authentication. Refer to the [authentication guide](/api-reference/authentication) for details on creating and using API keys.+## 2. Find your workspace and project IDs-## Base URL+Open a project in the browser. Its URL includes both IDs:```text-https://your-kaneo-instance.com/api+/dashboard/workspace/WORKSPACE_ID/project/PROJECT_ID/board```++Use the IDs from the URL, not the workspace name or a task number such as `WEB-22`.++## 3. List the workspace's projects++Set `KANEO_API_KEY` in your shell using your secret manager or a private environment file. Then replace the example workspace ID:++```bash+curl --fail-with-body --get 'https://kaneo.example.com/api/project' \+ --data-urlencode 'workspaceId=WORKSPACE_ID' \+ -H "Authorization: Bearer $KANEO_API_KEY"+```++A successful response is a JSON array of projects. Use a project's `id` in the next request.++## 4. Read the project's tasks++```bash+curl --fail-with-body \+ 'https://kaneo.example.com/api/task/tasks/PROJECT_ID?page=1&limit=50' \+ -H "Authorization: Bearer $KANEO_API_KEY"+```++This endpoint returns a project board, including columns and task buckets, together with pagination metadata. It is not a flat task array. Follow `pagination.totalPages` for task pages and `pagination.relatedTotalPages` for related metadata pages when those span multiple pages.++For a single task, request `GET /api/task/TASK_ID`. Check the endpoint reference for the exact response and supported filters. Large descriptions can be deferred from list results, so fetch task details when you need the full text.++## Handle errors++| Status | What to check |+| --- | --- |+| 400 | Required IDs, query parameters, and request body |+| 401 | Missing, invalid, or expired credentials |+| 403 | Workspace membership and permission for the requested action |+| 404 | The resource ID and endpoint path |+| 429 | Rate limits; wait before retrying |+| 5xx | Instance logs and service health |++Inspect the response body for the specific error. Do not retry a mutation blindly when you are unsure whether it already succeeded.++## API reference++The endpoint pages are generated from the repository's [OpenAPI specification](/openapi.json). A running instance exposes its own schema at `/api/openapi`, which is the best match for that instance's installed version.++Most application endpoints require authentication. Public endpoints, including health and sign-in routes, have their own requirements. Authentication never grants access to every workspace automatically.diff --git a/apps/docs/core/deployments/coolify.mdx b/apps/docs/core/deployments/coolify.mdxindex faa67fd13..a952b5246 100644--- a/apps/docs/core/deployments/coolify.mdx+++ b/apps/docs/core/deployments/coolify.mdx@@ -1,5 +1,5 @@----title: Coolify+title: Deploy on Coolifydescription: Deploy Kaneo to Coolify using the bundled Docker Compose file.---@@ -14,13 +14,13 @@ Kaneo ships a [Coolify-optimized Docker Compose file](https://github.com/usekane3. **Select the build pack**: Set **Build Pack** to `Docker Compose`.- **Base Directory**: `/`- **Docker Compose Location**: `compose.coolify.yml`-4. **Assign a domain to the `kaneo` service**: the container listens on port `5173`, so enter `https://<your-domain>:5173`. The port only tells Coolify where to route traffic inside the container — visitors use the normal HTTPS URL (`https://<your-domain>`) without the port.+4. **Assign a domain to the `kaneo` service**: the container listens on port `5173`, so enter `https://<your-domain>:5173`. The port only tells Coolify where to route traffic inside the container; visitors use the normal HTTPS URL (`https://<your-domain>`) without the port.5. **Set environment variables** (pre-filled from the compose file):- `KANEO_CLIENT_URL` (required): your public URL, e.g. `https://kaneo.example.com` (no `:5173`).- `AUTH_SECRET` (auto-generated 64-character hex, editable).- PostgreSQL password (auto-generated, shared with both services).- - **Do not set `KANEO_API_URL`** to `localhost` or an internal address. Leave it unset — the container derives it from `KANEO_CLIENT_URL` (`https://kaneo.example.com/api`). The browser must reach the API over the same public domain, not a host-internal URL.- - `KANEO_IMAGE_TAG` (optional): the Kaneo image version to deploy. It defaults to `latest`; set it to a release tag such as `2.20.0` to hold the deployment on a known version.+ - **Do not set `KANEO_API_URL`** to `localhost` or an internal address. Leave it unset; the container derives it from `KANEO_CLIENT_URL` (`https://kaneo.example.com/api`). The browser must reach the API over the same public domain, not a host-internal URL.+ - `KANEO_IMAGE_TAG` (optional): the Kaneo image version to deploy. It defaults to `latest`; set it to a release tag such as `2.28.3` to hold the deployment on a known version.6. **Deploy**.## What the Compose File Sets Up@@ -28,18 +28,18 @@ Kaneo ships a [Coolify-optimized Docker Compose file](https://github.com/usekane- **PostgreSQL 16** with a persistent volume; Kaneo waits for its health check before starting.- **Kaneo bundled image** (nginx + API in one container) on port `5173`.- **Kaneo version**: the image tracks `latest`, so a redeploy picks up the newest release. The API runs database migrations on startup, so set `KANEO_IMAGE_TAG` to a release tag if you would rather upgrade deliberately.-- **`KANEO_API_URL` is derived automatically** from `KANEO_CLIENT_URL` by the container entrypoint — no extra API URL configuration needed.+- **`KANEO_API_URL` is derived automatically** from `KANEO_CLIENT_URL` by the container entrypoint; no extra API URL configuration needed.- **No host port mappings or custom networks**: Coolify's proxy handles all external traffic.## Post-Deployment Setup1. **Create your first user**: visit your domain to create the admin account.2. **Email (optional)**: set the `SMTP_*` variables on the `kaneo` service in the Coolify UI.-3. **SSO (optional)**: configure GitHub, Google, or other providers — see the [social providers](/core/social-providers/github) guides.+3. **SSO (optional)**: configure GitHub, Google, or other providers; see the [social providers](/core/social-providers/github) guides.## Troubleshooting- **"No Available Server"**: check the container health check with `docker ps`; the image needs up to 60 seconds to start.- **Verify environment**: ensure `KANEO_CLIENT_URL` is set to the exact public URL of your instance.-For other issues, see the [troubleshooting section](/core/installation/start-services).+For other issues, see the [troubleshooting guide](/core/operations/troubleshooting).diff --git a/apps/docs/core/deployments/railway.mdx b/apps/docs/core/deployments/railway.mdxindex 64af28f1c..d0228229d 100644--- a/apps/docs/core/deployments/railway.mdx+++ b/apps/docs/core/deployments/railway.mdx@@ -1,73 +1,37 @@----title: Railway-description: Deploy Kaneo to Railway using the official template.+title: "Deploy on Railway"+description: "Deploy the Railway template, configure sign-in, and check the instance."----## Railway Template-Kaneo provides an official Railway template for easy deployment with a single click.+The [Kaneo Railway template](https://railway.com/deploy/kaneo) provisions PostgreSQL, a Kaneo API service, and a web service. This template uses separate API and web images, unlike the bundled Docker Compose guide.-[Deploy on Railway](https://railway.com/deploy/kaneo)+## Deploy the template-## What the Template Includes+1. Open the template and sign in to Railway.+2. Review the services, persistent database volume, and environment references.+3. Generate a secret with `openssl rand -hex 32` and set it as `AUTH_SECRET` on the API service.+4. Deploy and wait for the services to become healthy.-The Railway template automatically configures:+The template supplies the database connection and service URL references. Keep those references rather than replacing them with literal example credentials.-- **PostgreSQL Database**: Managed PostgreSQL instance-- **API Service**: Pre-configured Hono API server-- **Web Service**: Pre-configured React web application-- **Environment Variables**: All required variables with sensible defaults-- **Networking**: Proper service discovery and internal communication-- **Build Configuration**: Optimized Docker builds for both services+## Open Kaneo-## Deployment Steps+Open the public web URL and create the initial administrator account. Make a project and task to check the API connection.-1. **Click the Deploy Button** above to open the Railway template-2. **Connect to Railway** (sign up or log in if needed)-3. **Configure Environment Variables**:- - Set your `AUTH_SECRET` (minimum 32 characters)- - Review other environment variables as needed-4. **Deploy** - Railway will build and deploy all services automatically+If you add custom domains, update the public URL settings on the services that consume them. The browser must reach the public API URL; Railway's private service hostname is for server-to-server traffic.-## Post-Deployment Setup+## Add the features you need-After deployment completes:+Configure optional settings on the API service, then redeploy affected services:-1. **Access Your Application**: Railway will provide URLs for both services-2. **Create Admin Account**: Visit the web application to create your first user-3. **Configure Domain** (optional): Add custom domains in Railway dashboard-4. **Set Up SSO** (optional): Configure GitHub, Google, or other providers+- [Email](/core/installation/environment-variables#smtp-configuration) for invitations and account notifications.+- [Sign-in providers](/core/social-providers/custom-oauth) for your identity provider.+- [File storage](/core/installation/object-storage-and-image-uploads) for task attachments.-## Environment Variables+## Keep it running-The template includes these pre-configured variables:+Review Railway's service logs when a health check fails. For browser failures, check the public API URL and allowed origins before redeploying.-```-# Railway automatically sets these-DATABASE_URL=postgresql://postgres:password@host:port/database-KANEO_API_URL=https://your-api.railway.app-KANEO_CLIENT_URL=https://your-web.railway.app+Set up database and storage backups using [Backups and recovery](/core/operations/backups) as a checklist. Record the deployed versions and read the [upgrade guide](/core/operations/upgrades) before changing images.-# You may want to customize these-AUTH_SECRET=your-32-character-secret-here-CORS_ORIGINS=https://your-web.railway.app-```--## Monitoring and Scaling--Railway provides built-in:--- **Health Checks**: Automatic service monitoring-- **Logs**: Centralized logging for all services-- **Metrics**: Performance and usage analytics-- **Scaling**: Easy horizontal scaling when needed--## Troubleshooting--If you encounter issues:--1. **Check Logs**: Use Railway's log viewer to debug-2. **Verify Environment**: Ensure all required variables are set-3. **Redeploy**: Sometimes a fresh deployment resolves issues-4. **Check Resource Usage**: Free tier has limitations--For more detailed troubleshooting, see the [troubleshooting section](/core/installation/start-services).+For connection, sign-in, and upload problems, see [Troubleshooting](/core/operations/troubleshooting).diff --git a/apps/docs/core/functional/account-notifications.mdx b/apps/docs/core/functional/account-notifications.mdxindex 9dad13a31..a4554e93b 100644--- a/apps/docs/core/functional/account-notifications.mdx+++ b/apps/docs/core/functional/account-notifications.mdx@@ -1,168 +1,63 @@----title: Account Notifications-description: Deliver your personal Kaneo notifications by email, ntfy, Gotify, or a custom webhook with workspace and project scoping+title: "Notifications"+description: "Choose which workspaces can send updates to your email or another personal channel."----Kaneo can keep the normal in-app notification inbox and also forward matching notifications to external channels for the signed-in user.+Open **Settings → Account → Notifications** to choose how Kaneo reaches you. These settings belong to your account and do not change anyone else's notifications.-You can configure this under:+Your inbox in Kaneo keeps working whether or not you enable external delivery. For messages to a shared team channel, use a [project integration](/core/integrations/index).-1. Open **Settings**-2. Open **Account**-3. Open **Notifications**+## 1. Choose which events you want-## Available channels+Use the event preferences at the top of the page to control task assignments, comments and mentions, status changes, and due-date reminders. These categories are enabled by default. Turning one off stops new notifications in that category, including in the Kaneo inbox.-Users can forward matching notifications through:+Due-date reminders default to one day before the deadline. Choose a whole number of hours (1–720) or days (1–30), then save. External delivery still needs a channel and workspace rule below.-- `Email`-- `ntfy`-- `Gotify`-- `Custom webhook`+<Frame caption="Choose notification categories and how early Kaneo should remind you about due dates.">+ <img className="block dark:hidden" src="/images/product/notifications-light.png" alt="Choose notification categories and how early Kaneo should remind you about due dates." />+ <img className="hidden dark:block" src="/images/product/notifications-dark.png" alt="Choose notification categories and how early Kaneo should remind you about due dates." />+</Frame>-These settings are personal to the signed-in account. They do not change notification routing for other users in the workspace.+## 2. Connect a channel-## How it works+| Channel | What you need |+| --- | --- |+| Email | An email address on your account and SMTP configured by your instance operator |+| [ntfy](/core/integrations/ntfy) | Your server URL, topic, and a bearer token if the server requires one |+| [Gotify](/core/integrations/gotify) | Your server's base URL and an application token created in Gotify |+| [Custom webhook](/core/integrations/personal-webhooks) | A destination URL and, optionally, a signing secret |-Kaneo already stores in-app notifications in the notification inbox. Account notification delivery adds a separate preference layer on top of that behavior.+For channels with tokens or signing secrets, the instance operator must first set `NOTIFICATION_SECRET_ENCRYPTION_KEY`. Configure and enable a channel on this page. Use the Gotify base URL, such as `https://gotify.example.com`, without adding its message API path.-Important rules:+For a signed custom webhook, Kaneo sends `X-Kaneo-Signature` as the HMAC-SHA256 hex digest of the raw JSON request body. Your receiver can verify it with the shared secret.-- the in-app inbox remains the source of truth-- outbound delivery only applies to newly created notifications-- historical notifications are not replayed-- delivery failures do not block notification creation-- delivery can be scoped by workspace and, optionally, by selected projects+## 3. Choose the workspaces and projects-## Global channels+Below the channel settings, add or edit a workspace delivery rule:-The Notifications page includes separate connection cards for:+1. Make the rule active.+2. Enable the channels you want to use for that workspace.+3. Choose **All projects** or **Selected projects**.+4. Save your changes.-- `Email`-- `Gotify`-- `ntfy`-- `Custom webhook`+For example, you can receive email for the website launch and use ntfy for another workspace. Configuring a channel alone is not enough; its workspace rule must also allow delivery.-Configure each channel once at the account level, then decide which workspaces are allowed to use it.+## Pause or stop delivery+Pause the workspace rule to stop forwarding that workspace's notifications. Disable a channel on the rule to stop only that destination. Disable the account-level channel to stop using it across your rules.-Email delivery uses the signed-in account email address.+Changes apply to new notifications. Kaneo does not replay older inbox items when you enable delivery again. If delivery fails, the notification still remains in your Kaneo inbox.-Requirements:+## Which notifications are forwarded?-- the user must have an email on the account-- SMTP must be configured on the server+Forwarding uses the notifications Kaneo creates for your account and respects your event preferences. A project event does not automatically notify every member. Use a project integration when you want a shared feed of project activity.-### ntfy+A notification without a workspace or project context may stay in the inbox only.-ntfy requires:+## If a channel cannot be saved or delivery fails-- a server URL-- a topic-- optionally, a bearer token+Check the channel is enabled, the workspace rule is active, and the project is included. For email, ask the instance operator to check SMTP and its delivery logs.-### Gotify+HTTP destinations must be reachable from the Kaneo API. By default, local and private network addresses are rejected. On a trusted private deployment, an operator can choose to allow them with [`KANEO_ALLOW_PRIVATE_WEBHOOK_DESTINATIONS`](/core/installation/environment-variables#notifications); this changes a server-side security boundary, not an account preference.-Gotify requires:--- a server URL-- an application token (bearer token)--Setup notes:--- create an application in your Gotify server before connecting Kaneo-- paste the base server URL, for example `https://gotify.example.com`-- no extra topic or path is required because Kaneo sends directly to the Gotify message API using the application token-- if your Gotify server uses a custom port or TLS, include that in the server URL--### Custom webhook--Custom webhook requires:--- a destination URL-- optionally, a signing secret--When a signing secret is configured, Kaneo sends an `X-Kaneo-Signature` header containing the `HMAC-SHA256` hex digest of the raw JSON body.--## Workspace delivery rules--Below the global channel cards, Kaneo shows workspace delivery rules.--Each workspace rule can:--- be active or paused-- enable or disable `Email`, `Gotify`, `ntfy`, and `Custom webhook`-- apply to `All projects`-- or apply to `Selected projects` only--This lets a user receive notifications from one workspace in ntfy, another by email, and ignore the rest.--## Supported notification sources--V1 forwards the same notification types that currently create inbox notifications in Kaneo.--That includes:--- `task_created`-- `workspace_created`-- `task_status_changed`-- `task_assignee_changed`-- `time_entry_created`--If Kaneo cannot resolve a notification to a workspace or project context, that notification stays inbox-only.--## Reachability and security--For security, Kaneo validates outbound HTTP destinations before saving or sending.--Private or non-routable destinations are rejected, including examples like:--- `localhost`-- `127.0.0.1`-- `10.x.x.x`-- `172.16.x.x` to `172.31.x.x`-- `192.168.x.x`--This applies to:--- `ntfy` server URLs-- `Gotify` server URLs-- custom webhook URLs--If you are using a self-hosted ntfy instance, Gotify instance, or webhook receiver, it must be reachable from the API with an accepted public or routable hostname.--If your receiver only exists on a private network, set `KANEO_ALLOW_PRIVATE_WEBHOOK_DESTINATIONS=true` on the API to bypass this guard. It is off by default, the `http`/`https` protocol requirement still applies, and enabling it re-opens the SSRF surface the check protects against. Only turn it on for a trusted, isolated deployment.--## Troubleshooting--### Notifications show in Kaneo but are not delivered--Check that:--- the global channel is configured and enabled-- a workspace rule exists for the notification workspace-- the workspace rule is active-- the channel is enabled on that workspace rule-- the project is included when using `Selected projects`--### Email is enabled but nothing is sent--Check that:--- SMTP is configured correctly-- the signed-in user has an email address-- the server can reach the SMTP provider--### ntfy, Gotify, or webhook save fails--Check that:--- the URL is valid-- the destination is reachable from the API server-- the hostname does not resolve to a blocked local or private address--## Next--- [Personalize Your Workspace](/core/functional/personalize-your-workspace)-- [Outgoing webhooks](/core/integrations/outgoing-webhooks)+If a notification appears in the inbox but never reaches your destination, check the destination service's logs and credentials next.diff --git a/apps/docs/core/functional/backlog-planning.mdx b/apps/docs/core/functional/backlog-planning.mdxindex e307c5b74..834034c9f 100644--- a/apps/docs/core/functional/backlog-planning.mdx+++ b/apps/docs/core/functional/backlog-planning.mdx@@ -1,46 +1,33 @@----title: Plan Work in Backlog-description: Use the backlog to prepare work before it enters active execution+title: "Backlog"+description: "Keep ideas and upcoming work out of the active board until they are ready."----Backlog view is your planning layer. Use it to prepare tasks before moving them into active columns.+Open **Backlog** at the top of a project to collect work you want to keep but are not ready to start.-In Kaneo's data model, backlog items use the `planned` task status. A board column named "Backlog" is just a regular board column, not the same thing as the Backlog view.+<Frame caption="Backlog keeps planned work together until you move it to an active column.">+ <img className="block dark:hidden" src="/images/product/backlog-light.png" alt="Backlog keeps planned work together until you move it to an active column." />+ <img className="hidden dark:block" src="/images/product/backlog-dark.png" alt="Backlog keeps planned work together until you move it to an active column." />+</Frame>-## When to use Backlog+## Add and prepare work-Use backlog when you need to:+Choose **Plan** to create a task in the backlog, then open it to add context. Set a priority or label if that will help you decide what to work on next. An idea does not need an assignee or due date just to be worth keeping.-- Break down upcoming scope-- Prioritize before execution-- Triage ambiguous requests-- Keep active columns focused on in-flight work+Before moving it into active work, write down the expected outcome and any missing information. For example, “Update pricing” might become “Publish the approved annual pricing on the website.”-## Core workflow+## Move a task into active work-1. Open your project **Backlog** view.-2. Add or edit planned tasks.-3. Apply priority, due date, labels, and assignee.-4. Filter by priority/assignee/due date/labels to review specific slices.-5. Move ready tasks from planning into active execution.+Open the task and change its status to a board column, such as **To Do**. It is now part of the project's active task view. To return an active task to the backlog, right-click its board card and choose **Mark as planned**.-## Recommended planning cadence+Use the backlog filters to narrow the list by priority, assignee, dates, or labels when reviewing upcoming work.-- Daily: quick triage for new incoming work-- Weekly: backlog grooming and priority cleanup-- Sprint/start-of-cycle: move only ready tasks into active columns+<Note>+The backlog uses the **Planned** status. A board column you name “Backlog” is still a normal board column, so it does not replace this view.+</Note>-## Quality checklist for ready tasks+## Keep the backlog useful-A task is ready to move when it has:+Review it when you choose the next work. Clarify tasks you still want to do, move ready work onto the board, and remove requests you have decided against.-- Clear title and expected outcome-- Owner assigned-- Priority set-- Necessary labels-- Due date (if time-sensitive)--## Next--- [Plan and execute tasks in Board/List](/core/functional/plan-and-execute-tasks)-- [Collaborate with your team](/core/functional/collaborate-with-team)+Continue with [Board and List](/core/functional/plan-and-execute-tasks) to track work once it starts.diff --git a/apps/docs/core/functional/calendar-and-gantt.mdx b/apps/docs/core/functional/calendar-and-gantt.mdxnew file mode 100644index 000000000..eee3d489a--- /dev/null+++ b/apps/docs/core/functional/calendar-and-gantt.mdx@@ -0,0 +1,27 @@+---+title: "Calendar and Gantt"+description: "See when work is due and how scheduled tasks fit together."+---++Open a project and choose **Calendar** or **Gantt** from the top navigation. Both views use the dates on your tasks.++## Calendar++Use Calendar to review work by month. Use the arrows to change months and **Today** to return to the current month. Click a task to open its details. On busy days, open the overflow indicator to see the remaining tasks.++## Gantt++Use Gantt when you want to see scheduled tasks across time, such as the work leading up to a launch.++<Frame caption="Gantt view places scheduled project work on a shared timeline.">+ <img className="block dark:hidden" src="/images/product/timeline-light.png" alt="Gantt view places scheduled project work on a shared timeline." />+ <img className="hidden dark:block" src="/images/product/timeline-dark.png" alt="Gantt view places scheduled project work on a shared timeline." />+</Frame>++A task needs at least a start date or a due date to appear in either view. With only one date it occupies a single day; with both it spans the range. Scheduled backlog tasks are included, while archived tasks are excluded.++Set a start date and a due date on a task to give its schedule a clear span. Open the task when you need to update its owner, scope, or dates.++Dates and status answer different questions. Reaching a due date does not finish a task; move it to a done column when the work is complete.++For unscheduled ideas, use the [backlog](/core/functional/backlog-planning). For daily status changes, use [Board or List](/core/functional/plan-and-execute-tasks).diff --git a/apps/docs/core/functional/collaborate-with-team.mdx b/apps/docs/core/functional/collaborate-with-team.mdxindex d5149db0a..e46c3f5ef 100644--- a/apps/docs/core/functional/collaborate-with-team.mdx+++ b/apps/docs/core/functional/collaborate-with-team.mdx@@ -1,50 +1,66 @@----title: Collaborate with Your Team-description: Invite members, assign ownership, and keep team execution aligned+title: "Members and roles"+description: "Invite teammates, manage pending invitations, and choose who can change what."----Good collaboration in Kaneo comes from clear ownership and consistent project conventions.+Membership belongs to a workspace. Make sure the workspace name at the top of the sidebar is the one you want before inviting someone or changing their role.-## 1. Invite members+## Invite a teammate-In your workspace:+1. Open **Members** in the workspace sidebar.+2. Choose **Invite member** and enter their email address.+3. Create the invitation, then copy the link shown in the dialog.+4. Share the link with that person. With SMTP configured, the instance can also send an invitation email.-1. Open **Members**.-2. Click **Invite member**.-3. Send invitations to teammates.-4. Track active and pending members in the members table.+The person must sign in or sign up with the invited email address and accept the invitation. New invitations created from this dialog use the **Member** role. You can change the role after the person joins.-## 2. Assign clear ownership+<Frame caption="The Members page shows workspace members, their roles, and invitation controls.">+ <img className="block dark:hidden" src="/images/product/members-light.png" alt="The Members page shows workspace members, their roles, and invitation controls." />+ <img className="hidden dark:block" src="/images/product/members-dark.png" alt="The Members page shows workspace members, their roles, and invitation controls." />+</Frame>-For each active task:+## Find or cancel a pending invitation-- Assign one primary owner-- Use due dates for time-sensitive work-- Set priority to support tradeoff decisions+Pending invitations appear in the members table. Use the invitation's menu to copy its link again or cancel it.-## 3. Standardize labels+Cancel an invitation sent to the wrong address. If it has expired, create a new invitation. If someone sees an email mismatch, ask them to sign in with the address you invited.-Use labels to create a shared language across the team. Manage them at the workspace level in **Settings -> Workspace -> Labels** (see [Manage workspace labels](/core/functional/manage-workspace-labels)).+On an instance without email delivery, share the invitation link yourself. If email delivery reports an error, check the pending invitation before retrying; the operator may need to fix SMTP.-Examples:+## Choose a role-- Work type: `bug`, `feature`, `chore`-- Domain: `api`, `web`, `infra`-- Risk/impact: `critical`, `customer-impact`+Use the role selector next to a member in **Members**. You need permission to change roles; you cannot change your own role through that selector.-## 4. Use views intentionally+These are the starting permissions. An administrator can edit the **Viewer**, **Member**, and **Admin** roles, so your workspace may differ.-- **Board** for daily execution-- **List** for compact review and cleanup-- **Backlog** for planning and grooming+| Role | Default access |+| --- | --- |+| Viewer | Read projects, tasks, labels, and workspace details |+| Member | Create projects; create and update tasks; manage labels |+| Admin | Manage projects, tasks, members, and workspace settings |+| Owner | Full workspace control, including deleting the workspace |-Switch views depending on the meeting or decision you are making.+Task assignment and deletion are separate permissions. A member who can edit a task may still be unable to assign or delete it.-## 5. Keep communication in the task+## Edit roles or create a custom role-When scope, ownership, or timing changes, update the task directly so project history remains visible.+Open **Settings → Workspace → Roles** to inspect the permissions behind a role. If you have role-management permission, you can change the editable roles or create a custom one.-## Next+Give people the access their work needs. For example, a reviewer may only need to read tasks, while a project lead may need to assign and delete them. The owner role is fixed.-- [Configure project workflows](/core/functional/configure-workflows)-- [Personalize your workspace](/core/functional/personalize-your-workspace)+## Remove a member or transfer ownership++In **Members**, use the member's menu to remove them and confirm the action. They lose membership in this workspace, but their Kaneo account is not deleted.++To change the owner, use **Settings → Workspace → General → Transfer ownership**. Transfer ownership before leaving or deleting your account if you are the only owner of a shared workspace.++## Keep the conversation with the work++Open a task to leave a comment, update its description, or choose the next assignee.++<Frame caption="Comments stay alongside the task description and properties.">+ <img className="block dark:hidden" src="/images/product/task-light.png" alt="Comments stay alongside the task description and properties." />+ <img className="hidden dark:block" src="/images/product/task-dark.png" alt="Comments stay alongside the task description and properties." />+</Frame>++Each person can choose their own [notification settings](/core/functional/account-notifications). For updates sent to a team channel, use a [project integration](/core/integrations/index).diff --git a/apps/docs/core/functional/configure-workflows.mdx b/apps/docs/core/functional/configure-workflows.mdxindex 5919360d2..7a5c5d712 100644--- a/apps/docs/core/functional/configure-workflows.mdx+++ b/apps/docs/core/functional/configure-workflows.mdx@@ -1,50 +1,33 @@----title: Configure Project Workflows-description: Customize columns and automation rules for how your project moves+title: "Workflows"+description: "Choose project columns and map repository events to the right status."----Use workflow settings to match Kaneo to your team's delivery process.+Open **Settings → Projects**, select a project, and choose **Workflow**. You need permission to manage the project to change its columns.-## Open workflow settings+## Change the columns-1. Go to **Settings**.-2. Open **Projects**.-3. Select a project.-4. Open the **Workflow** tab.+In **Columns**, add a stage, rename an existing one, choose its icon, or drag it into a different order. Start with the few stages your team actually uses, such as **To Do → In Progress → Review → Done**.-## Configure columns+Mark a column as a final state when tasks in it should count as complete. A column's name alone does not define completion.-In **Workflow -> Columns**:+<Frame caption="Project workflow settings contain columns, custom fields, and integration automation.">+ <img className="block dark:hidden" src="/images/product/workflow-light.png" alt="Project workflow settings contain columns, custom fields, and integration automation." />+ <img className="hidden dark:block" src="/images/product/workflow-dark.png" alt="Project workflow settings contain columns, custom fields, and integration automation." />+</Frame>-1. Add or rename columns to reflect your real stages.-2. Reorder columns to match execution order.-3. Mark final columns as done states where appropriate.+Kaneo refuses to delete a column that still contains tasks. Move those tasks into another column first and check any automation rules that target it. Changes apply to the whole project, so let your teammates know before reorganizing an active board.-Common examples:+## Add custom fields-- `To Do -> In Progress -> Review -> Done`-- `Backlog -> Ready -> In Progress -> QA -> Done`+Use **Custom Fields** on the same page when tasks need another piece of structured information. Give each field a clear name and choose text, number, date, dropdown, or boolean. For a dropdown, define the available choices. Drag fields to change their order; task details show them under **Custom Fields**.-## Configure automation rules+## Move tasks automatically-In **Workflow -> Automation Rules**:+Under **Automation Rules**, choose a target column for each GitHub or Gitea event you want to use. For example, a branch push can move work to **In Progress**, and a merged pull request can move it to **Done**.-1. Map integration events to target columns.-2. Verify each event moves work to the expected stage.+Connect the repository first through [Integrations](/core/integrations/index). Test one event with a task whose branch name matches the integration's pattern, then confirm the task moves to the expected column.-This helps keep project state aligned with external systems.+To change a mapping, select another column. Disconnect the repository integration if you want to stop using that connection entirely.-## Rollout strategy--When changing workflows on active projects:--- Announce the new column model first-- Migrate existing tasks in a single pass-- Keep naming stable after rollout--Frequent column churn reduces reporting clarity.--## Next--- [Plan and execute tasks in Board/List](/core/functional/plan-and-execute-tasks)-- [Collaborate with your team](/core/functional/collaborate-with-team)+Return to [Board and List](/core/functional/plan-and-execute-tasks) to work with the updated columns.diff --git a/apps/docs/core/functional/create-workspace-and-project.mdx b/apps/docs/core/functional/create-workspace-and-project.mdxindex 72f9fa56a..9a2afb9df 100644--- a/apps/docs/core/functional/create-workspace-and-project.mdx+++ b/apps/docs/core/functional/create-workspace-and-project.mdx@@ -1,46 +1,46 @@----title: Create a Workspace and Project-description: Set up your first workspace and project structure in Kaneo+title: "Workspaces and projects"+description: "Choose where your team and its work belong."----This guide covers the first functional setup inside Kaneo so your team can begin tracking work immediately.+A workspace contains members, projects, and shared labels. Use one workspace for people who should work together. Create separate workspaces when access needs to stay separate.-## 1. Create a workspace+Projects divide the work inside a workspace. A website launch, a support queue, and an internal roadmap can each be a project.-1. Go to the dashboard and create a new workspace.-2. Choose a clear workspace name (usually company, team, or department).-3. Confirm creation and open the workspace.+## Create a workspace-## 2. Create your first project+Use the workspace menu at the top of the sidebar to create a workspace. Give it a name your teammates will recognize. You become its owner.-Inside the workspace Projects page:+If you received an invitation, accept it instead of creating another workspace for the same team.-1. Click **Create project**.-2. Set a project name your team will recognize quickly.-3. Open the project when it appears in the projects list.+## Create a project-## 3. Decide your execution view+1. Switch to the right workspace.+2. Choose **Add project** in the sidebar, or create one from **Projects**.+3. Enter its name and submit the form.+4. Open the project from the sidebar.-Each project supports:+<Frame caption="The workspace menu is at the top left. Projects appear below it in the sidebar.">+ <img className="block dark:hidden" src="/images/product/board-light.png" alt="The workspace menu is at the top left. Projects appear below it in the sidebar." />+ <img className="hidden dark:block" src="/images/product/board-dark.png" alt="The workspace menu is at the top left. Projects appear below it in the sidebar." />+</Frame>-- **Board view** for status-driven execution-- **List view** for compact scanning and sorting-- **Backlog view** for planning and grooming+## Choose a view-You can switch views as your workflow changes.+| View | Use it for |+| --- | --- |+| Backlog | Preparing work that is not ready to start |+| Tasks → Board | Moving tasks through status columns |+| Tasks → List | Scanning task properties in rows |+| Calendar | Reviewing tasks by date |+| Gantt | Seeing scheduled work across a timeline |-## 4. Define basic conventions before inviting others+Changing views does not create a second copy of a task.-Before team onboarding, align on:+## Change settings-- Default status flow (e.g. To Do -> In Progress -> Done)-- Priority usage (low/medium/high/urgent)-- Label naming style (feature, bug, area, etc.)-- Due date expectations+Open **Settings → Projects** and select your project to manage its details, workflow, and integrations. Workspace settings hold shared details, labels, and roles.-This keeps your board consistent from day one.+The controls you see depend on your permissions. If you cannot create a project or change its settings, ask a workspace admin to check your role.-## Next--- [Plan and execute tasks in Board/List](/core/functional/plan-and-execute-tasks)-- [Collaborate with your team](/core/functional/collaborate-with-team)+Next, [add some tasks](/core/functional/plan-and-execute-tasks) or [invite your team](/core/functional/collaborate-with-team).diff --git a/apps/docs/core/functional/index.mdx b/apps/docs/core/functional/index.mdxindex c402c410a..4d99ef1d5 100644--- a/apps/docs/core/functional/index.mdx+++ b/apps/docs/core/functional/index.mdx@@ -1,23 +1,19 @@----title: Functional Guides-description: Practical, task-oriented guides for running Kaneo day to day+title: "Using Kaneo"+description: "Find the guide for what you want to do next."----Use these guides when you want to get work done in Kaneo, not just configure infrastructure.+New to Kaneo? Start with [Your first project](/core/index).-## Start Here--1. [Create a workspace and project](/core/functional/create-workspace-and-project)-2. [Plan and execute tasks in Board/List](/core/functional/plan-and-execute-tasks)-3. [Plan work in Backlog](/core/functional/backlog-planning)-4. [Collaborate with your team](/core/functional/collaborate-with-team)-5. [Configure project workflows](/core/functional/configure-workflows)-6. [Personalize your workspace](/core/functional/personalize-your-workspace)-7. [Manage workspace labels](/core/functional/manage-workspace-labels)--## Related--- [Quick Start](/core/index)-- [GitHub Integration Setup](/core/integrations/github/setup)-- [Outgoing webhooks](/core/integrations/outgoing-webhooks)-- [API Introduction](/api-reference/introduction)+| You want to… | Read |+| --- | --- |+| Set up a team or another project | [Workspaces and projects](/core/functional/create-workspace-and-project) |+| Create, assign, or find a task | [Board, List, and task details](/core/functional/plan-and-execute-tasks) |+| Prepare work for later | [Backlog](/core/functional/backlog-planning) |+| See work over time | [Calendar and Gantt](/core/functional/calendar-and-gantt) |+| Invite someone or change their access | [Members and roles](/core/functional/collaborate-with-team) |+| Change project columns | [Workflows](/core/functional/configure-workflows) |+| Organize related tasks | [Labels](/core/functional/manage-workspace-labels) |+| Choose which updates you receive | [Notifications](/core/functional/account-notifications) |+| Change the theme or task display | [Preferences](/core/functional/personalize-your-workspace) |+| Update your profile or delete your account | [Your account](/core/functional/manage-your-account) |diff --git a/apps/docs/core/functional/manage-workspace-labels.mdx b/apps/docs/core/functional/manage-workspace-labels.mdxindex ce2401165..a33156b73 100644--- a/apps/docs/core/functional/manage-workspace-labels.mdx+++ b/apps/docs/core/functional/manage-workspace-labels.mdx@@ -1,5 +1,5 @@----title: Manage Workspace Labels+title: Labelsdescription: Create, edit, and delete reusable labels at the workspace level---@@ -10,7 +10,12 @@ Labels help your team categorize tasks consistently across all projects. Workspa1. Go to **Settings**.2. Open **Workspace -> Labels**.-You'll see a list of all existing workspace labels with their colors and names.+You'll see the workspace's labels with their colors and names.++<Frame caption="Workspace labels are managed in Settings and shared across projects.">+ <img className="block dark:hidden" src="/images/product/labels-light.png" alt="Workspace labels are managed in Settings and shared across projects." />+ <img className="hidden dark:block" src="/images/product/labels-dark.png" alt="Workspace labels are managed in Settings and shared across projects." />+</Frame>## Create a label@@ -51,5 +56,5 @@ Creating, editing, and deleting labels require the corresponding **Label** permi## Related-- [Collaborate with your team: Standardize labels](/core/functional/collaborate-with-team#3-standardize-labels)+- [Members and roles](/core/functional/collaborate-with-team)- [Create a workspace and project](/core/functional/create-workspace-and-project)diff --git a/apps/docs/core/functional/manage-your-account.mdx b/apps/docs/core/functional/manage-your-account.mdxindex a36e130af..a5a4f2364 100644--- a/apps/docs/core/functional/manage-your-account.mdx+++ b/apps/docs/core/functional/manage-your-account.mdx@@ -1,6 +1,6 @@----title: Manage Your Account-description: Change your profile picture and understand what deleting your account does+title: Your account+description: Manage your profile, password, API keys, and account deletion---Your profile picture and your account itself are both managed from **Settings -> Account -> Information**.@@ -14,6 +14,21 @@ Your profile picture and your account itself are both managed from **Settings ->Choose **Remove avatar** to go back to your initials. Pictures are stored in your Kaneo database, so self-hosted instances need no object storage for this and a normal database backup includes them.+## Change your password++Open **Settings → Account → Security**. If your account has a password, enter the current password, choose a new one, and confirm it. The new password must be between 8 and 128 characters.++Accounts that sign in only through a provider or passwordless email do not have a current password to change here. If you forgot an existing password, use **Forgot password?** on the password sign-in form. Reset emails require SMTP and local sign-in to be enabled by your instance operator. Reset links expire after one hour; completing a reset revokes existing sessions.++<Frame caption="Accounts with a password can change it under Account → Security.">+ <img className="block dark:hidden" src="/images/product/security-light.png" alt="Accounts with a password can change it under Account → Security." />+ <img className="hidden dark:block" src="/images/product/security-dark.png" alt="Accounts with a password can change it under Account → Security." />+</Frame>++## API keys++Open **Settings → Account → API Keys** to create or revoke credentials for scripts and integrations. Follow [API authentication](/api-reference/authentication) before using a key.+## Delete your account1. Go to **Settings**.diff --git a/apps/docs/core/functional/personalize-your-workspace.mdx b/apps/docs/core/functional/personalize-your-workspace.mdxindex 7d2a8200e..21cbf480d 100644--- a/apps/docs/core/functional/personalize-your-workspace.mdx+++ b/apps/docs/core/functional/personalize-your-workspace.mdx@@ -1,52 +1,30 @@----title: Personalize Your Workspace-description: Tune display and preference settings for your team's day-to-day workflow+title: "Preferences"+description: "Choose how Kaneo looks and how tasks appear for you."----Kaneo includes account and workspace preferences that improve clarity without adding noise.+Open **Settings → Account → Preferences**. These are your preferences, so changing them does not change how your teammates see Kaneo.-## Open preferences+## Appearance and layout-1. Go to **Settings**.-2. Open **Account -> Preferences**.+Choose your theme, default task view, compact mode, and whether the sidebar starts open or closed. You can also change the language and calendar preferences available on this page.-## Configure appearance defaults+<Frame caption="List view is useful when you prefer to scan work in rows.">+ <img className="block dark:hidden" src="/images/product/list-light.png" alt="List view is useful when you prefer to scan work in rows." />+ <img className="hidden dark:block" src="/images/product/list-dark.png" alt="List view is useful when you prefer to scan work in rows." />+</Frame>-Set the defaults your team prefers:+## Task details in views-- Theme (light/dark)-- Default task view (board/list)-- Compact mode-- Sidebar default open/closed+Choose whether to show task numbers, assignees, dates, labels, and priority indicators. Hiding a field changes its display, not the data on the task.-## Configure task display options+Use **Reset** to return preferences to their defaults.-Toggle the fields you want visible in views:+## Team settings-- Task numbers-- Assignees-- Due dates-- Labels-- Priority indicators+Shared settings live elsewhere:-If needed, use **Reset** in preferences to return to defaults.--## Tune workspace and project settings--Also review:--- **Settings -> Workspace** for workspace-level details (see [Manage workspace labels](/core/functional/manage-workspace-labels))-- **Settings -> Projects** for project general, visibility, integrations, and workflow (see [Outgoing webhooks](/core/integrations/outgoing-webhooks))--## Suggested baseline for most teams--- Default view: Board-- Compact mode: Off initially-- Show assignees, due dates, labels, and priority: On--Adjust once your team has 1-2 weeks of active usage.--## Next--- [Configure project workflows](/core/functional/configure-workflows)-- [Collaborate with your team](/core/functional/collaborate-with-team)+- [Workspace labels](/core/functional/manage-workspace-labels) organize work for everyone.+- [Project workflows](/core/functional/configure-workflows) define status columns.+- [Members and roles](/core/functional/collaborate-with-team) control access.+- [Notifications](/core/functional/account-notifications) control the updates you receive.diff --git a/apps/docs/core/functional/plan-and-execute-tasks.mdx b/apps/docs/core/functional/plan-and-execute-tasks.mdxindex 92451446f..5ab67e5b0 100644--- a/apps/docs/core/functional/plan-and-execute-tasks.mdx+++ b/apps/docs/core/functional/plan-and-execute-tasks.mdx@@ -1,64 +1,73 @@----title: Plan and Execute Tasks in Board and List-description: Create tasks, set metadata, and execute work using Board and List views+title: "Board, List, and task details"+description: "Create tasks, keep them moving, and find the work that needs attention."----Use this workflow to move from planning to execution with minimal overhead.+Open a project and choose **Tasks**. Use **Board** or **List** at the top right to change how the same work is displayed.-## 1. Create tasks quickly+## Add a task-In a project:+On the board, choose **+** in the column where the task belongs. Give it a title that describes the work, then open the task to add details.-1. Open **Board** or **List** view.-2. Click **Create task**.-3. Add a short, action-oriented title.-4. Optionally set description, assignee, priority, due date, and labels.+A title such as “Fix the mobile navigation” is easier to act on than “Mobile issues.” Use the description for context, links, and a checklist of smaller steps.-## 2. Keep task data clean+## Move work on the board-When editing tasks, prioritize:+Drag a task to another column when its status changes. You can also change its status inside the task.-- Clear scope in the description-- One owner (assignee)-- Explicit priority-- Realistic due dates-- Reusable labels+<Frame caption="Board view groups tasks by status. Cards show labels, priority, assignees, and dates.">+ <img className="block dark:hidden" src="/images/product/board-light.png" alt="Board view groups tasks by status. Cards show labels, priority, assignees, and dates." />+ <img className="hidden dark:block" src="/images/product/board-dark.png" alt="Board view groups tasks by status. Cards show labels, priority, assignees, and dates." />+</Frame>-## 3. Execute in Board view+Your project's [workflow settings](/core/functional/configure-workflows) determine the columns and which ones count as done. Move a completed task back to an active column to reopen it.-Board view is best for flow-based execution:+## Scan work in List-1. Pull tasks into active columns.-2. Drag tasks across columns as status changes.-3. Open a task to edit details without losing board context.+Switch to **List** when you want to compare task properties without opening every task.-## 4. Switch to List view for dense review+<Frame caption="List view shows the same project tasks in rows for faster scanning.">+ <img className="block dark:hidden" src="/images/product/list-light.png" alt="List view shows the same project tasks in rows for faster scanning." />+ <img className="hidden dark:block" src="/images/product/list-dark.png" alt="List view shows the same project tasks in rows for faster scanning." />+</Frame>-List view is useful when you need to scan many tasks quickly.+Use **Filter** to narrow the view by status, priority, assignee, dates, or labels. Use **Sort** to change the order. If a task seems to have disappeared, clear your filters and check the backlog before creating another one.-Typical uses:+## Add the details people need-- Reviewing priorities across the project-- Spotting overdue work-- Finding unassigned or under-specified tasks+Open a task to edit its description and properties. Use **Open in full page** from the task panel when you want more space.-## 5. Use filters to focus+<Frame caption="The full task page keeps the description, properties, and conversation together.">+ <img className="block dark:hidden" src="/images/product/task-light.png" alt="The full task page keeps the description, properties, and conversation together." />+ <img className="hidden dark:block" src="/images/product/task-dark.png" alt="The full task page keeps the description, properties, and conversation together." />+</Frame>-The board toolbar supports filtering by:+- **Assignee:** choose the person responsible for the next step. Clear it to leave the task unassigned.+- **Priority:** show what needs attention first. A task can have no priority.+- **Dates:** add start and due dates when the work has a schedule.+- **Labels:** group related work across projects. Removing a label from one task does not delete the workspace label.+- **Comments:** ask questions and record decisions where everyone following the task can find them.-- Status-- Priority-- Assignee-- Due date-- Labels+Use the attachment button, paste, or drag a file into the editor to add supporting material. Images appear inline; other files appear as attachments. On self-hosted instances, an operator must [configure file storage](/core/installation/object-storage-and-image-uploads) first.-Use filters aggressively during standups, planning, and triage.+## Break work into subtasks-## 6. Open full task page when needed+In the task’s **Sub-tasks** section, enter a title and choose **Add**. Each subtask is a task with its own status and assignee. Open it to add more detail. The **Subtask of** link takes you back to its parent.-From the task sheet, use **Open in full page** for deeper edits and focused context.+Use checkboxes in the description for a simple checklist. Use subtasks when each piece needs its own owner or progress tracking.-## Next+## Link related work-- [Plan work in Backlog](/core/functional/backlog-planning)-- [Configure project workflows](/core/functional/configure-workflows)+Open **Relations** and use the add button to find another task. Choose **Related** for a connection or **Blocks** when the current task must be resolved before the other one. The other task shows the inverse **blocked by** relationship.++Use **Remove relation** to unlink the tasks without deleting either task.++## Fill in custom fields++If your project defines extra fields, open **Custom Fields** in task details. These can hold text, numbers, dates, dropdown choices, or a yes/no value. A project manager defines the fields in [Workflow settings](/core/functional/configure-workflows).++## Delete a task++Use **Delete Task** only when you want to remove the task, rather than mark it done. Check the confirmation before proceeding. If deletion or assignment is unavailable, your workspace role may not permit it.++For work you want to keep but are not ready to start, use the [backlog](/core/functional/backlog-planning).diff --git a/apps/docs/core/index.mdx b/apps/docs/core/index.mdxindex 6c913a60f..442a5de29 100644--- a/apps/docs/core/index.mdx+++ b/apps/docs/core/index.mdx@@ -1,38 +1,61 @@----title: Quick Start-description: Get started with Kaneo in minutes+title: "Your first project"+description: "From an empty workspace to a finished task."----## Introduction+You need a Kaneo account and access to an instance. Use [Kaneo Cloud](https://cloud.kaneo.app), join your team's instance, or [host your own](/core/installation/index).-Kaneo <span className='text-fd-muted-foreground text-sm'>(/kəˈneɪ.oʊ/)</span> is a project management tool that gets out of your way. It is designed to be a simple, yet powerful tool for managing your projects. It **works for you** instead of you working for it.+We'll use a website launch as an example. You can follow along with your own project name.-### Components+## 1. Create a workspace-Kaneo is composed of several components:+After signing in, create a workspace for your team, for example **Studio North**. If you already belong to a workspace, use the workspace menu at the top of the sidebar to switch to it.-- API: The backend API that powers the application, it is built with Hono and TypeScript.-- Web: The frontend web application that is built with React and Tailwind CSS.-- Database: The database that is built with PostgreSQL.+A workspace is the boundary for membership and permissions. Separate teams that should not share access belong in separate workspaces.-### Installation+## 2. Add a project-We offer two ways to install Kaneo:+Choose **Add project** in the sidebar and create **Website launch**. Open the project, then choose **Tasks**. Board and List are two views of the same tasks.-**Quick Setup with drim (Recommended)**+<Frame caption="Website launch, with work grouped into To Do, In Progress, In Review, and Done.">+ <img className="block dark:hidden" src="/images/product/board-light.png" alt="Website launch, with work grouped into To Do, In Progress, In Review, and Done." />+ <img className="hidden dark:block" src="/images/product/board-dark.png" alt="Website launch, with work grouped into To Do, In Progress, In Review, and Done." />+</Frame>-For straightforward deployments, use [drim](/core/installation/drim) - a CLI tool that handles everything automatically:+Start with the existing columns. You can [change the workflow](/core/functional/configure-workflows) later.-Install drim using the [version-pinned download and checksum verification](/core/installation/drim#installation), then run:+## 3. Write the first task-```bash-drim setup-```+Use the **+** button in a board column to add a task. Call it **Build the new homepage**, then open it.-**Manual Setup with Docker Compose**+Add a short description of what needs to be true when the task is finished. For example:-For more control or complex setups, follow the manual installation process:+> Publish the new homepage with approved copy, a working contact link, and a layout checked on mobile.-- [Setting up the Docker compose file](/core/installation/docker-compose)-- [Setting up the environment variables](/core/installation/environment-variables)-- [Starting the services](/core/installation/start-services)+Use a checklist for the smaller steps. Set a due date if there is a real deadline, and add a label such as **Design** if it will help you find related work.++<Frame caption="An open task with a description, checklist, assignee, dates, labels, and comments.">+ <img className="block dark:hidden" src="/images/product/task-light.png" alt="An open task with a description, checklist, assignee, dates, labels, and comments." />+ <img className="hidden dark:block" src="/images/product/task-dark.png" alt="An open task with a description, checklist, assignee, dates, labels, and comments." />+</Frame>++## 4. Invite a teammate++Open **Members** in the workspace sidebar and choose **Invite member**. Enter your teammate's email address, then copy the invitation link and share it with them. If your instance has email configured, Kaneo can also deliver the invitation by email.++Your teammate opens the link, signs in with the invited email address, and accepts. Return to the task and choose an assignee. If that control is unavailable, ask a workspace admin to check your role.++See [Members and roles](/core/functional/collaborate-with-team) for pending invitations and access changes.++## 5. Move the work forward++Drag the task into **In Progress** when work starts. Add questions and updates in the task's comments so the context stays with the work.++When the work is finished, move it to the project's done column. If it needs another pass, move it back to an active column.++You now have a shared project with a task your team can follow from start to finish.++<CardGroup cols={2}>+ <Card title="Work with tasks" icon="square-check" href="/core/functional/plan-and-execute-tasks">Explore Board, List, filters, and task details.</Card>+ <Card title="Plan upcoming work" icon="list" href="/core/functional/backlog-planning">Keep ideas in the backlog until they are ready.</Card>+</CardGroup>diff --git a/apps/docs/core/installation/docker-compose.mdx b/apps/docs/core/installation/docker-compose.mdxindex 3251574e6..4c9c759c9 100644--- a/apps/docs/core/installation/docker-compose.mdx+++ b/apps/docs/core/installation/docker-compose.mdx@@ -1,21 +1,27 @@----title: The compose.yml file-description: The Docker Compose file is used to start the required services.+title: "Install with Docker Compose"+description: "Run Kaneo and PostgreSQL, then sign in to your new instance."----## The initial compose file+This guide starts a local instance at `http://localhost:5173`. You need Docker with Compose V2 and a terminal. No repository clone is required.-The first step is to create a Docker Compose file. We will call it `compose.yml`.+## 1. Create a directory-```yml+```bash+mkdir kaneo+cd kaneo+```++Save the following as `compose.yml`:++```yamlservices:postgres:image: postgres:16-alpine- env_file:- - .envenvironment:POSTGRES_USER: ${POSTGRES_USER:-kaneo}POSTGRES_DB: ${POSTGRES_DB:-kaneo}+ POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?Set POSTGRES_PASSWORD in .env}volumes:- postgres_data:/var/lib/postgresql/datarestart: unless-stopped@@ -26,9 +32,9 @@ services:retries: 5kaneo:- image: ghcr.io/usekaneo/kaneo:latest+ image: ghcr.io/usekaneo/kaneo:${KANEO_IMAGE_TAG:-2.28.3}ports:- - "5173:5173"+ - "127.0.0.1:5173:5173"env_file:- .envdepends_on:@@ -36,105 +42,79 @@ services:condition: service_healthyrestart: unless-stoppedhealthcheck:- test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://127.0.0.1:5173/api/health"]+ test: ["CMD", "wget", "--quiet", "--spider", "http://127.0.0.1:5173/api/health"]interval: 30stimeout: 5s- retries: 3start_period: 60s+ retries: 3volumes:postgres_data:```-## The services and volumes--Kaneo uses the following services:--- `postgres`: The PostgreSQL database.-- `kaneo`: The combined API and web container.+This example pins Kaneo to a release so a pull does not unexpectedly upgrade it. See the [release notes](https://github.com/usekaneo/kaneo/releases) when choosing another version.-Additionally, the following volumes are used:+## 2. Add configuration-- `postgres_data`: The PostgreSQL data.+Run this twice to generate two different secrets:-## Required URL configuration+```bash+openssl rand -hex 32+```-Copy `.env.sample` to `.env` and uncomment or set these values:+Create `.env` beside `compose.yml`. Replace both placeholders with the generated values:```env+KANEO_IMAGE_TAG=2.28.3KANEO_CLIENT_URL=http://localhost:5173POSTGRES_DB=kaneoPOSTGRES_USER=kaneo-POSTGRES_PASSWORD=changeme-AUTH_SECRET= # generate: openssl rand -hex 32+POSTGRES_PASSWORD=replace-with-the-first-generated-secret+AUTH_SECRET=replace-with-the-second-generated-secret```-`KANEO_API_URL` defaults to `KANEO_CLIENT_URL/api`; set it explicitly only if you need to override the default (e.g. a reverse proxy changes the path).+Keep this file private. On Linux or macOS, run `chmod 600 .env`.-This keeps the browser on one origin while the container proxies `/api` requests to the internal API process.+The bundled image derives its database connection from `POSTGRES_*` and its API URL from `KANEO_CLIENT_URL`. You do not need to set `DATABASE_URL` or `KANEO_API_URL` for this setup.-For this Compose setup, the bundled Kaneo container reaches PostgreSQL at the service hostname `postgres`.-The database is reachable only inside the Compose network. For host-based development, explicitly add a loopback-only mapping (`127.0.0.1:5432:5432`) and configure `DATABASE_URL` accordingly.+## 3. Start and check the services-## Notes on object storage+```bash+docker compose up -d+docker compose ps+curl --fail http://localhost:5173/api/health+```-Kaneo uses S3-compatible object storage for private uploads in task descriptions and comments.+Allow time for the first database initialization and migrations. Both services should become healthy. If they do not, check:-- Object storage is optional. Kaneo runs without it, but uploads in task descriptions and comments will be unavailable.-- For local/self-hosted setups, MinIO is the recommended option when you want uploads.-- The Kaneo API creates presigned upload URLs and the browser uploads files directly to the configured storage backend.-- Kaneo serves uploaded assets back through its own API, so the bucket does not need to be public.-- If you do not configure object storage, leave the `S3_*` variables unset.-- For a complete MinIO example and backend-specific setup notes, see the [storage backends guide](/core/installation/storage-backends).+```bash+docker compose logs --tail=100 kaneo postgres+```-### Optional MinIO service+Open [localhost:5173](http://localhost:5173), create the initial account, and follow [Your first project](/core/index).-Add this service and volume to your `compose.yml` only if you want uploads:+## 4. Make it available to your team-```yml-services:- minio:- image: minio/minio:latest- command: server /data --console-address ":9001"- env_file:- - .env- ports:- - "9000:9000"- - "9001:9001"- volumes:- - minio_data:/data- restart: unless-stopped+The port is bound to the host's loopback address. To serve Kaneo on a domain, follow the [Nginx and HTTPS guide](/core/reverse-proxy/nginx), then set:-volumes:- minio_data:+```env+KANEO_CLIENT_URL=https://kaneo.example.com```-Set the matching `S3_*` environment variables in your `.env` file. See the [environment variables page](/core/installation/environment-variables).--### Example `.env` values for MinIO+Apply environment changes by recreating the container:-```env-MINIO_ROOT_USER=minioadmin-MINIO_ROOT_PASSWORD=minioadmin--S3_ENDPOINT=http://minio:9000-S3_BUCKET=kaneo-uploads-S3_ACCESS_KEY_ID=minioadmin-S3_SECRET_ACCESS_KEY=minioadmin-S3_REGION=us-east-1-S3_FORCE_PATH_STYLE=true+```bash+docker compose up -d --force-recreate kaneo```-Create the bucket before testing uploads. With MinIO, you can do that from the MinIO Console at `http://localhost:9001`.--### Using `fs` instead of MinIO+A plain restart keeps the old environment. If you use a proxy in another container, connect it to Kaneo's Docker network and proxy to `kaneo:5173` instead of the host's loopback address.-If you want to use [`fs`](https://github.com/ferdzo/fs), you can point the same `S3_*` variables at its endpoint instead of MinIO. Kaneo only needs an S3-compatible API endpoint, credentials, and a bucket.+## Optional features-When using `fs`, keep these differences in mind:+- [Silo](/core/installation/silo) stores images and attachments.+- [SMTP](/core/installation/environment-variables#smtp-configuration) delivers sign-in codes, invitations, and notifications.+- [Sign-in providers](/core/social-providers/custom-oauth) connect your identity provider.-- Set `S3_FORCE_PATH_STYLE=true`.-- Create buckets through the S3 API or CLI, not through a web console.-- Browser uploads may require reverse-proxy CORS handling, because `fs` does not currently implement S3 CORS APIs.+PostgreSQL stays inside the Compose network. Do not publish its port for this deployment.-After creating the compose file, the next step is to set up the environment variables.+Before storing work you care about, set up [backups](/core/operations/backups). Use the [upgrade guide](/core/operations/upgrades) when changing versions.diff --git a/apps/docs/core/installation/drim-migration.mdx b/apps/docs/core/installation/drim-migration.mdxindex 7a5160001..be2e3efe3 100644--- a/apps/docs/core/installation/drim-migration.mdx+++ b/apps/docs/core/installation/drim-migration.mdx@@ -1,153 +1,62 @@----title: Migrating to drim-description: Move an existing Kaneo deployment onto the drim CLI, or update an older drim deployment to the current single-container layout+title: Use drim with an existing deployment+description: Manage an existing Compose stack without replacing its database or regenerating its secrets.----Two migrations are covered here. Both reuse your existing Docker volumes, so your database and uploads stay where they are and no data is copied.+The drim CLI runs Docker Compose commands in your deployment directory. You can use it with an existing stack; you do not need to run `drim setup` again.-## Updating an older drim deployment+## Adopt your existing Compose file-Kaneo used to ship as two images, `api` and `web`, behind a reverse proxy that split traffic between them. It now ships as one container that serves the web app and the API together.+1. Install [drim](/core/installation/drim) and back up your [database, files, and configuration](/core/operations/backups).+2. Stay in the current deployment directory. Moving directories can change the Compose project name and cause Docker to create new volumes.+3. Ensure the main Compose file is named `docker-compose.yml`. drim 0.1.15 checks for that filename. If yours is `compose.yml`, rename it in the same directory and update any scripts that refer to it. Avoid keeping two competing default Compose files.+4. Keep the existing `.env`, `AUTH_SECRET`, database credentials, volumes, networks, and reverse proxy configuration.+5. Validate the configuration with `docker compose config --quiet`.-`drim upgrade` pulls new images but does not rewrite an existing `docker-compose.yml`, so a deployment created before that change keeps running the old layout indefinitely. Check which one you have:+If your normal deployment uses `COMPOSE_FILE`, `COMPOSE_PROJECT_NAME`, profiles, or extra environment files, keep the same Compose context when running drim. For complex setups, direct Docker Compose commands may be clearer.-```bash-grep -E 'image:.*usekaneo' docker-compose.yml-```--Two lines with `usekaneo/api` and `usekaneo/web` mean you are on the old layout. A single `usekaneo/kaneo` line means you are already current and there is nothing to do.--### Steps--Back up the files you are about to edit, so you can put them back:+Run these commands from that directory when needed:```bash-STAMP=$(date +%Y%m%d-%H%M%S)-cp docker-compose.yml docker-compose.yml.bak-$STAMP-cp Caddyfile Caddyfile.bak-$STAMP+drim start # docker compose up -d+drim stop # docker compose stop+drim restart # restart existing containers+drim configure # edit .env and offer to apply changes```-Pull the image first, so the switchover is a quick container swap rather than a download:+Use `drim restart --recreate` after an environment change. A plain restart retains the container’s old environment. `drim upgrade` pulls the images selected in your Compose file and applies them; it does not rewrite the file or change a pinned version for you.-```bash-docker pull ghcr.io/usekaneo/kaneo:latest-```+## Replace an older two-container layout-Replace the `api` and `web` services in `docker-compose.yml` with one `kaneo` service. Leave `postgres`, the volumes, and any services you added yourself untouched:--```yaml- kaneo:- image: ghcr.io/usekaneo/kaneo:latest- env_file: .env- depends_on:- postgres:- condition: service_healthy- restart: unless-stopped- healthcheck:- test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://127.0.0.1:5173/api/health"]- interval: 30s- timeout: 5s- start_period: 60s- retries: 3- networks:- - kaneo-```+If your Compose file still contains separate `usekaneo/api` and `usekaneo/web` images, follow [Move to the bundled container](/core/installation/migration). `drim upgrade` alone does not combine those services.-Update anything that pointed at the old services. In `depends_on` entries elsewhere, replace `api` and `web` with `kaneo`. In your reverse proxy, send everything to the one service instead of splitting on path, because the container routes `/api` internally:+For a Caddy service on the same Docker network, the application upstream becomes:```caddyfile-your-domain.com {- reverse_proxy http://kaneo:5173+kaneo.example.com {+ reverse_proxy kaneo:5173encode gzip}```-Apply it:--```bash-docker compose up -d --remove-orphans-```--<Warning>-If your reverse proxy config is bind-mounted as a single file, recreate that container rather than reloading it. Replacing the file with `mv` gives it a new inode, and the running container keeps reading the old one, so a reload silently applies stale config:+Keep Caddy’s existing certificate volumes. If you replaced a bind-mounted Caddyfile, recreate the proxy container so it sees the current file:```bashdocker compose up -d --force-recreate caddy```-</Warning>--### Verify--```bash-docker compose ps-curl -s https://your-domain.com/api/health-```--You want every service up, the Kaneo container reporting healthy once its start period elapses, and `{"status":"ok"}` from the health endpoint.--### Rollback--Restore the backed-up files and recreate:--```bash-cp docker-compose.yml.bak-$STAMP docker-compose.yml-cp Caddyfile.bak-$STAMP Caddyfile-docker compose up -d --force-recreate-```--## Moving an existing Kaneo onto drim--If you deployed Kaneo by hand and want drim to manage it, the goal is to have drim generate its files and then point them at the volumes you already have.--Record the names of your existing volumes and your current environment values:--```bash-docker volume ls | grep -i kaneo-```--Complete the [verified drim installation](/core/installation/drim#installation)-before stopping the current stack. Then run setup in a new directory:--```bash-docker compose down-mkdir ~/kaneo && cd ~/kaneo-drim setup --domain=your-domain.com-drim stop-```--Point the generated `docker-compose.yml` at your existing database volume by declaring it external, using the exact name from `docker volume ls`:--```yaml-volumes:- postgres_data:- external: true- name: your_existing_volume_name-```--Copy your previous credentials into the generated `.env`, in particular `POSTGRES_USER`, `POSTGRES_PASSWORD`, `POSTGRES_DB`, `DATABASE_URL` and `AUTH_SECRET`. A different `AUTH_SECRET` invalidates every existing session, so reuse the old value unless you intend to sign everyone out.--```bash-drim configure # opens .env, applies changes on save-```--Then start and verify as above.--### Using your own reverse proxy--If you already run nginx, Traefik or similar, choose `--no-reverse-proxy` at setup so drim does not start Caddy on ports 80 and 443, and point your proxy at Kaneo on port 5173.--## Common issues--**Database connection failed.** The credentials in `.env` do not match the ones the volume was created with. `DATABASE_URL` must agree with `POSTGRES_USER`, `POSTGRES_PASSWORD` and `POSTGRES_DB`.--**Volume not found.** The `name:` under an external volume must match `docker volume ls` exactly, including any project-name prefix from the old deployment.-**Port already in use.** Something else holds 80 or 443, usually a system nginx or the old stack still running. Stop it, or use `--no-reverse-proxy`.+Use your actual proxy service name. A host-based proxy uses the published application port instead of Docker’s `kaneo` hostname.-**Everyone was signed out.** `AUTH_SECRET` changed. Restore the previous value.+## Check the result-## After migrating+Check `docker compose ps` and request `/api/health` through your public URL. Sign in, open existing tasks, and check an existing attachment. Confirm that the database is the original one before inviting anyone to use the instance.-Keep the old containers' volumes until you are confident, then remove the stale containers and images. Volumes are the only thing holding your data, so remove those last and deliberately.+| Problem | What to check |+| --- | --- |+| drim cannot find a deployment | Run it beside `docker-compose.yml`. |+| Kaneo looks like a new installation | Check the Compose project name, mounted database volume, and database URL. Stop the application before creating new data. |+| Database login fails | Use the original database credentials. Changing `.env` does not reset an existing PostgreSQL password. |+| Everyone was signed out | Check whether `AUTH_SECRET` changed. |+| Proxy cannot reach Kaneo | Check the service name, shared network, and port 5173. |-Set up off-site backups if you have not already. A copy on the same machine does not survive losing that machine.+Keep the backup and original configuration until the deployment is verified. If a newer image migrated the database, [recovery](/core/operations/backups) requires its matching backup, not just an older Compose file.diff --git a/apps/docs/core/installation/drim.mdx b/apps/docs/core/installation/drim.mdxindex f2cf49c82..6218338f3 100644--- a/apps/docs/core/installation/drim.mdx+++ b/apps/docs/core/installation/drim.mdx@@ -12,8 +12,8 @@ It suits straightforward deployments. If you need a custom topology, extra servi## InstallationInstall Docker and Docker Compose using your operating system's signed packages-before running setup. Then install the fixed [drim v0.1.8 release](https://github.com/usekaneo/drim/releases/tag/v0.1.8)-using the reviewed checksums below. The download is saved to a temporary file and+before running setup. Then install the fixed [drim v0.1.15 release](https://github.com/usekaneo/drim/releases/tag/v0.1.15)+using the release-asset SHA-256 checksums below. The download is saved to a temporary file andverified before it is made executable; it does not run an installation script.```sh@@ -22,16 +22,16 @@ verified before it is made executable; it does not run an installation script.case "$(uname -s)-$(uname -m)" inLinux-x86_64)drim_asset=drim_Linux_x86_64- drim_sha256=dbc57af416dac4d6f4302a77cac22c0e1887afcfdf55173c3113ae1f4712bd89 ;;+ drim_sha256=1961180bd6972e34c6ce9077cedc2524795d9fa717001e1bdec9e36817ca44a8 ;;Linux-aarch64|Linux-arm64)drim_asset=drim_Linux_arm64- drim_sha256=dd78bea7b40c4e071887605823f6d999829c7500787f27a86ab2166697f0520f ;;+ drim_sha256=58ddb9ed25491c2593f9f6ac3dc27741df75d4f7f05ef9338ace86c6d5aa42a9 ;;Darwin-x86_64)drim_asset=drim_Darwin_x86_64- drim_sha256=d2d6f8e1ab3e7725de0a559626a10660b6507cd85955c5bfcd1419de07e8ad29 ;;+ drim_sha256=2019ea560f62f5788c521f070013db5e7fa058ea01b2f2eb7cdbe77e5dae71cb ;;Darwin-arm64)drim_asset=drim_Darwin_arm64- drim_sha256=065d0611b61e83284f3ffa620c9cc12b83ebdab74ce09f402ed70eea795713ea ;;+ drim_sha256=58f353ca36067756ef7796ac79cfddbc4ef9568e051295b8b464782b496b76ab ;;*) echo "Unsupported platform; use a supported Linux or macOS system." >&2; exit 1 ;;esacdrim_tmp=$(mktemp -d)@@ -39,7 +39,7 @@ verified before it is made executable; it does not run an installation script.cd "$drim_tmp"curl --fail --show-error --silent --location \--proto '=https' --proto-redir '=https' --tlsv1.2 \- "https://github.com/usekaneo/drim/releases/download/v0.1.8/$drim_asset" \+ "https://github.com/usekaneo/drim/releases/download/v0.1.15/$drim_asset" \--output drimif command -v sha256sum >/dev/null 2>&1; thenprintf '%s drim\n' "$drim_sha256" | sha256sum -c -@@ -55,8 +55,7 @@ Add `~/.local/bin` to your shell's `PATH`, or use `~/.local/bin/drim` in place o`drim` below. WSL uses the Linux asset matching its architecture. Stop on achecksum mismatch; do not replace the expected checksum with one supplied bythe failed download. These fixed digests pin the published bytes, not a claim-that the release was independently audited. Upgrading drim requires selecting-and reviewing a new release and updating its expected digest.+that the release was independently audited. When updating drim, select a release and update its expected digest together.## Quick start@@ -123,6 +122,7 @@ GITHUB_OAUTH_CLIENT_SECRET=your_client_secretSMTP_HOST=smtp.example.comSMTP_PORT=587+SMTP_SECURE=falseSMTP_PASSWORD=your-password@@ -153,7 +153,7 @@ sudo usermod -aG docker $USERdrim upgrade```-This pulls the latest images and restarts the changed services. Your data lives in Docker volumes and is not touched.+Back up your [database, files, and configuration](/core/operations/backups) first. This pulls the selected images and recreates changed services. Data volumes are retained, but the API can migrate the database when it starts. See [Upgrade Kaneo](/core/operations/upgrades) for checks and recovery.To update drim itself, repeat the verified installation procedure with a newlyreviewed release and its fixed checksum. The built-in updater follows the latest@@ -168,7 +168,7 @@ Deployments created before Kaneo moved to a single container still run the older```bashgit clone https://github.com/usekaneo/drim.gitcd drim-git checkout --detach 2c21e713869c97dda413e4135ffaf89ece8156c8+git checkout --detach f1e404916304699404ca06e9c94b3cf9124b878f# Review this fixed source revision and its dependencies before building.go build -mod=readonly -o drim .```diff --git a/apps/docs/core/installation/environment-variables.mdx b/apps/docs/core/installation/environment-variables.mdxindex 26b00f51a..f00ef989f 100644--- a/apps/docs/core/installation/environment-variables.mdx+++ b/apps/docs/core/installation/environment-variables.mdx@@ -1,39 +1,24 @@---title: Environment variables-description: The environment variables are used to configure the application.+description: Look up configuration names, defaults, and when to set them.---## Set up the file-The environment variables are used to configure the application. We will use a `.env` file to store the variables.+For Docker Compose, put server settings in `.env` beside your Compose file. Start with the [complete installation guide](/core/installation/docker-compose), then use this page to add optional features.For the sample environment file, see the [example .env file](https://github.com/usekaneo/kaneo/blob/main/.env.sample).-The variables are split up into the following sections:--- [General URLs](#general-urls)-- [Database](#database)-- [Authentication](#authentication)-- [MCP](#mcp)-- [Object Storage](#object-storage)-- [Access Control](#access-control)-- [GitHub SSO](#github-sso)-- [GitHub integration](#github-integration)-- [Google SSO](#google-sso)-- [Discord SSO](#discord-sso)-- [Custom OAuth/OIDC](#custom-oauth-oidc)-- [Redis](#redis)-- [SMTP Configuration](#smtp-configuration)--## Required variables+## Core configuration### General URLs-This section will cover all the variables related to the general URLs.+For the bundled image, set `KANEO_CLIENT_URL` and leave `KANEO_API_URL` unset. The API URL defaults to your client URL plus `/api`. Set both explicitly only for a separate API deployment or a different proxy path.Name | Description |--- | --- || `KANEO_CLIENT_URL` | The URL of the web application.-| `KANEO_API_URL` | The URL of the API.+| `KANEO_API_URL` | Public API URL. Derived by the bundled image; set it explicitly for a separate API or host-native development. |+| `CORS_ORIGINS` | Optional comma-separated list of allowed browser origins, for example `https://kaneo.example.com`. When omitted, HTTP CORS uses `KANEO_CLIENT_URL`. |The web container embeds only `KANEO_API_URL`, `KANEO_CLIENT_URL`, and`KANEO_TURNSTILE_SITE_KEY` into browser assets at startup. These values are public;@@ -45,22 +30,25 @@ URL usable. Recreate the container when changing its environment.### Database-This section will cover all the variables related to the database.+The bundled Compose setup derives its database connection from `POSTGRES_*`. Set `DATABASE_URL` when using an external database; it takes precedence. The API needs a server-reachable database address, not a browser URL.Name | Description |--- | --- |-| `DATABASE_URL` | The full PostgreSQL connection string, in the format `postgresql://[user]:[password]@[host]:[port]/[database]`. Example: `postgresql://kaneo:kaneo@localhost:5432/kaneo`. The user/password/database must match the `POSTGRES_*` values below.+| `DATABASE_URL` | The full PostgreSQL connection string, in the format `postgresql://[user]:[password]@[host]:[port]/[database]`. Example: `postgresql://kaneo:kaneo@localhost:5432/kaneo`. Use the actual credentials for that database. This value overrides `POSTGRES_*`. Percent-encode special characters in URL credentials.| `POSTGRES_DB` | The name of the PostgreSQL database. Example: `kaneo`.| `POSTGRES_USER` | The username for the PostgreSQL database. Example: `kaneo`.| `POSTGRES_PASSWORD` | The password for the PostgreSQL database. Use a strong value in production.+| `POSTGRES_HOST` | Database hostname for derived configuration. Default: `postgres`; use `localhost` for a host-native API connected to local PostgreSQL. |+| `POSTGRES_PORT` | Database port for derived configuration. Default: `5432`. |### Authentication-This section will cover all the variables related to the authentication.+Keep `AUTH_SECRET` stable across restarts and include it in your protected configuration backup. The bundled image can generate a temporary secret if it is unset; a host-native API requires you to provide one.Name | Description |--- | --- |-| `AUTH_SECRET` | The secret key for the JWT token. **Must be at least 32 characters long**, use a long, random value in production. Example: use `openssl rand -base64 32` to generate a secure key in Linux/macOS.+| `AUTH_SECRET` | The secret used by the authentication service. **Must be at least 32 characters long**, use a long, random value in production. Example: use `openssl rand -base64 32` to generate a secure key in Linux/macOS.+| `COOKIE_DOMAIN` | Optional cookie domain override. Leave unset for host-only cookies. Set a parent domain only when your deployment needs cookies shared across its trusted subdomains. || `DEVICE_AUTH_CLIENT_IDS` | **Optional.** Comma-separated list of allowed device authorization client IDs. When unset, Kaneo implicitly allows `kaneo-cli` and `kaneo-mcp` by default, so no extra configuration is required for the CLI or MCP. Override only when you need additional trusted clients, for example `kaneo-cli,kaneo-mcp,my-desktop-app`. |@@ -76,17 +64,17 @@ Name | Description | Default |Kaneo uses S3-compatible object storage for private uploads in task descriptions and task comments.-MinIO is the easiest local option and the primary tested target. You can also use other S3-compatible storage backends such as AWS S3, Cloudflare R2, or [`fs`](https://github.com/ferdzo/fs).+For self-hosted storage, follow the [Silo setup](/core/installation/silo). For managed storage, see [AWS S3 and other providers](/core/installation/storage-backends). The endpoint must be reachable by both the API and the browser.Name | Description | Default |--- | --- | --- |-| `S3_ENDPOINT` | The S3-compatible API endpoint used by the Kaneo API for presigned uploads. Example: `http://minio:9000`. | |+| `S3_ENDPOINT` | The S3-compatible API endpoint used by the Kaneo API for presigned uploads. Example: `https://files.example.com`. | || `S3_BUCKET` | The bucket Kaneo will use for uploaded files. | || `S3_ACCESS_KEY_ID` | Access key used by the Kaneo API to create presigned upload URLs. Optional: leave unset (together with `S3_SECRET_ACCESS_KEY`) to use the default AWS credential provider chain (IAM role / IRSA / instance profile). | || `S3_SECRET_ACCESS_KEY` | Secret key used by the Kaneo API to create presigned upload URLs. Must be set together with `S3_ACCESS_KEY_ID`, or left unset for IAM-role-based access. | || `S3_REGION` | The storage region used for request signing. | `us-east-1` || `S3_PUBLIC_BASE_URL` | Optional public base URL for uploaded assets. Kaneo does not require this for the current private asset flow. | |-| `S3_FORCE_PATH_STYLE` | Use path-style S3 URLs. This should usually be `true` for MinIO and `fs`. | `true` |+| `S3_FORCE_PATH_STYLE` | Use path-style S3 URLs. Set to `true` for Silo. Check other providers' endpoint requirements. | `true` || `S3_MAX_IMAGE_UPLOAD_BYTES` | Maximum allowed upload size in bytes for images and other uploaded files. | `10485760` || `S3_KEY_PREFIX` | Optional prefix prepended to all S3 object keys. Useful for sharing a single bucket across multiple environments (e.g. `staging/`, `prod/kaneo/`). Trailing slashes are trimmed automatically. | || `S3_PRESIGN_TTL_SECONDS` | How long presigned upload URLs remain valid. | `300` |@@ -102,15 +90,16 @@ only the small `{"type":"ping"}` text keepalive, with a 64-byte message limit.Name | Description | Default |--- | --- | --- |+| `DISABLE_WORKSPACE_CREATION` | Allow only instance administrators to create workspaces. Workspace ownership or a workspace admin role does not grant this instance-wide permission. | `false` || `DISABLE_GUEST_ACCESS` | Disable anonymous/guest sign-in. Guests are also blocked before initial instance setup and when registration, local registration, or the local login form is disabled. | `false` || `DISABLE_REGISTRATION` | Disable public user registration. When set to `true`, the sign-up option will not be shown on the sign-in page and new user creation is blocked (including via SSO). **Note:** Invited password signups must present the matching invitation link. OAuth, OTP, and magic-link signups may match an invitation by email only after that email has been verified. Sign-in emails (OTP codes and magic links) are only sent to existing accounts or pending invitations. The first non-guest user can complete initial instance setup. | `false` || `DISABLE_PASSWORD_REGISTRATION` | Disable local account creation through password, email OTP, magic link, and guest access. Existing accounts can still use email sign-in unless `DISABLE_LOGIN_FORM=true`. Social/OIDC registration remains available unless `DISABLE_REGISTRATION=true`. The initial administrator can still be created through password signup. | `false` || `DISABLE_EMAIL_OTP_SIGN_IN` | When SMTP is configured, sign-in uses email verification codes by default. Set to `true` to use email/password sign-in instead. Workspace invitation and password-reset emails still use SMTP. | `false` |-| `DISABLE_LOGIN_FORM` | Hide the email/password login form on the sign-in page. When set to `true`, only SSO/OAuth buttons are shown. Useful when you want to enforce authentication exclusively through an external identity provider. | `false` |+| `DISABLE_LOGIN_FORM` | Disable local email sign-in and hide the form on the sign-in page. When set to `true`, only SSO/OAuth buttons are shown. Useful when you want to enforce authentication exclusively through an external identity provider. | `false` || `CUSTOM_OAUTH_AUTO_LOGIN` | Automatically redirect to the custom OAuth/OIDC provider instead of showing the sign-in page. When set to `true`, users are immediately redirected to your identity provider without seeing the login page. Requires a custom OAuth provider to be configured. | `false` |<Warning>- Before enabling SSO-only access with `DISABLE_LOGIN_FORM=true` or `CUSTOM_OAUTH_AUTO_LOGIN=true` on an existing installation, make sure existing local accounts have verified email addresses. OAuth/OIDC identities cannot be linked to an unverified local account, and affected users will receive `error=account_not_linked`. Keep the login form available until those users have signed in with an email OTP or magic link. If SSO-only access is already enabled, temporarily set both options to `false`, restart Kaneo, and let affected users complete an email sign-in before restoring the SSO-only settings.+ Before enabling SSO-only access with `DISABLE_LOGIN_FORM=true` or `CUSTOM_OAUTH_AUTO_LOGIN=true` on an existing installation, make sure existing local accounts have verified email addresses. OAuth/OIDC identities cannot be linked to an unverified local account, and affected users will receive `error=account_not_linked`. Keep the login form available until those users have signed in with an email OTP or magic link. If SSO-only access is already enabled, temporarily set both options to `false`, recreate the Kaneo container, and let affected users complete an email sign-in before restoring the SSO-only settings.</Warning>### Proxies@@ -127,6 +116,7 @@ Name | Description | Default |Name | Description | Default |--- | --- | --- |+| `NOTIFICATION_SECRET_ENCRYPTION_KEY` | Required to store personal notification tokens and webhook signing secrets. Generate a random value, keep it stable, and include it in protected configuration backups. Changing or losing it prevents decryption of existing secrets. | Unset || `KANEO_ALLOW_PRIVATE_WEBHOOK_DESTINATIONS` | Allow outbound notification destinations (ntfy, Gotify, generic webhooks) and self-managed Gitea or GitLab instances that resolve to private or non-routable addresses. Off by default to prevent SSRF; the `http`/`https` requirement still applies. Only enable on a trusted, isolated deployment. | `false` |### GitHub SSO@@ -242,8 +232,26 @@ When upgrading, remove `SMTP_IGNORE_TLS=true` and verify delivery with the corre## Authentication CAPTCHA-When `TURNSTILE_SECRET_KEY` is configured on the API, deploy the matching `VITE_TURNSTILE_SITE_KEY` with the web app. The API validates the token at password signup, social/OIDC initiation, guest sign-in, OTP sending (including resend), and magic-link initiation. Tokens are single-use; clients must obtain a fresh token for each attempt. OAuth callbacks and OTP redemption validate their own state/code and do not redeem the CAPTCHA token again.+When `TURNSTILE_SECRET_KEY` is configured on the API, set the matching public `KANEO_TURNSTILE_SITE_KEY` on the bundled container or standalone web container. For local Vite development, use `VITE_TURNSTILE_SITE_KEY` in `apps/web/.env.local` instead. The API validates the token at password signup, social/OIDC initiation, guest sign-in, OTP sending (including resend), magic-link initiation, and password-reset requests. Tokens are single-use; clients must obtain a fresh token for each attempt. OAuth callbacks and OTP redemption validate their own state/code and do not redeem the CAPTCHA token again.The widget uses the action `auth`. The API requires that action and the exact frontend hostname from `KANEO_CLIENT_URL`, and rejects verification failures, redirects and timeouts. Update the API and web app together when adopting this check. Custom clients must include the token in the `x-turnstile-token` header. Automatic OIDC redirection pauses at the sign-in page when a CAPTCHA widget is configured so the user can complete it.No secret configured means CAPTCHA is disabled, as on self-hosted instances that opt out. This does not bypass registration or guest-access restrictions.++## Error reporting++API reporting is opt-in. Leave `SENTRY_DSN` unset to disable it.++| Variable | Meaning | Default |+| --- | --- | --- |+| `SENTRY_DSN` | Destination for API error reports | Unset |+| `SENTRY_ENVIRONMENT` | Environment tag | `NODE_ENV`, then `production` |+| `SENTRY_RELEASE` | Release identifier | Application version |+| `SENTRY_TRACES_SAMPLE_RATE` | Fraction of requests traced, from 0 to 1 | `0` |+| `SENTRY_PROFILES_SAMPLE_RATE` | Profiling sample rate, from 0 to 1 | `0` |++The browser reads `VITE_SENTRY_DSN` when it is built. The current web container renderer does not replace `KANEO_SENTRY_DSN` at startup, so setting that variable on a running container does not enable browser reporting.++## Cloud mode++`KANEO_CLOUD=true` enables hosted-service behavior, including cloud billing and additional signup and invitation restrictions. Leave it unset for a normal self-hosted instance. CAPTCHA is controlled by `TURNSTILE_SECRET_KEY` independently of this flag.diff --git a/apps/docs/core/installation/index.mdx b/apps/docs/core/installation/index.mdxindex 2980c0883..6b5ab97ed 100644--- a/apps/docs/core/installation/index.mdx+++ b/apps/docs/core/installation/index.mdx@@ -1,52 +1,41 @@----title: Installation Overview-description: Choose how to install Kaneo - quick setup with drim or manual Docker Compose+title: "Self-host Kaneo"+description: "Choose a deployment method and know what you need to run it."----## Choose Your Installation Method+Kaneo runs as one application container plus PostgreSQL. You can add file storage and email when you need them. Redis is only needed when multiple API instances must share live updates.-Kaneo offers two installation methods depending on your needs:+## Choose your setup-### Quick Setup with drim (Recommended)+| Setup | Choose this when… |+| --- | --- |+| [Docker Compose](/core/installation/docker-compose) | You want to see and control the configuration. Start here for a local trial or an existing server. |+| [drim](/core/installation/drim) | You want a CLI to generate the deployment and set up Caddy for HTTPS. |+| [Coolify](/core/deployments/coolify) | You already deploy applications through Coolify. |+| [Railway](/core/deployments/railway) | You want a hosted deployment without managing a server. |+| [Helm](https://github.com/usekaneo/kaneo/tree/main/charts/kaneo) | You already operate a Kubernetes cluster. |-[drim](/core/installation/drim) is a CLI tool designed for straightforward Kaneo deployments. It's perfect for:+For a small installation, plan for at least 2 GB of memory and 10 GB of free disk as a starting point. Leave additional space for database growth, uploaded files, and backups. Compose deployments need Docker and Docker Compose V2.-- Getting started quickly with minimal configuration-- Local development environments-- Simple production deployments with a single domain-- Automatic HTTPS setup+## What runs where-Install drim using the [version-pinned download and checksum verification](/core/installation/drim#installation), then run:--```bash-drim setup+```mermaid+flowchart LR+ Browser[Your browser] -->|HTTPS| Proxy[Reverse proxy]+ Proxy --> Kaneo[Kaneo: web app and API]+ Kaneo --> DB[(PostgreSQL)]+ Browser -->|File uploads| Storage[(Optional S3 storage)]+ Kaneo -->|Read and validate files| Storage```-### Manual Setup with Docker Compose--For more control over your deployment or complex setups, use the manual installation process:--1. [Create the Docker Compose file](/core/installation/docker-compose)-2. [Configure environment variables](/core/installation/environment-variables)-3. [Start the services](/core/installation/start-services)--This method is ideal for:-- Custom networking configurations-- Multiple domains or complex reverse proxy setups-- Integration with existing infrastructure-- Advanced customization needs--## Requirements--Both methods require:--- Docker 20.10+-- Docker Compose V2-- 2GB RAM minimum-- 10GB disk space+PostgreSQL stores accounts, projects, tasks, comments, and upload records. File contents live in your configured object storage. Account avatars are stored in PostgreSQL.-**Supported Platforms:** Linux, macOS, Windows (WSL)+## Before inviting your team-## Next Steps+1. Put the instance behind [HTTPS](/core/reverse-proxy/nginx).+2. Create the initial administrator account before opening registration to others.+3. Configure [email and access settings](/core/installation/environment-variables).+4. Add [Silo file storage](/core/installation/silo) if your team needs attachments.+5. Make a [backup and test a restore](/core/operations/backups).-Choose your preferred method and follow the corresponding guide to get Kaneo up and running.+Then follow [Your first project](/core/index).diff --git a/apps/docs/core/installation/migration.mdx b/apps/docs/core/installation/migration.mdxindex edda80c52..daac5045f 100644--- a/apps/docs/core/installation/migration.mdx+++ b/apps/docs/core/installation/migration.mdx@@ -1,251 +1,79 @@----title: Migration guide-description: How to upgrade from the two-container setup (api + web) to the combined kaneo container introduced in v2.6.0.+title: Move to the bundled container+description: Replace separate API and web containers while keeping your existing database and configuration.----## What changed in v2.6.0+Use this guide only if your deployment still has separate `ghcr.io/usekaneo/api` and `ghcr.io/usekaneo/web` services. The bundled `ghcr.io/usekaneo/kaneo` image serves both on port 5173. Separate images remain available for deployments that need them.-This release replaces the separate `api` and `web` containers with a single `kaneo` container. nginx runs on port 5173 and proxies `/api/` requests to the internal Node API. Everything else (the database, volumes, environment variables) works the same.+If you already use the bundled image, follow [Upgrade Kaneo](/core/operations/upgrades). For drim-managed deployments, see [Migrate to drim](/core/installation/drim-migration).-Three areas require changes when upgrading:+## Before changing the layout-1. Docker Compose: replace the `api` and `web` services with `kaneo`-2. Environment variables: `KANEO_API_URL` and `DATABASE_URL` are now optional-3. Helm chart: all `api.*` and `web.*` values moved under `kaneo.*` (chart version 0.3.0)+1. [Back up the database, uploaded files, and configuration](/core/operations/backups). Test that you can restore the database.+2. Record the existing image version and choose a target release after reading its release notes.+3. Keep the same Compose project name, database volume, PostgreSQL major version, database credentials, and `AUTH_SECRET`.+4. Save copies of your Compose file, `.env`, and reverse-proxy configuration.------## Docker Compose+Changing the application layout does not require replacing PostgreSQL or moving its data. A newer Kaneo image can run database migrations, so an older image alone is not a complete rollback.-### Before--```yml-services:- postgres:- image: postgres:16-alpine- env_file:- - .env- ports:- - "5432:5432"- volumes:- - postgres_data:/var/lib/postgresql/data- restart: unless-stopped-- api:- image: ghcr.io/usekaneo/api:latest- ports:- - "1337:1337"- env_file:- - .env- depends_on:- - postgres- restart: unless-stopped-- web:- image: ghcr.io/usekaneo/web:latest- ports:- - "5173:5173"- env_file:- - .env- depends_on:- - api- restart: unless-stopped--volumes:- postgres_data:-```+## Replace the application services-### After (current recommended configuration)--```yml-services:- postgres:- image: postgres:16-alpine- env_file:- - .env- environment:- POSTGRES_USER: ${POSTGRES_USER:-kaneo}- POSTGRES_DB: ${POSTGRES_DB:-kaneo}- volumes:- - postgres_data:/var/lib/postgresql/data- restart: unless-stopped- healthcheck:- test: ["CMD-SHELL", "pg_isready -U \"$${POSTGRES_USER:-kaneo}\" -d \"$${POSTGRES_DB:-kaneo}\""]- interval: 10s- timeout: 5s- retries: 5+In your existing Compose file, replace `api` and `web` with this service. Set `KANEO_IMAGE_TAG` in `.env` to your chosen release tag. Keep the existing database service and volumes.+```yamlkaneo:- image: ghcr.io/usekaneo/kaneo:latest+ image: ghcr.io/usekaneo/kaneo:${KANEO_IMAGE_TAG:?Set KANEO_IMAGE_TAG in .env}+ env_file: .envports:- - "5173:5173"- env_file:- - .env- depends_on:- postgres:- condition: service_healthy+ - "127.0.0.1:5173:5173"restart: unless-stopped--volumes:- postgres_data:-```--Remove the `api` and `web` service blocks and add the `kaneo` service. The current recommended `postgres` configuration adds a healthcheck and keeps the database on the internal Compose network without publishing port 5432. Preserve the actual database name, user and password from your existing installation in `.env`; defaults do not rename an existing database.-------## Environment variables--### KANEO_API_URL is now optional--Previously both `KANEO_CLIENT_URL` and `KANEO_API_URL` were required. Now `KANEO_API_URL` is derived automatically from `KANEO_CLIENT_URL`:--```-KANEO_API_URL = KANEO_CLIENT_URL + "/api"-```--Remove `KANEO_API_URL` from your `.env` unless you need to override it (for example, when a reverse proxy changes the API path).--**Before:**-```env-KANEO_CLIENT_URL=https://kaneo.example.com-KANEO_API_URL=https://kaneo.example.com/api```-**After:**-```env-KANEO_CLIENT_URL=https://kaneo.example.com-# KANEO_API_URL is set automatically to https://kaneo.example.com/api-```+This port binding assumes your reverse proxy runs on the host. If the proxy is another container, attach Kaneo to its network and point it at `http://kaneo:5173` instead. Preserve any existing networks needed to reach the database or storage.-### DATABASE_URL is now optional+Set `KANEO_CLIENT_URL` to your public web origin. In a same-origin deployment, remove an old `KANEO_API_URL` override that points to the separate API service: the bundled entrypoint derives `KANEO_CLIENT_URL` plus `/api`.-For the bundled image, `DATABASE_URL` is derived from `POSTGRES_USER`, `POSTGRES_PASSWORD`, `POSTGRES_DB`, and the default Compose hostname if you leave it unset:+Keep `DATABASE_URL` if it already identifies the correct database. Alternatively, the bundled image can derive it from `POSTGRES_USER`, `POSTGRES_PASSWORD`, `POSTGRES_DB`, `POSTGRES_HOST` (default `postgres`), and `POSTGRES_PORT` (default `5432`). Preserve the existing values; changing an environment variable does not rename a database or reset its password.-```-postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB}-```+Keep your existing `AUTH_SECRET`. Generating a new one invalidates existing sessions.-If you were setting `DATABASE_URL` explicitly with the same values, you can remove it.-Keep it if you use an external database, a non-default hostname, or a host-native API process that should connect through `localhost` instead of the Compose hostname.+## Switch traffic-**Before:**-```env-POSTGRES_DB=kaneo-POSTGRES_USER=kaneo-POSTGRES_PASSWORD=changeme-DATABASE_URL=postgresql://kaneo:changeme@postgres:5432/kaneo-```+Validate the edited file and pull the selected image before stopping the old application:-**After:**-```env-POSTGRES_DB=kaneo-POSTGRES_USER=kaneo-POSTGRES_PASSWORD=changeme-# DATABASE_URL is derived automatically+```bash+docker compose config --quiet+docker compose pull kaneo```-### AUTH_SECRET fallback behavior--If `AUTH_SECRET` is not set, the container generates a random 64-character hex secret at startup and prints a warning to stderr. This means sessions will not survive container restarts.--Set a stable secret to avoid losing active sessions on restart:+Stop the old `api` and `web` services using your saved Compose file. Start the new service:```bash-openssl rand -hex 32-```--```env-AUTH_SECRET=your_generated_secret_here+docker compose up -d kaneo+docker compose logs --tail=100 kaneo```----+Update your proxy to send web, API, and WebSocket requests to port 5173. See [Nginx and HTTPS](/core/reverse-proxy/nginx). Remove dependencies on the old service names from other services in your Compose file.-## Helm chart (0.2.0 → 0.3.0)+Check `/api/health` through the public URL, then sign in, open an existing project, edit a test task, and check an existing attachment. Remove the stopped API and web containers only after those checks pass. Keep your backups.-Chart version 0.3.0 is a breaking change. All `api.*` and `web.*` value keys have moved under `kaneo.*`.+## Migrating an old Helm values file-### Changed value keys+The bundled chart uses `kaneo.*` values. Old split-container charts used `api.*` and `web.*`. Compare your file with the [values for your selected chart release](https://github.com/usekaneo/kaneo/tree/main/charts/kaneo) before upgrading.-| Old key | New key |-|---|---|-| `api.image.repository` | `kaneo.image.repository` |-| `api.image.tag` | `kaneo.image.tag` |-| `api.image.pullPolicy` | `kaneo.image.pullPolicy` |-| `api.service.type` | `kaneo.service.type` |-| `api.service.port` | `kaneo.service.port` |+| Old setting | Bundled chart setting |+| --- | --- |+| `api.image.*` | `kaneo.image.*`, with repository `ghcr.io/usekaneo/kaneo` || `api.resources` | `kaneo.resources` |-| `api.env.clientUrl` | `kaneo.env.clientUrl` |-| `api.env.authSecret` | `kaneo.env.authSecret` |-| `api.env.existingSecret` | `kaneo.env.existingSecret` |-| `api.env.disableRegistration` | `kaneo.env.disableRegistration` |-| `api.env.disablePasswordRegistration` | `kaneo.env.disablePasswordRegistration` |-| `api.env.database` | `kaneo.env.database` |-| `api.livenessProbe` | `kaneo.livenessProbe` |-| `api.readinessProbe` | `kaneo.readinessProbe` |-| `web.*` | removed, web is bundled in the kaneo image |--### Example values migration--**Before (`values.yaml`):**-```yaml-api:- image:- repository: ghcr.io/usekaneo/api- tag: "2.5.0"- service:- type: ClusterIP- port: 1337- env:- clientUrl: "https://kaneo.example.com"- authSecret: "your-secret-here"--web:- image:- repository: ghcr.io/usekaneo/web- tag: "2.5.0"- service:- type: ClusterIP- port: 5173-```--**After (`values.yaml`):**-```yaml-kaneo:- image:- repository: ghcr.io/usekaneo/kaneo- tag: "2.6.0"- service:- type: ClusterIP- port: 5173- env:- clientUrl: "https://kaneo.example.com"- authSecret: "your-secret-here"-```+| `api.env.*` | Corresponding settings under `kaneo.env` |+| `api.livenessProbe` / `api.readinessProbe` | `kaneo.livenessProbe` / `kaneo.readinessProbe` |+| Separate API and web services | One `kaneo.service`, port 5173 |+| Ingress targets for API and web | Bundled Kaneo service on port 5173 |-### Upgrade command--```bash-helm upgrade kaneo kaneo/kaneo \- --version 0.3.0 \- --values your-values.yaml \- --namespace kaneo-```+Check the probes as well as their key names: current probes use `/api/health` and the named port `kaneo`. Keep your PostgreSQL PVC and existing credential secrets. The application image defaults to the chart’s `appVersion` when `kaneo.image.tag` is empty.-If you store values in a file, update the keys before running the upgrade. Helm will reject unknown keys and the deployment will fail if `api.*` or `web.*` keys remain.-------## Minimum working configuration--After upgrading, a minimal `.env` for Docker Compose requires three values:--```env-KANEO_CLIENT_URL=http://localhost:5173-POSTGRES_PASSWORD=changeme-AUTH_SECRET=replace_with_output_of_openssl_rand_hex_32-```+Render the chosen chart with your migrated values and inspect its services, ingress, secrets, and database configuration before applying it. Choose the target chart version deliberately; the chart and application versions are aligned for current releases.-Generate a stable secret with `openssl rand -hex 32` and keep it persistent, or active sessions will be invalidated after a container restart.+## Recovery-`POSTGRES_DB` and `POSTGRES_USER` default to `kaneo` if not set. `KANEO_API_URL` and `DATABASE_URL` are derived automatically.+If the new application never changed the database, restore the old application and proxy configuration. If it applied migrations, restore the matching database backup before returning to the old version. Follow the [restore procedure](/core/operations/backups) and keep the failed database available for investigation.diff --git a/apps/docs/core/installation/object-storage-and-image-uploads.mdx b/apps/docs/core/installation/object-storage-and-image-uploads.mdxindex c7bb720c6..b3c33a33b 100644--- a/apps/docs/core/installation/object-storage-and-image-uploads.mdx+++ b/apps/docs/core/installation/object-storage-and-image-uploads.mdx@@ -1,223 +1,61 @@----title: Object storage and uploads-description: Configure S3-compatible storage for private images and attachments in task descriptions and comments.+title: "Files and uploads"+description: "Choose where task images and attachments are stored."----## Overview+File storage is optional. Kaneo works without it, but people cannot upload files into task descriptions or comments until you configure an S3-compatible backend.-Kaneo supports private uploads in task descriptions and task comments.+Use [Silo](/core/installation/silo) to host storage yourself. If you already use a managed service, follow [AWS S3 or Cloudflare R2](/core/installation/storage-backends).-Uploads use an S3-compatible object storage backend:+## How an upload works-- the Kaneo API creates presigned upload URLs-- the browser uploads files directly to the storage backend-- Kaneo finalizes uploads into private asset records-- Kaneo serves uploaded files back through its own API--Upload URLs bind the declared byte length and content type. The browser supplies-`Content-Length` from the selected file automatically; custom clients must send-that exact length and the returned `Content-Type`. A streaming request without-`Content-Length`, a larger body, or a changed content type is rejected by storage.--Before creating an asset record, Kaneo retrieves object metadata with `HeadObject`-and checks existence, size and content type. Missing or mismatched objects are-not finalized. Oversized objects are removed. The storage credentials therefore-need read (`s3:GetObject`, also used by HEAD), write and delete access. Configure-storage CORS to allow your frontend origin and PUT with `Content-Type`.--After upgrading, check an upload through your actual browser, storage provider-and reverse proxy. The provider must enforce SigV4 signed `Content-Length` and-`Content-Type`; do not work around incompatibility by removing those signed-headers. Previously issued upload URLs retain their old constraints until their-configured expiry, so account for `S3_PRESIGN_TTL_SECONDS` during rollout.--This means Kaneo can work with multiple backends as long as they expose a compatible S3-style API.--Current behavior:--- images render inline-- other files such as CSV, PDF, or ZIP are inserted as attachment cards/links-- uploaded files are private by default and are not meant to be served from public bucket URLs--If you want backend-specific setup examples, see the [storage backends guide](/core/installation/storage-backends).--## Recommended local setup: MinIO--For local or self-hosted deployments, MinIO is the recommended storage backend.--It gives you:--- a stable S3-compatible API-- a web console for bucket management-- a simple Docker setup-- better compatibility for direct browser uploads--Example `.env` values:--```env-MINIO_ROOT_USER=kaneo-local-MINIO_ROOT_PASSWORD=<choose-a-local-development-password>--S3_ENDPOINT=http://minio:9000-S3_BUCKET=kaneo-uploads-S3_ACCESS_KEY_ID=kaneo-local-S3_SECRET_ACCESS_KEY=<choose-a-local-development-password>-S3_REGION=us-east-1-S3_FORCE_PATH_STYLE=true-```--Create the bucket before using uploads.--You do not need to make the bucket public.--## Important: internal Docker URLs are not enough in production--When Kaneo generates a presigned upload URL, the browser uploads directly to your storage backend.--That means `S3_ENDPOINT` must be reachable by the browser, not just by Docker containers.--For example:--- `http://minio:9000` works only inside Docker-- `https://files.example.com` works from the browser--If your Kaneo deployment is public, do not leave `S3_ENDPOINT` set to `http://minio:9000`.--Use a public MinIO hostname instead, for example:--```env-S3_ENDPOINT=https://files.cloud.kaneo.app-S3_BUCKET=kaneo-uploads-S3_ACCESS_KEY_ID=kaneo-S3_SECRET_ACCESS_KEY=<generate-a-strong-random-secret>-S3_REGION=us-east-1-S3_FORCE_PATH_STYLE=true+```mermaid+sequenceDiagram+ participant B as Browser+ participant K as Kaneo API+ participant S as S3 storage+ B->>K: Request an upload URL+ K-->>B: Signed URL with size and file type+ B->>S: Upload the file directly+ B->>K: Finish the upload+ K->>S: Check the stored file+ K-->>B: Private attachment```-<Warning>- Never expose MinIO with its default `minioadmin` root credentials. Create a- dedicated, bucket-scoped user and generate unique credentials for every- deployment.-</Warning>--## Recommended public setup--The simplest production setup is:--- `cloud.kaneo.app` for Kaneo-- `files.cloud.kaneo.app` for MinIO--Expose MinIO on its own public hostname through your reverse proxy.--Why this is needed:--- Kaneo signs uploads against `S3_ENDPOINT`-- the browser uses that signed URL directly-- Docker-internal names like `minio` are not resolvable from a user's browser--Using a dedicated subdomain is recommended over proxying MinIO under a path.--Reads do not need a public bucket URL, because Kaneo serves uploaded assets back through `/api/asset/:id`.--## Other S3-compatible backends--Kaneo is not tied to MinIO. Any deployment can point Kaneo at another S3-compatible backend by changing the `S3_*` environment variables.--Examples:--- AWS S3-- Cloudflare R2-- MinIO-- [`fs`](https://github.com/ferdzo/fs)+The browser and the Kaneo API must both reach `S3_ENDPOINT`. Use a hostname such as `https://files.example.com`. An internal Docker name such as `http://silo:9000` will not work in a normal browser, even if the containers can reach one another.-## Using `fs`+The storage bucket stays private. Kaneo checks access and serves files through its own API. Images appear inline; PDFs, ZIPs, and other files appear as attachments.-`fs` is another S3-compatible option if you want a lightweight local object store. It is built by friends of Kaneo.--When using `fs`, configure Kaneo like this:+## Required configuration```env-S3_ENDPOINT=http://fs:2600+S3_ENDPOINT=https://files.example.comS3_BUCKET=kaneo-uploads-S3_ACCESS_KEY_ID=<your-access-key>-S3_SECRET_ACCESS_KEY=<your-secret-key>+S3_ACCESS_KEY_ID=your-bucket-access-key+S3_SECRET_ACCESS_KEY=your-bucket-secret-keyS3_REGION=us-east-1S3_FORCE_PATH_STYLE=true```-Important notes for `fs`:--- buckets are created through the S3 API or CLI, not through a web dashboard-- Kaneo still expects the bucket to exist before uploads start-- direct browser uploads may need reverse-proxy CORS headers, because `fs` does not currently implement S3 CORS APIs--## Required Kaneo storage variables--Set these in your Kaneo deployment:--| Name | Description |-| --- | --- |-| `S3_ENDPOINT` | S3-compatible API endpoint used by Kaneo |-| `S3_BUCKET` | Bucket used for uploaded files |-| `S3_ACCESS_KEY_ID` | Access key used to create presigned upload URLs. Optional when using an IAM role (see below) |-| `S3_SECRET_ACCESS_KEY` | Secret key used to create presigned upload URLs. Optional when using an IAM role (see below) |-| `S3_REGION` | Region used for signing |-| `S3_FORCE_PATH_STYLE` | Usually `true` for MinIO and `fs` |--Optional:--| Name | Description |-| --- | --- |-| `S3_PUBLIC_BASE_URL` | Optional public asset base URL. Kaneo does not require this for the current private asset flow. |-| `S3_MAX_IMAGE_UPLOAD_BYTES` | Maximum allowed upload size in bytes for images and other uploaded files |-| `S3_PRESIGN_TTL_SECONDS` | Presigned upload URL lifetime |--## Using an IAM role (AWS S3) instead of static keys+Use a dedicated credential with read, write, and delete access to this bucket. Kaneo uses `GetObject`, including HEAD requests, to check uploads and read files. It also needs `PutObject` and `DeleteObject`.-When Kaneo runs on AWS (EC2, ECS, or EKS), you can let it authenticate with an-IAM role instead of long-lived access keys.+On AWS you can [use an IAM role](/core/installation/storage-backends#aws-s3) instead of static keys. Set both key variables or leave both unset.-Leave both `S3_ACCESS_KEY_ID` and `S3_SECRET_ACCESS_KEY` unset. Kaneo then falls-back to the AWS SDK's default credential provider chain, which automatically-picks up credentials from:--- an EC2 instance profile-- an ECS task role-- an EKS service account / IRSA (`AWS_WEB_IDENTITY_TOKEN_FILE`)-- standard `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` environment variables-- a shared `~/.aws/credentials` profile--Example for AWS S3 with an attached IAM role:--```env-S3_ENDPOINT=https://s3.us-east-1.amazonaws.com-S3_BUCKET=kaneo-uploads-S3_REGION=us-east-1-S3_FORCE_PATH_STYLE=false-# S3_ACCESS_KEY_ID and S3_SECRET_ACCESS_KEY intentionally omitted-```+## Limits and browser access-The IAM role must allow `s3:PutObject`, `s3:GetObject`, and `s3:DeleteObject`-on the bucket.+The default upload limit is 10 MiB. Change `S3_MAX_IMAGE_UPLOAD_BYTES` to set another limit in bytes; despite its name, it also covers non-image attachments. Signed upload URLs expire after 300 seconds by default, controlled by `S3_PRESIGN_TTL_SECONDS`.-<Warning>- Set both keys or neither. Configuring only one of `S3_ACCESS_KEY_ID` /- `S3_SECRET_ACCESS_KEY` is treated as a misconfiguration and Kaneo will refuse- to start the storage client.-</Warning>+Configure storage CORS to allow your exact Kaneo origin and `PUT` requests with `Content-Type`. Both the storage endpoint and Kaneo should use HTTPS for a public deployment.-## Testing uploads+Custom upload clients must send the exact declared `Content-Length` and the returned `Content-Type`. Kaneo checks the stored object before finalizing it. Do not remove signed-header checks to work around an incompatible provider.-Once storage is configured:+## Check it works-1. Open a task.-2. Paste, drag, or select a file inside the description or a comment.-3. Confirm images render inline and other files render as attachment cards/links.+1. Open a task and attach a small image to its description.+2. Confirm the image appears, then reload the page.+3. Add a PDF or text file to a comment and open the attachment.+4. Check that a person without access cannot retrieve the private file.-If uploads fail:+Repeat this check after storage or proxy upgrades. If it fails, use [upload troubleshooting](/core/operations/troubleshooting#uploads-fail).-- confirm the bucket exists-- confirm the credentials can write to the bucket-- confirm the storage endpoint is reachable from the browser-- confirm `S3_ENDPOINT` is a public URL, not an internal Docker hostname-- if using direct browser uploads, confirm CORS is configured correctly for your storage endpoint+Back up the [database and the files together](/core/operations/backups). A database backup contains attachment records, not their file contents.diff --git a/apps/docs/core/installation/silo.mdx b/apps/docs/core/installation/silo.mdxnew file mode 100644index 000000000..d11a8f96d--- /dev/null+++ b/apps/docs/core/installation/silo.mdx@@ -0,0 +1,151 @@+---+title: "Store files with Silo"+description: "Add private S3-compatible storage to your Kaneo deployment."+---++[PGSTY Silo](https://silo.pgsty.com/) is a maintained MinIO fork with an S3 API and a web console. This guide uses it for a single-server Kaneo installation.++You need a running Kaneo instance, a hostname such as `files.example.com`, and an HTTPS reverse proxy on the Docker host. The API and every user's browser must be able to reach that hostname.++## 1. Add the storage service++Add this service and volume to your existing `compose.yml`. Merge them into the existing `services` and `volumes` sections; do not create duplicate top-level keys.++```yaml+services:+ silo:+ image: docker.io/pgsty/silo:RELEASE.2026-09-16T00-00-00Z+ command: server /data --console-address ":9001"+ env_file:+ - silo.env+ ports:+ - "127.0.0.1:9000:9000"+ - "127.0.0.1:9001:9001"+ volumes:+ - silo_data:/data+ restart: unless-stopped+ healthcheck:+ test: ["CMD", "silo", "healthcheck", "ready"]+ interval: 30s+ timeout: 5s+ retries: 3++volumes:+ silo_data:+```++The image and health check follow [Silo's container installation guide](https://silo.pgsty.com/download/). Keep the release pinned and review its release notes before changing it.++Create `silo.env` with a unique administrator name and a secret generated with `openssl rand -hex 32`:++```env+MINIO_ROOT_USER=silo-admin+MINIO_ROOT_PASSWORD=replace-with-a-generated-secret+MINIO_API_CORS_ALLOW_ORIGIN=https://kaneo.example.com+```++Silo retains the `MINIO_*` configuration names. Use the exact origin of your Kaneo instance, including its port if it has one. This global CORS setting applies to buckets without their own CORS configuration. See [Silo's compatibility notes](https://silo.pgsty.com/compatibility/migration/).++```bash+chmod 600 silo.env+docker compose up -d silo+docker compose ps silo+```++## 2. Put the S3 API behind HTTPS++Point `files.example.com` at your server. Configure your proxy to send that hostname to `http://127.0.0.1:9000`, preserving the request host, path, query string, and body.++For host-installed Nginx with an existing certificate, use:++```nginx+server {+ listen 443 ssl;+ server_name files.example.com;+ ssl_certificate /etc/letsencrypt/live/files.example.com/fullchain.pem;+ ssl_certificate_key /etc/letsencrypt/live/files.example.com/privkey.pem;+ client_max_body_size 10m;++ location / {+ proxy_pass http://127.0.0.1:9000;+ proxy_http_version 1.1;+ proxy_set_header Host $http_host;+ proxy_set_header X-Forwarded-Proto $scheme;+ proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;+ proxy_request_buffering off;+ }+}+```++Adjust the body limit if you increase Kaneo's upload limit. Use a dedicated hostname rather than adding a path prefix to the storage URL. Test with `sudo nginx -t` before reloading Nginx.++Keep port 9001, the administration console, private. On a remote server, open an SSH tunnel from your computer:++```bash+ssh -L 9001:127.0.0.1:9001 your-user@your-server+```++Then visit `http://localhost:9001` and sign in with the administrator credentials from `silo.env`.++## 3. Create the bucket and a Kaneo credential++In the Silo console:++1. Create a private bucket named **kaneo-uploads**.+2. Create a policy named **kaneo-uploads** with the JSON below.+3. Create a dedicated user for Kaneo and attach that policy. Use that user's access key and secret in Kaneo, not the root administrator credential.++```json+{+ "Version": "2012-10-17",+ "Statement": [+ {+ "Effect": "Allow",+ "Action": ["s3:GetBucketLocation", "s3:ListBucket"],+ "Resource": ["arn:aws:s3:::kaneo-uploads"]+ },+ {+ "Effect": "Allow",+ "Action": ["s3:GetObject", "s3:PutObject", "s3:DeleteObject"],+ "Resource": ["arn:aws:s3:::kaneo-uploads/*"]+ }+ ]+}+```++Leave anonymous bucket access disabled. The console's [identity and access guide](https://silo.pgsty.com/administration/identity-access-management/) covers storage-side administration.++## 4. Connect Kaneo++Add these values to Kaneo's `.env`:++```env+S3_ENDPOINT=https://files.example.com+S3_BUCKET=kaneo-uploads+S3_ACCESS_KEY_ID=your-dedicated-user-access-key+S3_SECRET_ACCESS_KEY=your-dedicated-user-secret+S3_REGION=us-east-1+S3_FORCE_PATH_STYLE=true+```++Apply them:++```bash+docker compose up -d --force-recreate kaneo+```++Open a task, upload an image, reload, and open the image again. Try a non-image attachment too. If it fails, check [uploads troubleshooting](/core/operations/troubleshooting#uploads-fail).++## Moving from MinIO++Back up the existing storage and configuration first. Follow [Silo's migration guide](https://silo.pgsty.com/compatibility/migration/) for your exact source and target versions.++Keep existing volume names, mounts, bucket names, and object keys. Do not rename a live `minio_data` volume to `silo_data` just to match this example, as Compose would create a different volume. Existing `MINIO_*` variables keep their spelling.++Test uploads and downloads before switching your team over. Image rollback alone may not reverse changes to persistent storage metadata or permissions.++## Local-only trials++A local setup still needs one storage hostname that both Docker and the browser can resolve. `localhost` inside the Kaneo container points to Kaneo, while `silo` usually resolves only inside Docker. Configure shared DNS and routing for your environment instead of copying either address into `S3_ENDPOINT`.++For the least setup, try Kaneo without attachments first and add storage on a host with a reachable domain.diff --git a/apps/docs/core/installation/start-services.mdx b/apps/docs/core/installation/start-services.mdxindex a0b031a07..43b795615 100644--- a/apps/docs/core/installation/start-services.mdx+++ b/apps/docs/core/installation/start-services.mdx@@ -1,21 +1,20 @@----title: Start the services-description: Start the services to start using Kaneo+title: "Start and check Kaneo"+description: "Start the containers and confirm the instance is ready."----## Start the services+If you are installing for the first time, use the complete [Docker Compose guide](/core/installation/docker-compose). It includes the configuration, secrets, startup, and first sign-in.-Congratulations! You have now set up the services to start using Kaneo.--To start the services, you can use the following command:+From the directory containing your Compose file:```bashdocker compose up -d+docker compose ps+curl --fail http://localhost:5173/api/health```-You can now access the web application at [http://localhost:5173](http://localhost:5173).+If a service is unhealthy, run `docker compose logs --tail=100 kaneo postgres` and follow [Troubleshooting](/core/operations/troubleshooting).-The next logical step would be to set up a reverse proxy to access the web application from the internet.+After changing `.env`, run `docker compose up -d --force-recreate kaneo` so the container receives the new values.-- Nginx-- Traefik+For a public instance, continue with [Nginx and HTTPS](/core/reverse-proxy/nginx).diff --git a/apps/docs/core/installation/storage-backends.mdx b/apps/docs/core/installation/storage-backends.mdxindex b5374e206..5463a707d 100644--- a/apps/docs/core/installation/storage-backends.mdx+++ b/apps/docs/core/installation/storage-backends.mdx@@ -1,107 +1,15 @@----title: Storage backends-description: Configure private uploads with MinIO, AWS S3, or Cloudflare R2.+title: "AWS S3 and other providers"+description: "Connect Kaneo to a managed S3-compatible bucket."----## Overview+For self-hosted storage, follow the [Silo guide](/core/installation/silo). This page covers managed providers and the requirements for another S3-compatible service.-Kaneo uses S3-compatible object storage for uploads in:--- task descriptions-- task comments--The browser uploads directly to the configured storage backend using presigned URLs.--Kaneo then serves uploaded assets back through its own API.--Current behavior:--- images render inline-- non-image files such as CSV, PDF, and ZIP render as attachment cards/links-- assets are private by default--That means one rule matters for every backend:--- `S3_ENDPOINT` must be reachable by the browser--Do not use a Docker-internal hostname such as `http://minio:9000` for a public deployment unless the browser can actually reach it.--## Required Kaneo variables--```env-S3_ENDPOINT=-S3_BUCKET=-S3_ACCESS_KEY_ID=-S3_SECRET_ACCESS_KEY=-S3_REGION=us-east-1-S3_FORCE_PATH_STYLE=false-```--Notes:--- `S3_FORCE_PATH_STYLE=true` is usually needed for MinIO.-- `S3_FORCE_PATH_STYLE=false` is usually correct for AWS S3 and R2.-- `S3_PUBLIC_BASE_URL` is optional and not required for the current private asset flow.--## MinIO--MinIO is the recommended self-hosted option.--### Local Docker setup--For local development, this is fine:--```env-MINIO_ROOT_USER=kaneo-local-MINIO_ROOT_PASSWORD=<choose-a-local-development-password>--S3_ENDPOINT=http://minio:9000-S3_BUCKET=kaneo-uploads-S3_ACCESS_KEY_ID=kaneo-local-S3_SECRET_ACCESS_KEY=<choose-a-local-development-password>-S3_REGION=us-east-1-S3_FORCE_PATH_STYLE=true-```--This works when Kaneo and MinIO are on the same Docker network and your browser reaches MinIO through `localhost`.--### Public deployment--For a public deployment, expose MinIO on its own hostname through your reverse proxy.--Example:--- Kaneo: `https://cloud.kaneo.app`-- MinIO: `https://files.cloud.kaneo.app`--This can be done with Caddy, Nginx, Traefik, or any other reverse proxy.--Then use:--```env-S3_ENDPOINT=https://files.cloud.kaneo.app-S3_BUCKET=kaneo-uploads-S3_ACCESS_KEY_ID=kaneo-S3_SECRET_ACCESS_KEY=<generate-a-strong-random-secret>-S3_REGION=us-east-1-S3_FORCE_PATH_STYLE=true-```--You also need:--- a created bucket-- a dedicated, non-root MinIO user with access limited to that bucket-- MinIO CORS allowing your Kaneo origin-- no anonymous bucket read policy is required--<Warning>- Never expose MinIO with its default `minioadmin` root credentials. Generate- unique credentials for every deployment and keep the MinIO Console private.-</Warning>+Start with a private bucket. Both the browser and the API must reach the endpoint, and storage CORS must allow your Kaneo origin. Read [Files and uploads](/core/installation/object-storage-and-image-uploads) for the full upload flow.## AWS S3-AWS S3 is the simplest managed option.+Use an existing AWS S3 bucket or create a private bucket for Kaneo.Use a bucket and an IAM user with access to that bucket.@@ -116,9 +24,7 @@ S3_REGION=us-east-1S3_FORCE_PATH_STYLE=false```-For another AWS region, adjust:--- `S3_ENDPOINT`+For another AWS region, change both `S3_ENDPOINT` and `S3_REGION`.### Using an IAM role instead of an access key@@ -145,12 +51,14 @@ Recommended S3 CORS policy:{"AllowedHeaders": ["*"],"AllowedMethods": ["GET", "PUT", "HEAD"],- "AllowedOrigins": ["https://cloud.kaneo.app"],+ "AllowedOrigins": ["https://kaneo.example.com"],"ExposeHeaders": ["ETag"]}]```+Apply the CORS policy above in the S3 bucket settings, replacing the origin with your public Kaneo URL.+## Cloudflare R2R2 works well because it exposes an S3-compatible API.@@ -172,85 +80,13 @@ Notes:- `S3_REGION=auto` is typical for R2- a public bucket is not required for Kaneo's current private asset flow+- configure the bucket's CORS policy for your Kaneo origin, including PUT and Content-Type; the JSON above shows the required shape-## One copy-paste self-hosted example--This example gives you Kaneo + MinIO in one Compose file.--```yml-services:- postgres:- image: postgres:16-alpine- env_file:- - .env- volumes:- - postgres_data:/var/lib/postgresql/data- restart: unless-stopped- healthcheck:- test: ["CMD-SHELL", "pg_isready -U kaneo -d kaneo"]- interval: 10s- timeout: 5s- retries: 5-- api:- image: ghcr.io/usekaneo/api:latest- env_file:- - .env- depends_on:- postgres:- condition: service_healthy- restart: unless-stopped-- web:- image: ghcr.io/usekaneo/web:latest- env_file:- - .env- depends_on:- - api- restart: unless-stopped-- minio:- image: minio/minio:latest- command: server /data --console-address ":9001"- env_file:- - .env- volumes:- - minio_data:/data- restart: unless-stopped--volumes:- postgres_data:- minio_data:-```--Matching `.env`:--```env-KANEO_CLIENT_URL=https://cloud.kaneo.app-KANEO_API_URL=https://cloud.kaneo.app/api--MINIO_ROOT_USER=<generate-a-unique-admin-user>-MINIO_ROOT_PASSWORD=<generate-a-strong-random-secret>--S3_ENDPOINT=https://files.cloud.kaneo.app-S3_BUCKET=kaneo-uploads-S3_ACCESS_KEY_ID=<generate-a-unique-admin-user>-S3_SECRET_ACCESS_KEY=<generate-a-strong-random-secret>-S3_REGION=us-east-1-S3_FORCE_PATH_STYLE=true-```--Before testing uploads:-1. Create the `kaneo-uploads` bucket.-2. Configure MinIO CORS for your Kaneo origin.-3. Make sure `files.cloud.kaneo.app` resolves publicly.+## Other S3-compatible services-## Troubleshooting+Use the provider's S3 API endpoint, region, and bucket-scoped credentials. Check whether it requires path-style URLs. Leave `S3_PUBLIC_BASE_URL` unset for Kaneo's private attachment flow.-If uploads fail:+The service must support presigned PUT requests with signed `Content-Length` and `Content-Type`, object metadata checks, reads, and deletes. An S3-compatible label alone does not prove this upload path works; test a browser upload, reload, and download before using it for team files.-- check that the bucket exists-- check that `S3_ENDPOINT` is public and browser-reachable-- check CORS on your storage backend-- check that the access key can `PutObject` and `GetObject`+Apply changes with `docker compose up -d --force-recreate kaneo`. See [Troubleshooting](/core/operations/troubleshooting#uploads-fail) if uploads fail.diff --git a/apps/docs/core/integrations/gitea/setup.mdx b/apps/docs/core/integrations/gitea/setup.mdxindex 09182a734..7ef148f39 100644--- a/apps/docs/core/integrations/gitea/setup.mdx+++ b/apps/docs/core/integrations/gitea/setup.mdx@@ -1,60 +1,63 @@----title: Gitea Setup-description: Connect Kaneo to a Gitea instance (issues, pull requests, webhooks).+title: Connect Gitea+description: Verify repository access, configure webhooks, and import existing issues.----## Overview+Connect a Kaneo project to one Gitea repository to sync issues and respond to branch and pull-request activity. You need permission to manage the Kaneo project, a Gitea token that can read the account and repository and write issues, and repository admin access to create its webhook.-The Gitea integration links a Kaneo project to a repository on your Gitea instance. Tasks sync with issues, and webhooks keep Kaneo updated when issues, pull requests, or pushes change.+## Connect the repository-You need:+1. Create a personal access token in Gitea under **Settings → Applications**. Give it the scopes needed to read your user and repository and write issues. The token’s account must also have write access to the target repository.+2. In Kaneo, open **Settings → Projects**, select your project, and open **Integrations → Gitea**.+3. Enter the Gitea base URL, such as `https://git.example.com`. Use the final URL directly, without `/api/v1`, credentials, a query string, or a fragment.+4. Enter the access token and repository owner and name. You can also browse repositories from the form.+5. Choose **Verify access** and resolve any reported problem, then save the connection.-- **Gitea base URL**: e.g. `https://git.example.com`.-- **Personal access token** with permission to read/write issues and repository contents for the target repo.-- **Repository owner and name**: same as in the Gitea UI.+The API must be able to reach your Gitea server. Verification checks the token and repository permissions; it does not prove that webhooks can reach Kaneo in the other direction.-## Personal access token+## Configure the webhook-1. In Gitea, open **Settings → Applications → Generate New Token** (paths may vary slightly by version).-2. Enable scopes for **repository** and **issues** (write access where needed).-3. Copy the token and store it securely; paste it into Kaneo’s Gitea integration settings.+After saving, Kaneo shows a webhook URL and secret. Copy both into a repository webhook in Gitea under **Settings → Webhooks → Add Webhook → Gitea**.-## Webhook in Gitea+| Gitea setting | Value |+| --- | --- |+| Target URL | The webhook URL shown in Kaneo |+| HTTP method | POST |+| Content type | `application/json` |+| Secret | The exact secret shown in Kaneo |+| Active | Enabled |-Kaneo verifies incoming webhooks with a **HMAC SHA256** secret stored per integration.+Select push, pull request, issue, and issue comment events. Include issue label events if your Gitea version exposes that selection. Kaneo handles `issue_label`; the Git branch/tag **Create** event is not a label event.-### Where to create the webhook in Gitea+The URL has this shape:-1. Log in to Gitea and **open the same repository** you linked in Kaneo (`owner/repo`).-2. Open the repository **Settings**.-3. In the **left sidebar**, open **Webhooks** (sometimes grouped under a “Repository” section).- - If you do not see it, you need **admin** access to that repository (owner or collaborator with admin).-4. Click **Add Webhook** and choose **Gitea**.+```text+https://kaneo.example.com/api/gitea-integration/webhook/INTEGRATION_ID+```-**Direct URL pattern** (replace host, owner, and repo):+Use Gitea’s test delivery, then create a test issue and confirm it appears in Kaneo. A successful test response proves the request arrived; checking the resulting task proves issue sync works. See [Gitea’s webhook documentation](https://docs.gitea.com/usage/repository/webhooks/) for its settings and delivery log.-`https://<your-gitea-host>/<owner>/<repo>/settings/hooks`+## Import existing issues-Example: `https://git.example.com/acme/my-app/settings/hooks`+Save the repository connection, verify its current settings, then choose **Import Issues**. Verification is cleared when you reload the page or change connection details. If import is disabled, verify again. When replacing the token, save it before importing because the importer uses the saved connection.-### Configure the webhook+## Configure automation-1. Connect the repository in Kaneo **Project → Integrations → Gitea** and save.-2. Copy the **Webhook URL** and **Secret** shown in Kaneo (after saving).-3. In Gitea: **Add Webhook → Gitea**.-4. Set **Payload URL** to the Kaneo webhook URL.-5. Set **Secret** to the exact value from Kaneo.-6. Enable **Content type**: `application/json`.-7. Enable events:+Choose your branch naming pattern in the integration settings. In the project’s [Workflow settings](/core/functional/configure-workflows), map branch pushes, opened pull requests, and merged pull requests to the intended columns. Try one task first and check its status before adopting the pattern across your team.- - **Push**- - **Pull requests**- - **Issues** (open, close, label, edit, etc.)- - **Issue comments**- - **Create** (used for label creation events on some Gitea versions)+## Replace a token or disconnect-8. Save and use **Test Delivery** to confirm a `200` response from Kaneo.+To rotate credentials, enter a replacement token, verify access, and save. On an existing connection, an empty token field keeps the saved token; it does not clear it.-The webhook URL includes your integration id, for example:+Choose **Disconnect** to remove the Kaneo connection. This does not delete the Gitea repository or Kaneo tasks. Remove the webhook in Gitea as well, and revoke its token if nothing else uses it.-`https://your-kaneo-host/api/gitea-integration/webhook/<integrationId>`+## Troubleshooting++| Problem | What to check |+| --- | --- |+| URL redirects or returns HTML | Use Gitea’s final base URL and make sure an authentication proxy is not intercepting API requests. |+| Repository not found | Check owner, name, and token access to private repositories. |+| Verification succeeds, writes fail | Check token scopes as well as the account’s repository permissions. |+| Invalid webhook signature | Copy the current secret from Kaneo and save it in Gitea. |+| No tasks arrive | Check recent Gitea deliveries, selected events, repository identity, and the active connection. |+| Task does not move after a push | Check the branch naming pattern and workflow mapping. |diff --git a/apps/docs/core/integrations/github/configuration.mdx b/apps/docs/core/integrations/github/configuration.mdxindex 8ba8bb208..a525e2e1d 100644--- a/apps/docs/core/integrations/github/configuration.mdx+++ b/apps/docs/core/integrations/github/configuration.mdx@@ -1,176 +1,39 @@----title: Configuration & Setup-description: Configure Kaneo with your GitHub App credentials and connect projects to repositories. Includes Docker Compose and Kubernetes examples.+title: "Connect a GitHub repository"+description: "Add the app credentials, connect a project, and verify synchronization."---+First [create and install a GitHub App](/core/integrations/github/setup). GitHub sign-in is separate and uses [OAuth settings](/core/social-providers/github).-This guide covers configuring Kaneo with your GitHub App credentials and connecting projects to repositories.+## Add the instance credentials-<Info>-Make sure you've completed the [GitHub App setup](/core/integrations/github/setup) before proceeding.-</Info>--## Environment Variables+For the bundled Compose deployment, add these values to `.env`:-Add the following environment variables to your Kaneo deployment:--```bash-# GitHub App (integration only: repository sync, webhooks)-GITHUB_APP_ID=123456-GITHUB_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY------MIIEpAIBAAKCAQEA...-[Full contents of your private key]-...------END RSA PRIVATE KEY-----"-GITHUB_WEBHOOK_SECRET=your-webhook-secret-here--# Optional: GitHub App slug for installation URLs in the UI-GITHUB_APP_NAME=kaneo-your-instance-name+```env+GITHUB_APP_ID=your-app-id+GITHUB_APP_NAME=your-app-slug+GITHUB_WEBHOOK_SECRET=your-webhook-secret+GITHUB_PRIVATE_KEY_BASE64=your-base64-encoded-private-key```-<Info>-GitHub sign-in uses separate OAuth variables (`GITHUB_OAUTH_CLIENT_ID` / `GITHUB_OAUTH_CLIENT_SECRET`). You can run the integration without enabling GitHub SSO. See [GitHub SSO](/core/social-providers/github) and [Environment variables](/core/installation/environment-variables#github-sso).-</Info>--### Variable Reference+Encode the downloaded PEM file without printing it into logs or committing it. Alternatively, set `GITHUB_PRIVATE_KEY` to the full PEM with real line breaks or literal `\n` sequences. `GITHUB_PRIVATE_KEY_BASE64` takes precedence if both are present.-| Variable | Description | Required | Example |-|----------|-------------|----------|---------|-| `GITHUB_APP_ID` | Your GitHub App's ID | ✅ | `123456` |-| `GITHUB_PRIVATE_KEY` | Full private key content (with newlines) | ✅ | `-----BEGIN RSA...` |-| `GITHUB_WEBHOOK_SECRET` | Secret for webhook verification | ✅ | `your-secret` |-| `GITHUB_APP_NAME` | App slug for installation URLs in the UI | ⚠️ | `kaneo-mycompany` |--<Warning>-`GITHUB_APP_NAME` is optional but recommended. It's used to generate direct installation links in the UI.-</Warning>--## Deployment Examples--### Docker Compose--Update your `compose.yml` file:--```yaml-services:- backend:- image: ghcr.io/usekaneo/api:latest- environment:- # ... other environment variables- GITHUB_APP_ID: "123456"- GITHUB_PRIVATE_KEY: |- -----BEGIN RSA PRIVATE KEY------ MIIEpAIBAAKCAQEA...- [Full contents of your private key]- ...- -----END RSA PRIVATE KEY------ GITHUB_WEBHOOK_SECRET: "your-webhook-secret-here"- GITHUB_APP_NAME: "kaneo-mycompany"- # ... rest of configuration-```--<Tip>-Use the `|` YAML syntax for multi-line environment variables like the private key.-</Tip>--### Kubernetes--Create a secret for your GitHub credentials:--```yaml-apiVersion: v1-kind: Secret-metadata:- name: github-integration- namespace: kaneo-type: Opaque-stringData:- GITHUB_APP_ID: "123456"- GITHUB_PRIVATE_KEY: |- -----BEGIN RSA PRIVATE KEY------ MIIEpAIBAAKCAQEA...- [Full contents of your private key]- ...- -----END RSA PRIVATE KEY------ GITHUB_WEBHOOK_SECRET: "your-webhook-secret-here"- GITHUB_APP_NAME: "kaneo-mycompany"-```--Then reference it in your deployment:--```yaml-apiVersion: apps/v1-kind: Deployment-metadata:- name: kaneo-backend-spec:- template:- spec:- containers:- - name: backend- image: ghcr.io/usekaneo/api:latest- envFrom:- - secretRef:- name: github-integration-```--### Environment File--For development or simple deployments, create a `.env` file:+Recreate the application container to apply the environment:```bash-# .env file-GITHUB_APP_ID=123456-GITHUB_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY------MIIEpAIBAAKCAQEA...-[Full contents of your private key]-...------END RSA PRIVATE KEY-----"-GITHUB_WEBHOOK_SECRET=your-webhook-secret-here-GITHUB_APP_NAME=kaneo-mycompany+docker compose up -d --force-recreate kaneo```-## Connecting Repositories--Once your environment variables are configured and your backend is restarted, you can connect projects to GitHub repositories.--<Steps>-<Step>-**Navigate to Project Settings**--1. Open your Kaneo project-2. Go to **Project Settings**-3. Find the **GitHub Integration** section-</Step>--<Step>-**Connect Repository**+For Kubernetes, pass the same values through a Secret using your deployment's existing secret configuration. Do not create a second API deployment just for this integration.-You have two options to connect a repository:+## Connect the project-**Option A: Browse Repositories**-1. Click "Browse Repositories"-2. Select from repositories where your GitHub App is installed-3. Click on the desired repository+1. Open **Settings → Projects**, select the project, then open **Integrations**.+2. In GitHub, browse the repositories available to your installed app, or enter the owner and repository name.+3. Verify the installation and connect the repository.+4. Create a test task and check that its GitHub issue appears.-**Option B: Manual Entry**-1. Enter the **Repository Owner** (username or organization)-2. Enter the **Repository Name**-3. Click "Verify Installation"-</Step>--<Step>-**Verify and Connect**--1. Kaneo will verify that your GitHub App has access-2. If successful, click "Connect Repository"-3. You should see a green "Connected" status--<Check>-Once connected, new tasks created in this project will automatically generate GitHub issues!-</Check>-</Step>-</Steps>+Use a test repository for the first check, since synchronization creates real issues and comments. Review the event-to-column mappings under **Workflow → Automation Rules**.### Changing the connected repositorydiff --git a/apps/docs/core/integrations/github/setup.mdx b/apps/docs/core/integrations/github/setup.mdxindex aac805282..81abdd42d 100644--- a/apps/docs/core/integrations/github/setup.mdx+++ b/apps/docs/core/integrations/github/setup.mdx@@ -1,231 +1,56 @@----title: App Setup-description: Learn how to create and configure a GitHub App for Kaneo integration. Step-by-step guide to register your Kaneo instance with GitHub.+title: Create a GitHub App+description: Give a self-hosted Kaneo instance access to the repositories you want to sync.---+A self-hosted Kaneo instance uses a GitHub App for repository sync. Create the app once, install it on the repositories you need, then [connect each Kaneo project](/core/integrations/github/configuration).-This guide walks you through creating and configuring a GitHub App to enable the Kaneo integration. **Start here before deploying or configuring your Kaneo instance.**+GitHub sign-in is a separate feature. Use the [GitHub sign-in guide](/core/social-providers/github) for that setup.-## Overview+## 1. Register the app-A GitHub App provides secure, granular access to your repositories and enables powerful bidirectional synchronization between Kaneo and GitHub:+Open [GitHub Developer Settings](https://github.com/settings/apps) and choose **New GitHub App**.-**Task to GitHub:**-- Automatically create GitHub issues when you create tasks-- Update issue status and priority labels when you change tasks-- Add comments linking to Kaneo tasks-- Close/reopen issues based on task status changes+| Setting | Value |+| --- | --- |+| App name | A unique name, such as `kaneo-your-team` |+| Homepage URL | Your public Kaneo URL |+| Webhook URL | `https://kaneo.example.com/api/github-integration/webhook` |+| Webhook secret | A random secret you will also configure in Kaneo |-**GitHub to Kaneo:**-- Create tasks from GitHub issues-- Sync issue labels (priority, status) to task properties-- Link pull requests to tasks automatically-- Update task status based on branch activity (push, PR open/merge)-- Sync GitHub labels to Kaneo task labels+Keep webhooks active. GitHub must be able to reach the endpoint without signing in to your reverse proxy. Use your actual public API origin if you host it separately.-**Automatic Status Transitions:**-- Branch push → Move task to "in-progress"-- PR opened → Move task to "in-review"-- PR merged → Move task to "done"+## 2. Set permissions and events-<Info>-GitHub Apps are more secure than personal access tokens and provide fine-grained permission control.-</Info>+Use these repository permissions:-<Warning>-**Important**: Complete this GitHub App setup **before** deploying Kaneo. You'll need the app credentials during deployment configuration.-</Warning>+| Permission | Access | Used for |+| --- | --- | --- |+| Issues | Read and write | Issue creation, edits, comments, labels, and open/closed state |+| Pull requests | Read | Pull-request links and status changes |+| Contents | Read | Branch and push activity |+| Metadata | Read | Repository discovery and installation checks |-## Step 1: Create a GitHub App+Subscribe to **Issues**, **Issue comments**, **Pull requests**, and **Push**. If you later change the app’s permissions, approve the updated permissions on its installation too.-<Steps>-<Step>-**Navigate to GitHub App Settings**+Create the app. GitHub’s [app registration guide](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/registering-a-github-app) explains the remaining platform settings.-Go to [GitHub Developer Settings](https://github.com/settings/developers) and click "New GitHub App".-</Step>+## 3. Save the credentials-<Step>-**Configure Basic Information**+On the app’s settings page, record its **App ID** and app slug. Generate and download a private key from **Private keys**. Keep the webhook secret you chose earlier.-Fill in the basic app information:+Kaneo’s repository integration needs the App ID, private key, and webhook secret. It does not use the app’s OAuth Client ID or Client Secret for repository access.-- **GitHub App name**: `kaneo-[your-instance-name]` (must be unique across GitHub)-- **Description**: `Kaneo project management integration`-- **Homepage URL**: Your planned Kaneo instance URL (e.g., `https://kaneo.yourdomain.com`)-- **Webhook URL**: `https://your-kaneo-instance.com/api/github-integration/webhook`-- **Webhook secret**: Generate a secure random string (save this for later)+## 4. Install on your repositories-<Warning>-Replace `your-kaneo-instance.com` with your planned Kaneo domain. The webhook URL must be publicly accessible once deployed.-</Warning>-</Step>+Choose **Install App**, select your GitHub account or organization, and select the repositories to connect. You can change that selection later under [GitHub App installations](https://github.com/settings/installations).-<Step>-**Set Repository Permissions**+An organization may require an owner to approve the installation or permission changes. Finish that approval before verifying access in Kaneo.-Configure the following permissions:+## 5. Connect Kaneo-| Permission | Access | Purpose |-|------------|---------|---------|-| **Issues** | Read & Write | Create issues, add/remove labels, create comments, close/reopen issues |-| **Pull Requests** | Read | Link pull requests to tasks and track PR status |-| **Metadata** | Read | Access repository information and verify installation |-| **Contents** | Read | Track branch pushes and associate commits with tasks |+Follow [Connect a GitHub repository](/core/integrations/github/configuration) to add the instance credentials, connect a project, and import issues.-<Warning>-**Critical**: Make sure to grant **Write** access to Issues - this is required for the integration to work properly.-</Warning>+Tasks and issues can sync in both directions. Branch and pull-request activity can move tasks according to your [workflow mappings](/core/functional/configure-workflows); check those mappings against your project’s actual columns.-<Info>-Pull Requests permission is optional but recommended for full integration features. Without it, you won't be able to automatically link PRs to tasks or track PR status changes.-</Info>-</Step>--<Step>-**Subscribe to Webhook Events**--**This step is required for proper integration.** Subscribe to these events:--- **Issues** - To sync issues with tasks (opened, edited, closed, labeled, unlabeled)-- **Issue comments** - To track comments on linked issues-- **Pull requests** - To link PRs to tasks and update task status (opened, closed, reopened, merged)-- **Push** - To automatically update task status based on branch activity--<Warning>-**Required**: You must subscribe to **Issues** events for bidirectional synchronization to work.-</Warning>--<Info>-**Recommended**: Subscribe to all four event types for full integration features:-- **Issues**: Creates tasks from issues and syncs status/labels-- **Issue comments**: Tracks GitHub discussions-- **Pull requests**: Auto-updates task status when PRs are opened/merged-- **Push**: Moves tasks to "in-progress" when branches are pushed-</Info>--<Warning>-Without **Push** and **Pull requests** events, automatic status transitions won't work (e.g., moving tasks to "in-progress" on branch push or "done" on PR merge).-</Warning>-</Step>--<Step>-**Create the App**--Click "Create GitHub App" to create your app. You'll be redirected to the app settings page.-</Step>-</Steps>--## Step 2: Generate Credentials--<Steps>-<Step>-**Generate and Download Private Key**--1. Scroll down to the "Private keys" section-2. Click "Generate a private key"-3. Download the `.pem` file - you'll need its contents for configuration--<Warning>-Keep this private key secure! It's used to authenticate your Kaneo instance with GitHub.-</Warning>-</Step>--<Step>-**Note Your App Information**--From the app settings page, note down these important values:--- **App ID** (shown at the top of the page)-- **Webhook Secret** (the one you created earlier)-- **Private Key** (contents of the downloaded `.pem` file)--The GitHub App also shows an OAuth **Client ID** and **Client Secret** under "Basic information". Kaneo’s **repository integration** does not use those environment variables; they are only relevant if you enable **Sign in with GitHub** using `GITHUB_OAUTH_CLIENT_ID` / `GITHUB_OAUTH_CLIENT_SECRET` (see [GitHub SSO](/core/social-providers/github)).--<Info>-You need **App ID**, **private key**, and **webhook secret** for the [configuration step](/core/integrations/github/configuration).-</Info>-</Step>-</Steps>--## Step 3: Install the App--<Steps>-<Step>-**Install on Your Account/Organization**--1. Go to your GitHub App settings page-2. Click "Install App" in the left sidebar-3. Choose your account or organization-4. Select repositories:- - **All repositories** (if you want integration available for all repos)- - **Selected repositories** (choose specific repos)--<Tip>-You can modify repository access later by going to your [GitHub App installations](https://github.com/settings/installations).-</Tip>-</Step>--<Step>-**Verify Installation**--After installation, you should see your app listed in:-- [Your GitHub App installations](https://github.com/settings/installations)-- The repository's Settings → Integrations & services (for organization repos)-</Step>-</Steps>--## Security Best Practices--### App Configuration-- **Use descriptive names**: Make it clear the app is for Kaneo integration-- **Limit permissions**: Only grant the minimum required permissions-- **Repository scope**: Install only on repositories that need integration--### Credential Management-- **Secure storage**: Store credentials in environment variables or secret management systems-- **Regular rotation**: Generate new private keys periodically-- **Access control**: Limit who has access to the GitHub App settings--## Common Issues--### App Name Already Taken-If your desired app name is taken, try:-- Adding your organization name: `kaneo-mycompany`-- Adding a timestamp: `kaneo-mycompany-2024`-- Using a different naming convention: `mycompany-kaneo`--### Webhook URL Not Accessible-Ensure your Kaneo instance is:-- Publicly accessible on the internet-- Using HTTPS (GitHub requires this for webhooks)-- Not behind authentication that would block GitHub's webhook calls--### Permission Issues-Double-check that you've granted:-- **Write** access to Issues (not just Read)-- **Read** access to Pull Requests (for PR linking)-- **Read** access to Metadata and Contents-- Selected the correct repositories during installation--### Webhook Events Not Working-If automatic synchronization isn't happening:-- Verify all webhook events are subscribed (Issues, Issue comments, Pull requests, Push)-- Check webhook deliveries in GitHub App settings for failed deliveries-- Ensure your webhook URL is publicly accessible and using HTTPS--## Next Steps--Now that your GitHub App is created and configured:--1. **[Deploy Kaneo](/core)** - Deploy your Kaneo instance with the GitHub App credentials-2. **[Configure GitHub Integration](/core/integrations/github/configuration)** - Complete the integration setup in your deployed Kaneo instance-3. **[Connect Repositories](/core/integrations/github/configuration#connecting-repositories)** - Link your projects to GitHub repositories--<Info>-**Important**: Have your GitHub App credentials ready before deployment. You'll need to set them as environment variables during the deployment process.-</Info>-------**Need help?** Check our [troubleshooting guide](/core/integrations/github/troubleshooting) or ask for help on [Discord](https://discord.gg/rU4tSyhXXU).\ No newline at end of file+If verification or sync fails, check [GitHub troubleshooting](/core/integrations/github/troubleshooting).diff --git a/apps/docs/core/integrations/github/troubleshooting.mdx b/apps/docs/core/integrations/github/troubleshooting.mdxindex da25f2978..59450ebad 100644--- a/apps/docs/core/integrations/github/troubleshooting.mdx+++ b/apps/docs/core/integrations/github/troubleshooting.mdx@@ -1,369 +1,68 @@----title: Troubleshooting-description: Common issues and solutions for GitHub integration. Debug connection problems, permission errors, and webhook issues.+title: "GitHub troubleshooting"+description: "Find why repository connection, issue sync, or status changes stopped working."---+Start with the connection shown under **Settings → Projects → your project → Integrations → GitHub**. Then check the matching symptom below.-This guide helps you diagnose and fix common issues with the GitHub integration.+## The repository is missing or verification fails-## Common Issues+Open [GitHub App installations](https://github.com/settings/installations) and check that the app is installed on the correct account or organization. Add the specific repository to its allowed repositories if needed.-### "GitHub App not installed" Error+Confirm the owner and repository name in Kaneo. An organization owner may need to approve the installation or permission changes.-**Problem**: Verification shows the app isn't installed on the repository.+## Credentials changed, but Kaneo still fails-**Symptoms**:-- Red error message in Kaneo UI-- "Connect Repository" button remains disabled-- Repository doesn't appear in the browser modal+Update the instance's [GitHub environment variables](/core/installation/environment-variables#github-integration), then recreate the application container:-**Solutions**:-1. **Check Installation Scope**- - Go to [GitHub App installations](https://github.com/settings/installations)- - Verify your app is installed on the correct account/organization- - Check if the target repository is included in the installation scope--2. **Reinstall with Broader Access**- - Edit your app installation- - Change from "Selected repositories" to "All repositories"- - Or add the specific repository to the selected list--3. **Verify Repository Ownership**- - Ensure you're entering the correct repository owner (username/organization)- - Check that the repository name is spelled correctly- - Verify the repository exists and you have access to it--<Tip>-Use the "Browse Repositories" feature in Kaneo to see which repositories your app can access.-</Tip>--### "Missing Permissions" Error--**Problem**: App is installed but lacks required permissions.--**Symptoms**:-- Orange warning in verification-- App appears in installations but can't create issues-- Missing permissions listed in the error message--**Solutions**:-1. **Update App Permissions**- - Go to your [GitHub App settings](https://github.com/settings/developers)- - Edit your app and verify these permissions:- - **Issues**: Must have **Write** access (for creating/updating issues, adding labels, posting comments)- - **Pull Requests**: Must have **Read** access (for linking PRs to tasks)- - **Metadata**: Must have **Read** access (for repository information)- - **Contents**: Must have **Read** access (for tracking branch pushes)--2. **Update Installation**- - After changing app permissions, you may need to update the installation- - Go to [GitHub App installations](https://github.com/settings/installations)- - Click "Configure" on your Kaneo app- - Review and accept the new permissions- - Go to [GitHub App installations](https://github.com/settings/installations)- - Click "Configure" next to your app- - Review and accept any permission changes--3. **Check Organization Permissions**- - For organization repositories, ensure the organization allows the app- - Organization owners may need to approve third-party apps--### "Repository not found" Error--**Problem**: Repository exists but isn't accessible to the app.--**Symptoms**:-- Repository not found in verification-- 404-style errors in logs-- Repository doesn't appear in browse modal--**Solutions**:-1. **Verify Repository Details**- - Double-check the repository owner and name- - Ensure there are no typos or extra spaces- - Check that the repository is public or your app has access to private repos--2. **Check Private Repository Access**- - Private repositories require explicit app installation- - Ensure your GitHub App is installed on the repository owner's account- - Verify the app has permission to access private repositories--3. **Organization Repository Issues**- - Check if the organization has third-party app restrictions- - Ensure the app is approved by organization owners- - Verify the app is installed at the organization level, not just personal account--### Environment Variable Issues--**Problem**: Integration doesn't work after configuration.--**Symptoms**:-- No GitHub issues created when tasks are made-- Authentication errors in logs-- Integration appears configured but doesn't function--**Solutions**:-1. **Verify All Variables Are Set**- ```bash- # Check if integration environment variables are loaded (do not print secrets)- echo $GITHUB_APP_ID- if [ -n "$GITHUB_WEBHOOK_SECRET" ]; then echo "GITHUB_WEBHOOK_SECRET is set"; else echo "GITHUB_WEBHOOK_SECRET is missing"; fi- ```--2. **Check Private Key Format**- - Ensure `GITHUB_PRIVATE_KEY` includes the full content with proper line breaks- - The key should start with `-----BEGIN RSA PRIVATE KEY-----`- - The key should end with `-----END RSA PRIVATE KEY-----`- - Include all newlines and formatting from the `.pem` file--3. **Restart Backend Service**- - Environment variable changes require a service restart- - For Docker Compose: `docker compose restart backend`- - For Kubernetes: `kubectl rollout restart deployment/kaneo-backend`--4. **Check Log Output**- - Look for authentication errors on startup- - Verify the GitHub App ID is recognized- - Check for private key parsing errors--<Warning>-Make sure your private key doesn't have any extra characters or missing newlines.-</Warning>--## Webhook Issues--### Webhook Not Receiving Events--**Problem**: GitHub events aren't reaching Kaneo.--**Symptoms**:-- Webhook events listed in GitHub but no logs in Kaneo-- Webhook delivery failures in GitHub App settings--**Solutions**:-1. **Verify Webhook URL**- - Ensure the URL is publicly accessible: `https://your-domain.com/github-integration/webhook`- - Test accessibility from external tools like curl or online checkers- - Verify your domain has proper DNS resolution--2. **Check HTTPS Configuration**- - GitHub requires HTTPS for webhook endpoints- - Ensure your SSL certificate is valid and not self-signed- - Test your webhook endpoint with online SSL checkers--3. **Firewall and Network Issues**- - Ensure GitHub's IP ranges can reach your server- - Check if your hosting provider blocks incoming webhooks- - Verify no authentication middleware is blocking the webhook endpoint--### Webhook Signature Verification Fails--**Problem**: Webhooks reach Kaneo but signature verification fails.--**Symptoms**:-- "Invalid signature" errors in logs-- Webhook events rejected with 400 status--**Solutions**:-1. **Verify Webhook Secret**- - Ensure `GITHUB_WEBHOOK_SECRET` matches exactly what you set in the GitHub App- - Check for extra spaces or characters- - The secret is case-sensitive--2. **Check Secret Configuration**- - In GitHub App settings, verify the webhook secret is set- - If you changed the secret, update the environment variable and restart- - Generate a new secret if there are persistent issues--### Automatic Status Transitions Not Working--**Problem**: Tasks aren't automatically updating when you push branches or open/merge PRs.--**Symptoms**:-- Task stays in "to-do" after pushing a branch-- Task doesn't move to "in-review" when PR is opened-- Task doesn't move to "done" when PR is merged--**Solutions**:-1. **Verify Webhook Subscriptions**- - Go to your [GitHub App settings](https://github.com/settings/developers)- - Check the "Webhook" section and verify these events are subscribed:- - **Push** - For branch-based status transitions- - **Pull requests** - For PR-based status transitions- - If missing, add them and save--2. **Check Pull Requests Permission**- - Ensure your app has **Read** access to Pull Requests- - Without this permission, PR events won't work- - Update the permission if needed and reinstall the app--3. **Verify Branch Naming Pattern**- - Your branch name must match the configured pattern (default: `{slug}-{number}`)- - Example: For task `PROJ-123`, use branch `proj-123` or `PROJ-123`- - Check your project's GitHub integration settings for the configured pattern--4. **Check Status Transition Configuration**- - Verify your status transition settings in the project GitHub integration- - Default transitions:- - Branch push → `in-progress`- - PR opened → `in-review`- - PR merged → `done`- - These can be customized per project--5. **Review Webhook Delivery Logs**- - In GitHub App settings → Advanced tab- - Check if Push and Pull request events are being delivered- - Look for successful 200 responses--<Tip>-Test the automatic transitions by:-1. Creating a task (e.g., `PROJ-123`)-2. Creating a branch named `proj-123` and pushing it-3. Verify the task moves to "in-progress"-4. Opening a PR from that branch-5. Verify the task moves to "in-review"-</Tip>--### Issue Label Synchronization Issues--**Problem**: Labels aren't syncing between Kaneo and GitHub.--**Symptoms**:-- Changing priority in Kaneo doesn't update GitHub labels-- Adding labels in GitHub doesn't reflect in Kaneo-- Labels have wrong colors or formats--**Solutions**:-1. **Check Label Format**- - System labels must use the format: `priority:{level}` or `status:{status}`- - Valid priority labels: `priority:low`, `priority:medium`, `priority:high`, `priority:urgent`- - Valid status labels: `status:to-do`, `status:in-progress`, `status:in-review`, `status:done`--2. **Verify Issues Write Permission**- - Label management requires **Write** access to Issues- - Check your GitHub App permissions- - Update and reinstall if needed--3. **Check Webhook Events**- - Ensure **Issues** events are subscribed (especially "labeled" and "unlabeled")- - Without these, label changes from GitHub won't sync to Kaneo--## Testing and Debugging--### Testing the Integration--Follow these steps to systematically test your integration:--1. **Verify Environment Variables**- ```bash- # Check that all required integration variables are set (don't print private key or webhook secret!)- echo "App ID: $GITHUB_APP_ID"- echo "App Name: $GITHUB_APP_NAME"- if [ -n "$GITHUB_WEBHOOK_SECRET" ]; then echo "GITHUB_WEBHOOK_SECRET is set"; else echo "GITHUB_WEBHOOK_SECRET is missing"; fi- ```--2. **Test Repository Access**- - Use the "Browse Repositories" feature in Kaneo- - Verify your target repository appears in the list- - Try connecting a test repository first--3. **Create a Test Task**- - Create a simple task in your connected project- - Check GitHub immediately for the new issue- - Verify the issue format and labels are correct--4. **Check Backend Logs**- Look for these log messages:- ```- ✅ GitHub issue created: { issueNumber: 42, issueUrl: "...", taskId: "...", repository: "..." }- ❌ Failed to create GitHub issue: [error details]- ✅ Task created: { taskId: "...", title: "...", projectId: "..." }- ```--### Log Analysis--**Successful Integration Logs**:-```-Task created: { taskId: "task_123", title: "Fix bug", projectId: "proj_456" }-Creating GitHub issue for repository: owner/repo-GitHub issue created: { issueNumber: 42, issueUrl: "https://github.com/owner/repo/issues/42" }-```--**Common Error Patterns**:-```-❌ No active GitHub integration found for project: proj_456-❌ Failed to create GitHub issue: HttpError: Bad credentials-❌ Repository not found: owner/nonexistent-repo-❌ App installation not found for repository: owner/repo+```bash+docker compose up -d --force-recreate kaneo+docker compose logs --tail=100 kaneo```-### GitHub App Diagnostics+A plain container restart does not reload `.env`. Check the app ID, webhook secret, and private key format. For PEM formatting problems, use `GITHUB_PRIVATE_KEY_BASE64` with the encoded full key. Do not paste the private key or secret into a support issue.-Use GitHub's built-in tools to diagnose issues:+## GitHub events never arrive-1. **App Installation Page**- - Visit [GitHub App installations](https://github.com/settings/installations)- - Check which repositories your app can access- - Review granted permissions+The webhook URL for the bundled deployment is:-2. **Webhook Delivery Logs**- - In your GitHub App settings, check the "Advanced" tab- - Review recent webhook deliveries and their status codes- - Look for failed deliveries or error responses+```text+https://kaneo.example.com/api/github-integration/webhook+```-3. **Repository Integration Status**- - Go to your repository's Settings → Integrations & services- - Verify your app appears in the list- - Check the app's permissions and access+In the GitHub App settings, open **Advanced** and inspect recent deliveries. Check the response code and body for the failing event.-## Getting Help+- A connection error points to DNS, TLS, firewall, or proxy configuration.+- A `404` can mean the proxy dropped `/api` or the webhook path is wrong.+- A signature error means the webhook secret may differ between GitHub and Kaneo.-If you're still experiencing issues:+After correcting the cause, redeliver the failed event in GitHub and check the result in Kaneo.-### Before Asking for Help+## Tasks or issues do not sync-1. **Check Your Setup**- - Verify all environment variables are correct- - Ensure your GitHub App has the right permissions- - Test with a simple repository first+Check that the app has the permissions and event subscriptions in [GitHub App setup](/core/integrations/github/setup). After changing permissions, accept the installation update in GitHub.-2. **Gather Information**- - Note the exact error messages- - Check both Kaneo logs and GitHub webhook delivery logs- - Document your environment (Docker, Kubernetes, etc.)+Create one test task, then one test issue in the connected repository. Check the API logs and webhook delivery for each direction separately. Creating a task exercises Kaneo's outgoing GitHub credentials; creating an issue exercises GitHub's incoming webhook path.-3. **Test Basic Functionality**- - Try creating a task without GitHub integration- - Verify your Kaneo instance is working normally- - Test with different repositories if possible+For existing issues, use **Import Issues**. If an import stops, return to the integration settings and choose **Resume import**. See [import behavior](/core/integrations/github/configuration#import-existing-issues) before starting another run.-### Support Channels+## Branches and pull requests do not move tasks-- **[Discord Community](https://discord.gg/rU4tSyhXXU)** - Real-time help from the community-- **[GitHub Issues](https://github.com/usekaneo/kaneo/issues)** - Report bugs or request features-- **[Documentation](/core)** - Review setup guides and troubleshooting+Check the branch naming pattern in the project's integration settings. The default is `{slug}-{number}`, for example `web-22` for task `WEB-22`.-### What to Include in Support Requests+Then check:-1. **Environment Details**- - Kaneo version- - Deployment method (Docker, Kubernetes, etc.)- - Operating system+1. The app can read pull requests and repository contents.+2. Push and pull-request events are subscribed and arriving.+3. **Workflow → Automation Rules** maps the event to the intended column.+4. The task is eligible for the transition. Completed tasks are protected from automatic reopening by the integration.-2. **Error Information**- - Exact error messages- - Screenshots of the issue- - Relevant log entries+Try one branch push and inspect its webhook delivery before testing another event.-3. **Configuration Details**- - Which environment variables you've set (don't share secret values!)- - GitHub App permissions you've granted- - Repository details (without sharing sensitive info)+## Labels look different-<Info>-When sharing logs or error messages, always redact sensitive information like private keys, secrets, or access tokens.-</Info>+Kaneo uses reserved labels such as `priority:high` and `status:in-progress`. Check their spelling and the Issues write permission. Ordinary labels are separate from these reserved status and priority labels.----+## Ask for help-**Still stuck?** The Kaneo community is here to help! Join our [Discord](https://discord.gg/rU4tSyhXXU) for real-time support.\ No newline at end of file+Include the Kaneo version, the event that failed, its delivery status, and a redacted error from the API logs in a [GitHub issue](https://github.com/usekaneo/kaneo/issues). Do not include credentials or private issue content.diff --git a/apps/docs/core/integrations/gotify.mdx b/apps/docs/core/integrations/gotify.mdxnew file mode 100644index 000000000..f4edebe4a--- /dev/null+++ b/apps/docs/core/integrations/gotify.mdx@@ -0,0 +1,33 @@+---+title: Gotify+description: Send personal Kaneo notifications through Gotify.+---++Use your Gotify server to deliver Kaneo account notifications to your devices.++## Connect Gotify++1. Create an application for Kaneo on your Gotify server and copy its application token. Use an application token for publishing, as described in [Gotify’s push-message guide](https://gotify.net/docs/pushmsg).+2. Open **Settings → Account → Notifications** in Kaneo and find **Gotify**.+3. Enter the base URL, such as `https://gotify.example.com`. Leave off `/message` and token query parameters; Kaneo adds them when sending.+4. Paste the application token, enable the channel, and choose **Connect Gotify**.++Messages include the notification title and text, with a task link when one is available.++## Choose what reaches Gotify++Enable your event categories at the top of the page. Add an active workspace rule, enable Gotify on it, and choose all projects or specific ones. Save the rule.++Ask a teammate to assign a test task to you in one of those projects. Confirm it appears in your Kaneo inbox and Gotify. Your own task changes may not create a notification for you.++## Change or disconnect++Enter a new application token and choose **Save changes** to rotate credentials. An empty token field preserves the saved token. **Disconnect** removes the server URL and token from Kaneo. Revoke the application token in Gotify if nothing else uses it.++If you disable the channel and later enable it again, review its workspace rules before resuming use.++## Self-hosting requirements and troubleshooting++The Kaneo API must be able to reach your notification server. Private network destinations require the operator to enable `KANEO_ALLOW_PRIVATE_WEBHOOK_DESTINATIONS`. To save a token, the API also needs a stable `NOTIFICATION_SECRET_ENCRYPTION_KEY`; see [notification server settings](/core/installation/environment-variables#notifications).++If a notification stays in the inbox but is not delivered, check the channel, workspace rule, project selection, and destination credentials. If it never reaches the inbox, check your event preferences and whether that action should notify your account. See [Notifications](/core/functional/account-notifications) for the full flow.diff --git a/apps/docs/core/integrations/index.mdx b/apps/docs/core/integrations/index.mdxnew file mode 100644index 000000000..ae1503083--- /dev/null+++ b/apps/docs/core/integrations/index.mdx@@ -0,0 +1,87 @@+---+title: Integrations+description: Find the right connection for repositories, team updates, personal notifications, and automation.+---++Connect the tools your team already uses. Repository connections and shared notifications belong to a project. Personal notification channels belong to your account.++## Repositories++<CardGroup cols={3}>+ <Card title="GitHub" icon="github" href="/core/integrations/github/setup">+ Sync issues and comments, link pull requests, and automate task status.+ </Card>+ <Card title="Gitea" icon="git-branch" href="/core/integrations/gitea/setup">+ Connect your Gitea server for issue sync and workflow automation.+ </Card>+ <Card title="GitLab" icon="gitlab" href="/core/integrations/gitlab/setup">+ Connect GitLab.com or your own instance to sync issues and track merge requests.+ </Card>+</CardGroup>++GitHub, Gitea, and GitLab have connection forms under **Settings → Projects → your project → Integrations**. Follow the provider guide to connect a repository and configure its webhook.++## Team notifications++Send selected project events to a shared channel. Open **Settings → Projects → your project → Integrations** to connect these services.++<CardGroup cols={2}>+ <Card title="Slack" icon="slack" href="/core/integrations/slack">+ Post task updates to a Slack channel through an incoming webhook.+ </Card>+ <Card title="Discord" icon="message-circle" href="/core/integrations/discord">+ Send task activity to a Discord channel.+ </Card>+ <Card title="Mattermost" icon="messages-square" href="/core/integrations/mattermost">+ Connect an incoming webhook on your Mattermost instance.+ </Card>+ <Card title="Telegram" icon="send" href="/core/integrations/telegram">+ Send updates through a bot to a chat, group, channel, or forum topic.+ </Card>+</CardGroup>++<Frame caption="Project integrations live together in Settings. Expand a service to configure its connection.">+ <img className="block dark:hidden" src="/images/product/integrations-light.png" alt="Kaneo project settings showing the GitHub, Gitea, GitLab, and team notification integrations." />+ <img className="hidden dark:block" src="/images/product/integrations-dark.png" alt="Kaneo project settings showing the GitHub, Gitea, GitLab, and team notification integrations." />+</Frame>++## Personal notifications++Receive updates meant for you, such as assignments, mentions, and due-date reminders. Connect these under **Settings → Account → Notifications**, then choose the workspaces and projects that can send them.++<CardGroup cols={2}>+ <Card title="ntfy" icon="bell" href="/core/integrations/ntfy">+ Publish your notifications to an ntfy topic.+ </Card>+ <Card title="Gotify" icon="smartphone" href="/core/integrations/gotify">+ Receive notifications through your Gotify server.+ </Card>+ <Card title="Email" icon="mail" href="/core/functional/account-notifications#2-connect-a-channel">+ Send updates to your account email. Self-hosted instances need SMTP.+ </Card>+ <Card title="Personal webhook" icon="webhook" href="/core/integrations/personal-webhooks">+ Forward your own notifications to an HTTP endpoint.+ </Card>+</CardGroup>++[Notification preferences](/core/functional/account-notifications) control the events and workspace rules for all four channels.++## Automation and AI assistants++<CardGroup cols={3}>+ <Card title="Project webhooks" icon="radio" href="/core/integrations/outgoing-webhooks">+ Send selected project events to your service as signed JSON requests.+ </Card>+ <Card title="MCP" icon="bot" href="/core/integrations/mcp">+ Let an MCP client work with your Kaneo tasks and projects.+ </Card>+ <Card title="REST API" icon="code" href="/api-reference/introduction">+ Create tasks, query projects, or build a connection to another service.+ </Card>+</CardGroup>++## Looking for sign-in or file storage?++Sign-in providers are configured by the instance operator: [GitHub](/core/social-providers/github), [Google](/core/social-providers/google), [Discord](/core/social-providers/discord), or [custom OAuth/OIDC](/core/social-providers/custom-oauth).++For attachments, use [Silo](/core/installation/silo) or [another S3-compatible provider](/core/installation/storage-backends).diff --git a/apps/docs/core/integrations/mattermost.mdx b/apps/docs/core/integrations/mattermost.mdxindex 0ba0a086d..6c2edeaf5 100644--- a/apps/docs/core/integrations/mattermost.mdx+++ b/apps/docs/core/integrations/mattermost.mdx@@ -3,7 +3,7 @@ title: Mattermostdescription: Send task notifications from Kaneo to a Mattermost channel using incoming webhooks.----Kaneo can post task activity to a Mattermost channel whenever events occur in a project. This uses Mattermost's incoming webhook feature — no bot account or OAuth flow required.+Kaneo can post task activity to a Mattermost channel whenever events occur in a project. This uses Mattermost's incoming webhook feature; no bot account or OAuth flow required.## Create a Mattermost webhookdiff --git a/apps/docs/core/integrations/mcp-stateless.mdx b/apps/docs/core/integrations/mcp-stateless.mdxindex 8e014c9c6..a59f91b1a 100644--- a/apps/docs/core/integrations/mcp-stateless.mdx+++ b/apps/docs/core/integrations/mcp-stateless.mdx@@ -1,122 +1,74 @@----title: MCP 2026-07-28 stateless compatibility-description: Protocol contract, verification, limitations, and rollback for Kaneo's dual-era Streamable HTTP endpoint.+title: MCP protocol reference+description: Authentication, transport behavior, and deployment limits for Kaneo’s HTTP MCP endpoint.----# MCP 2026-07-28 stateless compatibility+Use the [MCP setup guide](/core/integrations/mcp) to connect a client. This page is for people operating Kaneo or building an MCP client.-Research date: 2026-08-09.+## Endpoint and authentication-## Contract and primary sources+The HTTP endpoint is `/api/mcp`. Every request requires a bearer token that Kaneo can resolve to an authenticated user. Tools make internal API requests as that user, so workspace permissions still apply.-MCP revision `2026-07-28` changes Streamable HTTP from a protocol-session-model to a per-request model. Modern clients do not call `initialize` or-`notifications/initialized`, and the server does not mint `Mcp-Session-Id`.-Every JSON-RPC message uses a separate HTTP POST and carries protocol version,-client identity, and capabilities in request metadata.+OAuth clients discover Kaneo’s authorization server, register a public client, and use the authorization code flow with PKCE (`S256`). The user must approve the connection in Kaneo. The token endpoint supports the authorization-code grant; it does not advertise a refresh-token grant.-Primary sources:+The discovery URLs at the public API origin are:-- [MCP 2026-07-28 changelog](https://modelcontextprotocol.io/specification/2026-07-28/changelog)-- [Streamable HTTP specification](https://modelcontextprotocol.io/specification/2026-07-28/basic/transports/streamable-http)-- [SEP-2575: Make MCP Stateless](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/seps/2575-stateless-mcp.md)-- [OpenAI Codex support commit](https://github.com/openai/codex/commit/be2e4afcd739)-- [Official OpenAI MCP documentation](https://learn.chatgpt.com/docs/extend/mcp)+- `/.well-known/oauth-protected-resource/api/mcp`+- `/.well-known/oauth-authorization-server/api`-Required modern request fields include:+The API also serves these under `/api/.well-known/`. Preserve discovery routes as well as `/api/mcp` when configuring your reverse proxy.-- `MCP-Protocol-Version: 2026-07-28`-- `Mcp-Method: <json-rpc-method>`-- `Mcp-Name: <tool-name>` for `tools/call`-- matching `params._meta["io.modelcontextprotocol/protocolVersion"]`-- per-request client capabilities and, preferably, client information+## Supported transports-Kaneo validates the bearer token before protocol routing on every request.-Modern requests use a fresh `McpServer` instance and hold no process-local-protocol state. Requests classified as the 2025 era continue through the-existing sessionful transport, preserving `initialize`,-`notifications/initialized`, and `Mcp-Session-Id` behavior.+| Client flow | Kaneo behavior |+| --- | --- |+| MCP 2026-07-28 | A fresh server handles each request. No protocol session is retained between requests. |+| Legacy session flow | The client initializes a session, then sends the returned `Mcp-Session-Id` on later requests. |+| Local stdio | The separate `@kaneo/mcp` package uses device authorization and communicates with the Kaneo API. |-This dual-era split matters: treating a sessionful `2025-06-18` exchange as-"stateless" because its POSTs use separate TCP connections does not implement-the `2026-07-28` contract.+Let your client negotiate its supported protocol. No Kaneo environment switch is needed to choose between HTTP protocol versions.-## Automated verification+Legacy sessions live in the API process. A restart loses them, and requests for an unknown session return HTTP 404. The client must initialize again. If you run multiple API replicas, route a legacy session back to the same replica. Redis distributes realtime application events; it does not share MCP protocol sessions.-From the repository root:+Modern requests do not need session affinity. OAuth registration and pending authorization state are stored in PostgreSQL and shared between API replicas.-```bash-pnpm --filter @kaneo/api test:unit-pnpm --filter @kaneo/api typecheck-pnpm --filter @kaneo/api build-```+## Reverse proxy and internal requests-`tests/api/mcp-stateless.test.ts` verifies:+Forward the client’s authorization, content type, and MCP headers unchanged. Allow streaming responses for clients that use them.-1. repeated `tools/list` calls on independent requests without session IDs;-2. concurrent read-only `tools/call` requests with bearer propagation;-3. rejection of missing per-request metadata;-4. an effectful `update_task_status` request;-5. separation of modern traffic from legacy `initialize` traffic.+HTTP MCP tools reach Kaneo’s API through `KANEO_INTERNAL_API_URL`, which defaults to `http://127.0.0.1:1337`. This is a server-side address, separate from the public URL used for discovery and sign-in. Set it only when that loopback address does not reach the API from its own process.-The tests use an in-process handler and stub the internal Kaneo API fetch. They-do not mutate a real Kaneo database.+## Troubleshooting-## Codex configuration and manual verification+| Response | What to check |+| --- | --- |+| 401 | Complete OAuth sign-in again and check that the proxy forwards the bearer token. |+| 404 with “Session not found” | Reconnect the client. For multiple replicas, check legacy session affinity. |+| 405 | A request without a session must use POST. |+| 415 | Send JSON with the correct content type. |+| 429 | Wait for `Retry-After` before retrying. |-Codex CLI `0.147.0` contains `mcp_2026_07_28`, but the feature is under-development and disabled by default. Confirm the installed build before-testing:+A tool can also fail because the user lacks permission or its arguments do not match the project. Call `list_project_columns` before assigning a status and `list_workspace_members` before assigning a user.-```bash-which codex-codex --version-codex features list | grep '^mcp_2026_07_28'-codex -c features.mcp_2026_07_28=true features list | grep '^mcp_2026_07_28'-```+### OAuth request limits-Permanent configuration, once the operator chooses to enable the experimental-client path:+The HTTP OAuth endpoints accept bodies up to 32 KiB and URLs up to 8 KiB.+Client registration accepts at most 10 redirect URIs. Request bodies must arrive+within five seconds. Each API process allows up to 16 concurrent requests in+each of the registration, authorization, and token endpoint groups.-```toml-[features]-mcp_2026_07_28 = true+Instances sharing a database also share OAuth storage and issuance limits:-[mcp_servers.kaneo]-url = "https://your-kaneo-instance.com/api/mcp"-bearer_token_env_var = "KANEO_MCP_TOKEN"-startup_timeout_sec = 20-tool_timeout_sec = 60-```+| State | Stored entries | New entries per minute | Pending entries per client |+| --- | --- | --- | --- |+| Registered clients | 1,000 | 60 | Not applicable |+| Authorization requests | 10,000 | 300 | 20 |+| Authorization codes | 10,000 | 300 | 20 |-Keep the token in the environment, not in `config.toml`. Then start a new Codex-session, inspect `/mcp`, list Kaneo tools, call `whoami`, and perform one-explicitly approved effectful call on test data. Capture traffic only with-authorization values redacted. Modern traffic must show `server/discover`-followed by self-contained calls, no `initialize`, and no `Mcp-Session-Id`.--With the feature disabled, Codex uses its legacy MCP lifecycle. Kaneo should-still complete `initialize`, return a session ID, accept-`notifications/initialized`, and serve tools on later requests carrying that-ID.--## Limitations--- OpenAI documentation confirms Streamable HTTP, bearer tokens, and OAuth, but- does not publish a Codex-release-to-MCP-revision matrix.-- Modern Codex support remains experimental in `0.147.0`; dual-era serving is- required until deployed clients are confirmed.-- The modern handler is request-local. Kaneo tools currently need no- server-to-client request channel or cross-request protocol state.-- No production image or NAS stack is changed by the repository tests.--## Rollback--Code rollback removes the modern route and `@modelcontextprotocol/server` v2,-leaving the existing v1 sessionful branch unchanged. Client rollback disables-`features.mcp_2026_07_28` and starts a new Codex session. No database migration-is involved.--Production rollback must happen by deploying the previous Kaneo image through-the normal operator-controlled stack workflow. Do not restart the host and do-not remove persistent volumes.+When capacity is exhausted, the endpoint returns HTTP 429 with `Retry-After`.+Clients should wait before retrying. Existing, unexpired entries are retained;+an approval that cannot issue a code leaves its authorization request available+for retry until it expires. Expired entries are cleaned up in bounded batches+when new state is created, so a previously oversized store may need multiple+attempts before accepting new entries. These limits complement reverse-proxy+connection and request limits for internet-facing installations.diff --git a/apps/docs/core/integrations/mcp.mdx b/apps/docs/core/integrations/mcp.mdxindex e259d07b3..13a5b3ff8 100644--- a/apps/docs/core/integrations/mcp.mdx+++ b/apps/docs/core/integrations/mcp.mdx@@ -20,7 +20,7 @@ Point your MCP client at:https://your-kaneo-instance.com/api/mcp```-On first connect, you will be redirected to Kaneo to sign in and explicitly approve the MCP client. After approval, all MCP tools run as your authenticated user.+With an OAuth-capable client, you will be redirected to Kaneo to sign in and explicitly approve the MCP client. After approval, all MCP tools run as your authenticated user.The endpoint implements OAuth 2.1 with PKCE for authentication. Discovery metadata is available at:@@ -29,31 +29,8 @@ The endpoint implements OAuth 2.1 with PKCE for authentication. Discovery metadaThe endpoint serves both MCP protocol eras: modern `2026-07-28` requests arestateless and self-contained, while 2025-era clients keep the sessionful-`initialize` flow. See [MCP 2026-07-28 stateless compatibility](/core/integrations/mcp-stateless)-for the exact contract, tests, Codex configuration, limitations, and rollback.--### OAuth request limits--The HTTP OAuth endpoints accept bodies up to 32 KiB and URLs up to 8 KiB.-Client registration accepts at most 10 redirect URIs. Request bodies must arrive-within five seconds. Each API process allows up to 16 concurrent requests in-each of the registration, authorization, and token endpoint groups.--Instances sharing a database also share OAuth storage and issuance limits:--| State | Stored entries | New entries per minute | Pending entries per client |-| --- | --- | --- | --- |-| Registered clients | 1,000 | 60 | — |-| Authorization requests | 10,000 | 300 | 20 |-| Authorization codes | 10,000 | 300 | 20 |--When capacity is exhausted, the endpoint returns HTTP 429 with `Retry-After`.-Clients should wait before retrying. Existing, unexpired entries are retained;-an approval that cannot issue a code leaves its authorization request available-for retry until it expires. Expired entries are cleaned up in bounded batches-when new state is created, so a previously oversized store may need multiple-attempts before accepting new entries. These limits complement reverse-proxy-connection and request limits for internet-facing installations.+`initialize` flow. See [MCP protocol reference](/core/integrations/mcp-stateless)+for transport behavior, proxy requirements, and request limits.## Stdio package@@ -72,7 +49,7 @@ By default, self-hosted Kaneo allows both `kaneo-cli` and `kaneo-mcp` as deviceUse the recommended interactive installer:```bash-npx @kaneo/mcp+npx -y @kaneo/mcp```The installer lets you choose where to register the server configuration:@@ -85,13 +62,13 @@ The installer lets you choose where to register the server configuration:You can also run the explicit install command:```bash-kaneo-mcp install --target cursor-user -y+npx -y @kaneo/mcp install --target cursor-user -y```Use `--help` to see all available targets and flags:```bash-kaneo-mcp install --help+npx -y @kaneo/mcp install --help```### Point to a self-hosted instance@@ -99,14 +76,14 @@ kaneo-mcp install --helpWhen generating config, pass your Kaneo base URL:```bash-kaneo-mcp install --target cursor-user -y --api-url https://kaneo.example.com+npx -y @kaneo/mcp install --target cursor-user -y --api-url https://kaneo.example.com```Or set it via environment variable:| Variable | Description || --- | --- |-| `KANEO_API_URL` | Kaneo API origin. Default: `http://localhost:1337`. Do not include `/api`. |+| `KANEO_API_URL` | Kaneo API base URL. Default: `http://localhost:1337`. A trailing `/api` is accepted and normalized. || `KANEO_MCP_CLIENT_ID` | Device auth client ID. Default: `kaneo-mcp`. |If you override `KANEO_MCP_CLIENT_ID`, make sure it is included in [`DEVICE_AUTH_CLIENT_IDS`](/core/installation/environment-variables).@@ -119,7 +96,7 @@ On the first tool call that needs Kaneo access, the MCP server:2. Prints a verification URL and user code3. Opens the browser when possible4. Polls until you approve sign-in-5. Stores credentials in `~/.config/kaneo-mcp/credentials.json`+5. Stores credentials in `$XDG_CONFIG_HOME/kaneo-mcp/credentials.json`, or `~/.config/kaneo-mcp/credentials.json` when `XDG_CONFIG_HOME` is unset## Available tools@@ -130,7 +107,7 @@ Both the HTTP endpoint and stdio package expose the same tools:- Projects: `list_projects`, `get_project`, `create_project`, `update_project`, `list_project_columns`- Tasks: `list_tasks`, `get_task`, `create_task`, `duplicate_task`, `update_task`, `delete_task`, `move_task`, `update_task_status`, `update_task_assignee`, `update_task_due_date`, `list_task_activity`- Time entries: `list_task_time_entries`, `get_time_entry`, `create_time_entry`, `update_time_entry`-- Comments: `list_task_comments`, `create_task_comment`+- Comments: `list_task_comments`, `create_task_comment`, `update_task_comment`, `delete_task_comment`- Labels: `list_workspace_labels`, `create_label`, `attach_label_to_task`, `detach_label_from_task`, `delete_label`- Task relations: `create_task_relation`, `get_task_relations`, `delete_task_relation`@@ -145,7 +122,7 @@ tools expect. Time entries have no delete endpoint on the API, so there is noTo run the stdio server directly:```bash-npx @kaneo/mcp serve+npx -y @kaneo/mcp serve```When running from source in this monorepo:diff --git a/apps/docs/core/integrations/ntfy.mdx b/apps/docs/core/integrations/ntfy.mdxnew file mode 100644index 000000000..f702fdccd--- /dev/null+++ b/apps/docs/core/integrations/ntfy.mdx@@ -0,0 +1,34 @@+---+title: ntfy+description: Send personal Kaneo notifications through ntfy.+---++Use ntfy to receive your Kaneo account notifications on devices subscribed to a topic.++## Connect ntfy++1. Choose an ntfy server and a topic you can publish to. Subscribe to that topic in your ntfy client. Follow [ntfy’s publishing guide](https://docs.ntfy.sh/publish/) for topic access and tokens.+2. Open **Settings → Account → Notifications** in Kaneo and find **ntfy**.+3. Enter the server’s base URL, for example `https://ntfy.example.com`, and the topic in its separate field. Do not append the topic to the server URL.+4. If the server requires authentication, enter a token with permission to publish to that topic.+5. Enable the channel and choose **Connect ntfy**.++Kaneo includes the notification title, message, and a task link when one is available. Choose a topic with access controls appropriate for the task information being sent.++## Choose what reaches the topic++Enable the notification categories you want at the top of the page. Add an active workspace rule below the channel settings, enable ntfy on it, and select all projects or specific ones. Save the rule.++Ask a teammate to assign a test task to you in an included project. Check that it appears in both your Kaneo inbox and your ntfy client. Events you perform yourself may not notify you.++## Change or disconnect++Enter a replacement token and choose **Save changes** to rotate it. Leaving the token field empty keeps the stored token. Choose **Disconnect** to remove the saved server, topic, and token from Kaneo.++If you disable the channel and later enable it again, review its workspace rules before resuming use.++## Self-hosting requirements and troubleshooting++The Kaneo API must be able to reach your notification server. Private network destinations require the operator to enable `KANEO_ALLOW_PRIVATE_WEBHOOK_DESTINATIONS`. To save a token, the API also needs a stable `NOTIFICATION_SECRET_ENCRYPTION_KEY`; see [notification server settings](/core/installation/environment-variables#notifications).++If a notification stays in the inbox but is not delivered, check the channel, workspace rule, project selection, and destination credentials. If it never reaches the inbox, check your event preferences and whether that action should notify your account. See [Notifications](/core/functional/account-notifications) for the full flow.diff --git a/apps/docs/core/integrations/outgoing-webhooks.mdx b/apps/docs/core/integrations/outgoing-webhooks.mdxindex ff624201e..b44b489b6 100644--- a/apps/docs/core/integrations/outgoing-webhooks.mdx+++ b/apps/docs/core/integrations/outgoing-webhooks.mdx@@ -1,9 +1,9 @@---title: Outgoing webhooks-description: Send task activity from a Kaneo project to Slack, Discord, Telegram, or any HTTP endpoint. Configure per-project notifications and optional signing.+description: Send task activity from a Kaneo project to Slack, Discord, Mattermost, Telegram, or any HTTP endpoint. Configure per-project notifications and optional signing.----Kaneo can notify external systems when tasks change in a project. Each integration is per project and uses either an incoming webhook URL from the service you connect (Slack, Discord), a bot token plus chat ID (Telegram), or your own HTTP listener (generic webhook).+Kaneo can notify external systems when tasks change in a project. Each integration is per project and uses either an incoming webhook URL from the service you connect (Slack, Discord, Mattermost), a bot token plus chat ID (Telegram), or your own HTTP listener (generic webhook).<Info>These integrations are outgoing only: Kaneo posts to your URL when events occur. They are separate from [GitHub integration](/core/integrations/github/setup), which syncs issues and repositories.@@ -21,7 +21,7 @@ Notification messages and generic webhook payloads include links to the task in## Events you can subscribe to-For Slack, Discord, Telegram, and generic webhooks you can toggle the same event types:+For Slack, Discord, Mattermost, Telegram, and generic webhooks you can toggle the same event types:| Event | Default on | Description || --- | --- | --- |@@ -52,6 +52,10 @@ Create an incoming webhook for a Discord channel (Channel settings → Integrati(or the `discordapp.com` hostname). Paste it into the Discord section, optionally add a channel name label, select events, and save.+## Mattermost++Use an HTTPS incoming webhook URL from your Mattermost instance. Follow the [Mattermost setup guide](/core/integrations/mattermost) for connection and event settings.+## TelegramCreate a Telegram bot with [`@BotFather`](https://t.me/BotFather), then add that bot to the destination chat, group, channel, or topic. Telegram requires:@@ -72,6 +76,21 @@ Paste those values into the Telegram section, optionally add a chat label, choosUse a generic webhook when you want a JSON POST to your own service, automation, or middleware.+Generic webhooks also support these events. They are off by default:++| Event | Payload `event` |+| --- | --- |+| Task deleted | `task.deleted` |+| Task moved to another project | `task.moved` |+| Due date changed | `task.due_date_changed` |+| Assignee changed | `task.assignee_changed` |+| Task unassigned | `task.unassigned` |+| Due-date reminder | `task.due_date_reminder` |++When enabling due-date reminders, set how far ahead to send them. The default is 24 hours. These extra subscriptions are specific to the generic webhook integration; the chat integrations use the six-event table above.++The destination must use HTTP or HTTPS and be reachable from the API. Private network destinations are blocked unless the operator enables `KANEO_ALLOW_PRIVATE_WEBHOOK_DESTINATIONS`.+### Delivery healthAfter delivery attempts, Kaneo stores basic health metadata (for example last success, last failure message, failure count) so you can see whether recent posts succeeded. This does not replace monitoring on your endpoint.@@ -80,15 +99,15 @@ After delivery attempts, Kaneo stores basic health metadata (for example last suEach POST has `Content-Type: application/json`. Top-level fields:-- `event`: string, one of: `task.created`, `task.status_changed`, `task.priority_changed`, `task.title_changed`, `task.description_changed`, `task.comment_created`+- `event`: string, one of: `task.created`, `task.status_changed`, `task.priority_changed`, `task.title_changed`, `task.description_changed`, `task.comment_created`, or one of the additional generic webhook events above- `timestamp`: ISO 8601 time when Kaneo sent the request- `integration`: `{ "type": "generic-webhook" }`- `project`: `id`, `name`, `workspaceId`-- `task`: `id`, `number`, `title`, `status`, `priority`, `url` (link to the task in the web UI)+- `task`: `id`, `number`, `title`, `status`, `statusName`, `priority`, `url` (link to the task in the web UI)- `actor`: `id` and `name` of the user when available, or nulls for automated actions- `data`: event-specific fields (for example `oldStatus` / `newStatus` for status changes, `comment` text for comments)-Use these payloads to drive custom workflows, internal dashboards, or bridges to other tools.+For `task.deleted`, the `task` object contains only `id` and `title`, and `data` is empty. Do not require the usual task URL or status fields when handling deletion. Move events include source and destination project IDs; reminders include `dueDate` and `leadTimeMinutes`.### Signature verificationdiff --git a/apps/docs/core/integrations/personal-webhooks.mdx b/apps/docs/core/integrations/personal-webhooks.mdxnew file mode 100644index 000000000..868170856--- /dev/null+++ b/apps/docs/core/integrations/personal-webhooks.mdx@@ -0,0 +1,42 @@+---+title: Personal webhooks+description: Forward your account notifications to an HTTP receiver.+---++A personal webhook forwards notifications created for your account. For a shared feed of project events, use a [project webhook](/core/integrations/outgoing-webhooks), which has a different payload.++## Connect your receiver++1. Open **Settings → Account → Notifications** and find **Webhook**.+2. Enter your receiver’s HTTP or HTTPS URL.+3. Enter a signing secret if your receiver will verify requests.+4. Enable the channel and choose **Connect webhook**.+5. Add an active workspace rule, enable the webhook channel, choose the projects to include, and save.++Choose the notification categories you want at the top of the page. The same preferences control your inbox and forwarding.++## Payload++Kaneo sends a JSON POST with these fields:++| Field | Contents |+| --- | --- |+| `notification` | ID, type, title, content, creation time, event data, resource ID, and resource type |+| `workspace` | Workspace ID and name |+| `project` | Project ID and name, or `null` |+| `task` | Task ID, title, and URL, or `null` |+| `user` | Your user ID, name, and email |++A notification needs a resolvable workspace context for external delivery. It must also pass the active workspace rule and project selection.++## Verify requests++When a signing secret is set, Kaneo sends `X-Kaneo-Signature`: the lowercase hexadecimal HMAC-SHA256 digest of the exact JSON body. Verify the raw body before parsing it, using a constant-time comparison. Use the notification ID to avoid processing the same notification twice.++The API needs `NOTIFICATION_SECRET_ENCRYPTION_KEY` to save the signing secret. Private receivers also need `KANEO_ALLOW_PRIVATE_WEBHOOK_DESTINATIONS`; see [server settings](/core/installation/environment-variables#notifications).++## Check and disconnect++Have a teammate trigger a notification for you in an included project. Inspect your receiver’s logs and compare it with the Kaneo inbox. A delivery failure does not remove the inbox item.++To rotate the secret, enter a replacement and save it, then update your receiver. An empty secret field retains the saved value. **Disconnect** removes the stored URL and secret. Review workspace rules when reconnecting.diff --git a/apps/docs/core/migrations/from-planka.mdx b/apps/docs/core/migrations/from-planka.mdxindex 3b1453822..bb44da7f8 100644--- a/apps/docs/core/migrations/from-planka.mdx+++ b/apps/docs/core/migrations/from-planka.mdx@@ -3,12 +3,10 @@ title: Migrating from PLANKAdescription: Move your PLANKA boards into Kaneo with the @kaneo/planka-import CLI, including lists, cards, labels, assignees, checklists and comments----PLANKA has no export feature, so there is no file to hand over. Instead,`@kaneo/planka-import` reads your boards directly from PLANKA's REST API andrecreates them in Kaneo through Kaneo's public API.-Nothing is written back to PLANKA, and your PLANKA credentials stay on your-machine: the CLI talks to both servers itself, so no third party sees them.+The CLI reads from PLANKA and writes directly to your Kaneo instance. It does not modify PLANKA or use an intermediary migration service.## Before you start@@ -17,9 +15,11 @@ You need:- A PLANKA account that can see the boards you want to move. If you sign inthrough SSO and have no password, create a PLANKA API key and use`--planka-api-key`.-- A Kaneo workspace, and an API key from **Settings → API keys**.+- A Kaneo workspace, and an API key from **Settings → Account → API Keys**.- Node.js 20 or newer.+Use a PLANKA administrator account if you want to preserve assignees. PLANKA hides other users’ email addresses from non-administrators, which prevents email matching.+Invite your team to the Kaneo workspace **before** importing. Assignees arematched by email address, so anyone who isn't a member yet will have their cardsimported unassigned.@@ -46,13 +46,12 @@ Planned import:## Run the import-When the plan looks right, add your Kaneo credentials and drop `--dry-run`:+When the plan looks right, set `KANEO_API_KEY` in your environment and drop `--dry-run`. The CLI reads the key from that variable:```bashnpx @kaneo/planka-import \--planka-url https://planka.example.com \--kaneo-url https://cloud.kaneo.app \- --kaneo-api-key kaneo_xxx \--workspace ws_123```@@ -65,7 +64,6 @@ To skip the prompts entirely, for example in a script:npx @kaneo/planka-import \--planka-url https://planka.example.com \--planka-user [email protected] \- --kaneo-api-key kaneo_xxx \--workspace ws_123 \--all --yes --report import-report.json```@@ -86,7 +84,7 @@ passing secrets on the command line, where they end up in your shell history.| Labels | Labels, with their original colors || Card members | Assignee, matched by email || Due date | Due date |-| Comments | Comments, prefixed with the original author and date |+| Comments | Comments, with the original author recorded separately and the original date added to the text |One Kaneo project is created per PLANKA **board**, because the board is whatholds the lists and cards. When a PLANKA project has more than one board, each@@ -102,9 +100,9 @@ resulting Kaneo project is named `Project - Board`.original PLANKA author is recorded on it and shown in Kaneo, the same wayimported GitHub comments are. This needs Kaneo 2.17.6 or newer; against olderinstances the comment still imports, just without the original author.-- **Priorities.** PLANKA has no priority field, so every task starts at+- **Priorities.** The importer sets every task to`no-priority`.-- **Custom fields, stopwatches, and card subscriptions.** No Kaneo equivalent.+- **Custom fields, stopwatches, and card subscriptions.** The importer does not transfer these. Kaneo supports custom fields and time entries, but you need to recreate that information yourself.## Troubleshooting@@ -118,7 +116,7 @@ recommended credential: it doesn't expire the way a copied session token does.**A board failed partway**: failures are isolated per board, so the rest stillimport and the summary names the one that failed. Delete the half-created Kaneo-project and re-run with `--project` to retry just that one.+project and run the importer interactively again, selecting only the failed board. The `--project` flag filters PLANKA projects, which can contain several boards.## Re-runningdiff --git a/apps/docs/core/operations/backups.mdx b/apps/docs/core/operations/backups.mdxnew file mode 100644index 000000000..86a03d83b--- /dev/null+++ b/apps/docs/core/operations/backups.mdx@@ -0,0 +1,123 @@+---+title: "Backups and recovery"+description: "Save the database, uploaded files, and configuration, then prove you can restore them."+---++A complete Kaneo backup has three parts:++| Part | What it contains |+| --- | --- |+| PostgreSQL | Accounts, workspaces, tasks, comments, settings, avatars, and attachment records |+| Object storage | The actual files attached to tasks and comments |+| Configuration | Compose files, environment files, proxy configuration, and the application image tag or digest |++Keep an encrypted copy away from the server. A backup on the same disk will not help if you lose that disk.++The commands below apply to the [Docker Compose setup](/core/installation/docker-compose). Run them from its directory. With a managed database or storage service, use the provider's backup tools as well.++## Make a consistent backup++Schedule a maintenance window and stop every Kaneo API instance that can write to this database. For the single-container setup:++```bash+docker compose stop kaneo+```++If uploads are configured, wait for outstanding signed upload URLs to expire before taking the storage snapshot. The default is five minutes; use your configured `S3_PRESIGN_TTL_SECONDS` if it differs.++Create a private backup directory and dump PostgreSQL:++```bash+umask 077+backup_dir="backups/$(date -u +%Y%m%dT%H%M%SZ)"+mkdir -p "$backup_dir"+docker compose exec -T postgres sh -c \+ 'pg_dump -U "$POSTGRES_USER" -d "$POSTGRES_DB" --format=custom' \+ > "$backup_dir/database.dump"+```++Check the command's exit status. Do not keep going after a failed dump. Check that the archive can be read:++```bash+docker compose exec -T postgres pg_restore --list \+ < "$backup_dir/database.dump" > "$backup_dir/database.contents"+cp compose.yml .env "$backup_dir/"+docker compose images > "$backup_dir/images.txt"+```++Also copy any `silo.env`, proxy files, Compose override files, and secret references needed to recreate your setup. Preserve `AUTH_SECRET` and, when used, `NOTIFICATION_SECRET_ENCRYPTION_KEY`; the latter is needed to decrypt personal notification credentials. Use your actual Compose filename if it differs.++The custom archive is created by [pg_dump](https://www.postgresql.org/docs/16/app-pgdump.html). Listing its contents checks the archive structure; a successful restore is the stronger check.++## Save uploaded files++Keep Kaneo stopped while saving storage, so the database records and files stay aligned.++For the single-node Silo service in this guide, copy its complete data directory while it is stopped. `docker compose cp` can copy from a stopped container. Include the hidden metadata files:++```bash+docker compose stop silo+mkdir -p "$backup_dir/silo-data"+docker compose cp silo:/data/. "$backup_dir/silo-data/"+docker compose start silo+```++Check the copy succeeded before restarting Kaneo. For large volumes, a consistent filesystem snapshot may be more practical. Record the volume name and snapshot identifier beside the database dump. See the [Compose copy reference](https://docs.docker.com/reference/cli/docker/compose/cp/).++For managed object storage, use a recoverable bucket snapshot or versioned backup and record its recovery point. Make sure your retention policy will preserve objects deleted after the backup. Store any encryption keys and bucket policies needed for recovery separately and securely.++Once the database, storage, and configuration copies are complete:++```bash+docker compose start kaneo+```++## Test the database restore in isolation++Use a separate directory and Compose project with a new volume. Do not point this test at the live database. Save this as `compose.restore.yml`:++```yaml+services:+ postgres:+ image: postgres:16-alpine+ environment:+ POSTGRES_USER: kaneo+ POSTGRES_DB: kaneo+ POSTGRES_PASSWORD: ${RESTORE_DB_PASSWORD:?Set a temporary restore password}+ volumes:+ - restore_data:/var/lib/postgresql/data+ healthcheck:+ test: ["CMD-SHELL", "pg_isready -U kaneo -d kaneo"]+ interval: 5s+ timeout: 5s+ retries: 20+volumes:+ restore_data:+```++Start the isolated database, then restore the selected dump. Replace the path with your actual backup:++```bash+export RESTORE_DB_PASSWORD="$(openssl rand -hex 32)"+docker compose -p kaneo-restore -f compose.restore.yml up -d --wait+docker compose -p kaneo-restore -f compose.restore.yml exec -T postgres \+ pg_restore --username=kaneo --dbname=kaneo \+ --no-owner --no-privileges --exit-on-error \+ < /absolute/path/to/backup/database.dump+```++Use a new, empty recovery volume for each rehearsal. Do not run the restore repeatedly against a partially restored database. [pg_restore](https://www.postgresql.org/docs/16/app-pgrestore.html) stops at the first error with these flags.++## Recover the whole instance++1. Restore PostgreSQL into an empty recovery database.+2. Restore the matching storage backup, preserving bucket names, object keys, and required key material. For a fresh single-node Silo recovery volume, create the stopped container with `docker compose create silo`, copy the saved `silo-data/.` into `silo:/data/` with `docker compose cp`, check ownership matches the container's runtime user, then start it. Do not overlay a recovery copy onto a live storage volume.+3. Deploy the Kaneo image recorded with the backup. Restore its `AUTH_SECRET` and other required settings.+4. Set the recovery instance's URLs, database connection, and storage endpoint to the recovery services.+5. Before starting it, isolate outbound email, webhooks, and repository integrations at the network level. Integration credentials can be present in the restored database, not only in `.env`.+6. Sign in, compare several projects and tasks with the expected backup state, and open existing attachments. Try a new task and file upload.+7. Only after those checks, plan the cutover and restore the intended URLs and delivery channels.++A restore loses changes made after the selected recovery point. Tell your team which point you are restoring before bringing it back online.++Schedule backups at a frequency that matches how much work you can afford to lose. Rehearse recovery after major deployment changes, and keep a record of the last successful restore.diff --git a/apps/docs/core/operations/troubleshooting.mdx b/apps/docs/core/operations/troubleshooting.mdxnew file mode 100644index 000000000..a431aec90--- /dev/null+++ b/apps/docs/core/operations/troubleshooting.mdx@@ -0,0 +1,67 @@+---+title: "Troubleshooting"+description: "Start with the symptom and check the part of the setup that controls it."+---++Run Compose commands from the directory containing your deployment file. The service names below match the bundled setup: `kaneo` and `postgres`.++## Kaneo will not start++```bash+docker compose ps+docker compose logs --tail=100 kaneo postgres+```++If PostgreSQL is unhealthy, check its logs and available disk space. If Kaneo cannot connect, check the database hostname and credentials. Inside Compose, the default hostname is `postgres`, not `localhost`.++Changing `POSTGRES_PASSWORD` in `.env` does not change the password of an already initialized PostgreSQL user. Update the database credential deliberately and keep the application configuration in sync. Do not delete the volume to resolve a password mismatch.++## The page opens, but requests or sign-in fail++Check `KANEO_CLIENT_URL` against the URL in your browser. In the bundled deployment, leave `KANEO_API_URL` unset so it becomes the client URL plus `/api`.++A browser on another computer cannot use your server's `localhost` URL. Use the public hostname and HTTPS, then recreate the container:++```bash+docker compose up -d --force-recreate kaneo+```++Check the browser's Network panel for the failed request and its status. A `401` usually calls for checking authentication; a `403` calls for checking workspace access or the required permission.++## Changes only appear after refreshing++Check that the reverse proxy forwards WebSocket upgrades. Use the [Nginx example](/core/reverse-proxy/nginx) and check for failed WebSocket requests in browser developer tools.++With multiple API instances, configure [Redis](/core/installation/environment-variables#redis) for shared realtime delivery. A single API instance does not need it.++## Uploads fail++Check these in order:++1. **Configuration:** the bucket exists and the `S3_*` values are set on the API.+2. **Reachability:** the browser and API both resolve and reach `S3_ENDPOINT`. Docker-only names do not work for browser uploads.+3. **HTTPS:** an HTTPS Kaneo page must not upload to an HTTP storage endpoint.+4. **CORS:** storage allows the exact Kaneo origin, PUT, and the requested headers. For Silo, a bucket-specific policy overrides global CORS.+5. **Permissions:** the credential can put, read, and delete objects in the bucket.+6. **Limits:** the file fits Kaneo's upload limit and the proxy's body limit.+7. **Signature:** the proxy preserves the host, path, query string, and signed headers. Check the storage server's clock too.++An upload that reaches storage but cannot be finalized may have the wrong size or content type. Keep signed-header validation enabled and check the storage response.++Use the [Silo guide](/core/installation/silo) for a complete self-hosted setup.++## An invitation email does not arrive++Check the pending invitation in **Members**. Copy its link and share it directly if email is not configured. If SMTP is configured but delivery fails, check the API logs and your mail provider's delivery logs.++For SMTP on port 587, use `SMTP_SECURE=false` with STARTTLS. For implicit TLS, commonly on port 465, use `SMTP_SECURE=true`. Follow your provider's settings and the [SMTP reference](/core/installation/environment-variables#smtp-configuration).++## Someone cannot see or change a project++Check the selected workspace, their membership, and their role. Being able to read a task does not imply permission to assign or delete it. See [Members and roles](/core/functional/collaborate-with-team).++## Ask for help++Open a [GitHub issue](https://github.com/usekaneo/kaneo/issues) with the Kaneo version, deployment method, steps to reproduce, expected result, and the relevant error. Include a screenshot when it helps explain the problem.++Remove passwords, tokens, connection strings, invitation links, and private task data from logs or screenshots before sharing them. Do not post your `.env` file.diff --git a/apps/docs/core/operations/upgrades.mdx b/apps/docs/core/operations/upgrades.mdxnew file mode 100644index 000000000..ce9571e35--- /dev/null+++ b/apps/docs/core/operations/upgrades.mdx@@ -0,0 +1,50 @@+---+title: "Upgrade Kaneo"+description: "Choose a release, protect your data, and check the result."+---++Kaneo runs database migrations when the API starts. An upgrade can change your database as well as the application, so prepare a recovery point before changing the image.++## Before you upgrade++1. Read the [release notes](https://github.com/usekaneo/kaneo/releases) between your current and target versions.+2. Record the current image tag or digest and keep a copy of your Compose file and environment files.+3. Create a [database and file backup](/core/operations/backups), and check that you can restore it.+4. Choose a short maintenance window. Try the new release against a restored copy first when the change is substantial.++Do not change the PostgreSQL major version as part of an ordinary Kaneo image update. A database major upgrade needs its own migration procedure.++## Docker Compose++In the Compose setup from this guide, set `KANEO_IMAGE_TAG` in `.env` to the release you chose. If your Compose file hardcodes the image tag, edit that instead. Pulling an image does not restart the running container.++```bash+docker compose pull kaneo+docker compose up -d kaneo+docker compose ps+docker compose logs --tail=100 kaneo+```++## drim++Run `drim upgrade` from the deployment directory. It pulls the images selected by your existing Compose file. If those use `latest`, that means the newest published images. Review the file before running it.++Older two-container deployments need the [layout migration](/core/installation/drim-migration); upgrading images does not rewrite their Compose file.++## Check the result++- Request `/api/health` and confirm the container becomes healthy.+- Sign in, open an existing project, and create a test task.+- Open the same project in another browser session and check a status change appears.+- Upload and reopen an attachment if storage is configured.+- Check email and the integrations your team uses.++Keep the backup until you are satisfied with the result.++## If the upgrade fails++Capture the failing container logs and stop the new application container with `docker compose stop kaneo` while you investigate.++Do not assume an old image can read a newly migrated database. Unless the release explicitly supports that downgrade, recover using the previous application image plus its matching database and file backup. Follow [Backups and recovery](/core/operations/backups), and account for any work created since the backup.++Never use `docker compose down -v` as an upgrade or troubleshooting step. It removes the named data volumes.diff --git a/apps/docs/core/reverse-proxy/nginx.mdx b/apps/docs/core/reverse-proxy/nginx.mdxindex 724126a0a..53a3a5305 100644--- a/apps/docs/core/reverse-proxy/nginx.mdx+++ b/apps/docs/core/reverse-proxy/nginx.mdx@@ -1,78 +1,109 @@----title: Nginx-description: Nginx is a web server that can be used as a reverse proxy.+title: "Nginx and HTTPS"+description: "Serve the bundled Kaneo container on one domain with working realtime updates."----## Overview+This example uses Nginx installed on the same host as the [Docker Compose deployment](/core/installation/docker-compose). The Kaneo container is available only at `127.0.0.1:5173`.-This guide explains how to deploy Kaneo using Nginx as a reverse proxy. This setup is ideal for production environments where you want to expose Kaneo through a domain name with HTTPS.+You need a domain pointing at the server and a valid TLS certificate. The paths below assume a certificate for `kaneo.example.com` already exists. Obtain one with your certificate manager before enabling the HTTPS server block.-## Prerequisites+## Configure one public origin-- A domain name-- A SSL certificate-- A Nginx web server+Set this in Kaneo's `.env`:-## Installation+```env+KANEO_CLIENT_URL=https://kaneo.example.com+```++Leave `KANEO_API_URL` unset for the bundled image. It serves the web app and `/api` through the same public origin.++```bash+docker compose up -d --force-recreate kaneo+```++## Trust the proxy chain++Configure `TRUSTED_PROXIES` for this host-Nginx setup before serving traffic. Requests pass through host Nginx, Docker's published port, and the bundled Nginx before reaching the API. The API trusts loopback by default, but the bundled Nginx also appends its Docker-side peer address. Without trusting that hop, visitors can share the gateway address in session records and IP-based rate limits.++Find the gateway for the Kaneo container's network:++```bash+docker inspect "$(docker compose ps -q kaneo)" --format '{{range $name, $network := .NetworkSettings.Networks}}{{$name}} gateway={{$network.Gateway}}{{println}}{{end}}'+```++On a standard Linux Docker bridge, the host proxy reaches the container through that gateway. If the output shows `172.19.0.1`, add this to `.env`, replacing the example address with your actual gateway:-The first step is to make sure nginx is installed and running.+```env+TRUSTED_PROXIES=127.0.0.0/8,::1/128,172.19.0.1/32+```++Keep loopback in the list because the bundled Nginx connects to the API locally. Trust only the gateway or proxy addresses you control, not every private network. If Docker uses a different network mode or forwarding layer, confirm the peer address in the bundled Nginx access logs and trust that specific hop instead. Recheck this setting if you recreate the Docker network.++Apply the setting:```bash-sudo apt update-sudo apt install nginx+docker compose up -d --force-recreate kaneo```-## Configuration+## Configure Nginx-The next step is to configure Nginx to proxy requests to the Kaneo services. We will create two servers, one for the web application and one for the API.+Save this in your Nginx site's configuration. The `map` belongs in the `http` context, outside the `server` blocks; on a standard Debian or Ubuntu installation, `sites-enabled` is included there.-1. Create a new file in the `/etc/nginx/sites-available/kaneo.conf` directory.+```nginx+map $http_upgrade $kaneo_connection_upgrade {+ default upgrade;+ '' close;+}-```nginx title="kaneo.conf"server {- listen 80;- server_name kaneo.your-domain.com;-- location / {- proxy_pass http://localhost:5173;- proxy_set_header Host $host;- proxy_set_header X-Real-IP $remote_addr;- proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;- }+ listen 80;+ server_name kaneo.example.com;+ return 301 https://$host$request_uri;}-+server {- listen 80;- server_name kaneo-api.your-domain.com;-- location / {- proxy_pass http://localhost:1337;- proxy_set_header Host $host;- proxy_set_header X-Real-IP $remote_addr;- proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;- }+ listen 443 ssl;+ server_name kaneo.example.com;+ ssl_certificate /etc/letsencrypt/live/kaneo.example.com/fullchain.pem;+ ssl_certificate_key /etc/letsencrypt/live/kaneo.example.com/privkey.pem;++ location / {+ proxy_pass http://127.0.0.1:5173;+ proxy_http_version 1.1;+ proxy_set_header Host $host;+ proxy_set_header X-Forwarded-Proto $scheme;+ proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;+ proxy_set_header Upgrade $http_upgrade;+ proxy_set_header Connection $kaneo_connection_upgrade;+ proxy_read_timeout 300s;+ proxy_buffering off;+ }}```-2. Enable the configuration by creating a symlink to the `sites-enabled` directory.--```bash-sudo ln -s /etc/nginx/sites-available/kaneo.conf /etc/nginx/sites-enabled/-```+The upgrade headers follow [Nginx's WebSocket guidance](https://nginx.org/en/docs/http/websocket.html). They allow live task updates through the proxy. Disabling response buffering also lets streaming MCP responses arrive promptly.-3. Test the configuration.+Enable the site using your distribution's normal procedure, then validate and reload:```bashsudo nginx -t+sudo systemctl reload nginx```-4. Restart Nginx to apply the changes.+## Check the public URL```bash-sudo systemctl restart nginx+curl --fail https://kaneo.example.com/api/health```-## Key points+Sign in and open a project in two browser sessions. Change a task in one and confirm the other receives the update without a refresh.++## Other network layouts++If Nginx runs in another container, `127.0.0.1` refers to that proxy container. Put it on the same Docker network as Kaneo and use `http://kaneo:5173` as the upstream.++Configure [`TRUSTED_PROXIES`](/core/installation/environment-variables#proxies) for this different proxy chain so client addresses remain correct. Trust only the proxy addresses or a dedicated proxy subnet.++If you deliberately host the API and web app separately, set their public URLs explicitly and configure allowed origins. The one-domain setup above does not require exposing port 1337.-- This configuration is for a single server, if you want to use a load balancer, you need to configure it accordingly.-- This configuration is for a single domain, if you want to use a subdomain, you need to configure it accordingly.\ No newline at end of file+For uploads, give [Silo](/core/installation/silo) its own HTTPS hostname pointing to its S3 API.diff --git a/apps/docs/core/social-providers/custom-oauth.mdx b/apps/docs/core/social-providers/custom-oauth.mdxindex d4940ecdd..f69e72cb8 100644--- a/apps/docs/core/social-providers/custom-oauth.mdx+++ b/apps/docs/core/social-providers/custom-oauth.mdx@@ -5,23 +5,27 @@ description: Configure Kaneo with your custom OpenID Connect (OIDC) provider.## Overview-Kaneo supports custom OAuth 2.0 and OpenID Connect (OIDC) providers, allowing you to integrate with any standards-compliant identity provider such as Keycloak, Auth0, Okta, Azure AD, or self-hosted solutions like Pocket ID.+Kaneo supports custom OAuth 2.0 and OpenID Connect (OIDC) providers, allowing you to connect an identity provider such as Keycloak, Auth0, Okta, Azure AD, or self-hosted solutions like Pocket ID.++Use the public callback URL shown below. If `KANEO_API_URL` already ends in `/api`, do not add another `/api` segment.## ConfigurationTo configure a custom OAuth/OIDC provider, you need to set the following environment variables in your `.env` file:-### Required Variables+### Provider settings| Variable | Description | Example ||----------|-------------|---------|| `CUSTOM_OAUTH_CLIENT_ID` | OAuth client ID from your provider | `2b1ae9df-8d25-4dbc-8cc8-f8f2c1ef6bd0` |-| `CUSTOM_OAUTH_CLIENT_SECRET` | OAuth client secret from your provider | `NzDjplDsdQyP062wTmkZ8kyiaziBag0N` |+| `CUSTOM_OAUTH_CLIENT_SECRET` | OAuth client secret from your provider | `your-client-secret` || `CUSTOM_OAUTH_AUTHORIZATION_URL` | Authorization endpoint URL | `https://id.example.com/authorize` || `CUSTOM_OAUTH_TOKEN_URL` | Token exchange endpoint URL | `https://id.example.com/api/oidc/token` || `CUSTOM_OAUTH_USER_INFO_URL` | User info endpoint URL | `https://id.example.com/api/oidc/userinfo` |-### Optional Variables+If you use a discovery URL, the provider can supply the authorization, token, and user-info endpoints. You still need the client ID and secret.++### Optional settings| Variable | Description | Default ||----------|-------------|---------|@@ -29,7 +33,7 @@ To configure a custom OAuth/OIDC provider, you need to set the following environ| `CUSTOM_OAUTH_SCOPES` | Comma-separated list of OAuth scopes | `profile,email` || `CUSTOM_OAUTH_RESPONSE_TYPE` | OAuth response type | `code` || `CUSTOM_AUTH_PKCE` | Enable/disable PKCE (Proof Key for Code Exchange) | `true` |-| `CUSTOM_OAUTH_LOGOUT_URL` | Logout endpoint URL (optional) | `https://id.example.com/api/oidc/logout` |+| `CUSTOM_OAUTH_LOGOUT_URL` | Provider logout endpoint, if needed | Unset || `CUSTOM_OAUTH_AUTO_LOGIN` | Auto-redirect to the custom OAuth provider, bypassing the login page | `false` |## Setup Steps@@ -40,7 +44,7 @@ First, create an OAuth 2.0 or OIDC application in your identity provider:1. Log in to your identity provider's admin console2. Create a new OAuth 2.0 or OIDC application-3. Set the redirect URI to: `{KANEO_API_URL}/api/auth/oauth2/callback/custom`+3. Set the redirect URI to: `https://kaneo.example.com/api/auth/oauth2/callback/custom`- Example: `https://api.kaneo.example.com/api/auth/oauth2/callback/custom`4. Copy the client ID and client secret5. Note the authorization, token, and userinfo endpoint URLs@@ -64,17 +68,16 @@ CUSTOM_OAUTH_DISCOVERY_URL=https://your-idp.com/.well-known/openid-configuration# Optional: Customize scopesCUSTOM_OAUTH_SCOPES=profile,email,openid-# Optional: Disable PKCE if your provider doesn't support it-CUSTOM_AUTH_PKCE=false+# Keep PKCE enabled when your provider supports it+CUSTOM_AUTH_PKCE=true```-### 3. Restart Services+### 3. Apply the configuration-After updating the environment variables, restart your Kaneo services:+After updating the environment variables, recreate the bundled application container:```bash-docker compose down-docker compose up -d+docker compose up -d --force-recreate kaneo```## Example Configurations@@ -83,12 +86,12 @@ docker compose up -d```bashCUSTOM_OAUTH_CLIENT_ID=2b1ae9df-8d25-4dbc-8cc8-f8f2c1ef6bd0-CUSTOM_OAUTH_CLIENT_SECRET=NzDjplDsdQyP062wTmkZ8kyiaziBag0N-CUSTOM_OAUTH_AUTHORIZATION_URL=https://4c6332d2.demo.pocket-id.org/authorize-CUSTOM_OAUTH_TOKEN_URL=https://4c6332d2.demo.pocket-id.org/api/oidc/token-CUSTOM_OAUTH_USER_INFO_URL=https://4c6332d2.demo.pocket-id.org/api/oidc/userinfo-CUSTOM_OAUTH_DISCOVERY_URL=https://4c6332d2.demo.pocket-id.org/.well-known/openid-configuration-CUSTOM_OAUTH_SCOPES=profile,email+CUSTOM_OAUTH_CLIENT_SECRET=your-client-secret+CUSTOM_OAUTH_AUTHORIZATION_URL=https://id.example.com/authorize+CUSTOM_OAUTH_TOKEN_URL=https://id.example.com/api/oidc/token+CUSTOM_OAUTH_USER_INFO_URL=https://id.example.com/api/oidc/userinfo+CUSTOM_OAUTH_DISCOVERY_URL=https://id.example.com/.well-known/openid-configuration+CUSTOM_OAUTH_SCOPES=openid,profile,email```### Keycloak@@ -124,26 +127,26 @@ If you want to bypass the login page entirely and automatically redirect users tCUSTOM_OAUTH_AUTO_LOGIN=true```-When enabled, users visiting the sign-in page will be immediately redirected to your custom OAuth provider without seeing the Kaneo login page. This is ideal for organizations that use a single identity provider for all authentication.+When enabled, Kaneo redirects visitors to the custom provider. If CAPTCHA is configured, it first shows the sign-in page so the visitor can complete the challenge. Verify existing local accounts before enabling this option; see account linking below.## Troubleshooting### "Invalid code verifier" Error-This error typically indicates a PKCE configuration issue. Try setting:+Check that the provider and Kaneo both use PKCE and that the callback returns to the same public instance URL. Keep PKCE enabled for providers that support it:```bash-CUSTOM_AUTH_PKCE=false+CUSTOM_AUTH_PKCE=true```-Some OAuth providers don't support PKCE or have it disabled by default.+Only set `CUSTOM_AUTH_PKCE=false` when your provider's documentation requires a flow without PKCE.### Missing User InformationEnsure your OAuth scopes include at least `profile` and `email`:```bash-CUSTOM_OAUTH_SCOPES=profile,email+CUSTOM_OAUTH_SCOPES=openid,profile,email```Some providers require `openid` scope as well:@@ -157,10 +160,10 @@ CUSTOM_OAUTH_SCOPES=openid,profile,emailVerify that your redirect URI in the OAuth provider matches exactly:```-{KANEO_API_URL}/api/auth/oauth2/callback/custom+https://kaneo.example.com/api/auth/oauth2/callback/custom```-For example, if `KANEO_API_URL=https://api.kaneo.example.com`, the redirect URI should be:+For a separately hosted API at `https://api.kaneo.example.com`, use:```https://api.kaneo.example.com/api/auth/oauth2/callback/custom@@ -182,7 +185,7 @@ When a user signs in with this provider using an email that already belongs to aFor safety, Kaneo only links to an existing local account if that account's email has already been verified. This prevents someone from pre-registering another person's email with a password account and retaining access after the real owner signs in through OIDC. If your instance allows password registration alongside OIDC, consider setting `DISABLE_PASSWORD_REGISTRATION=true` (which also blocks new OTP, magic-link and guest accounts) or requiring email verification for password users to avoid account-linking surprises.-On existing installations, local accounts created before this requirement may still have an unverified email. Those users will receive `error=account_not_linked` until they verify the local account. Before enforcing SSO-only access, keep the login form available so affected users can sign in with an email OTP or magic link, which verifies the email. If users are already locked out, temporarily set `DISABLE_LOGIN_FORM=false` and `CUSTOM_OAUTH_AUTO_LOGIN=false`, restart Kaneo, and have them complete an email sign-in before enabling SSO-only access again.+On existing installations, local accounts created before this requirement may still have an unverified email. Those users will receive `error=account_not_linked` until they verify the local account. Before enforcing SSO-only access, keep the login form available so affected users can sign in with an email OTP or magic link, which verifies the email. If users are already locked out, temporarily set `DISABLE_LOGIN_FORM=false` and `CUSTOM_OAUTH_AUTO_LOGIN=false`, recreate the Kaneo container, and have them complete an email sign-in before enabling SSO-only access again.## Security Notesdiff --git a/apps/docs/core/social-providers/discord.mdx b/apps/docs/core/social-providers/discord.mdxindex 641e0d79a..cb7936925 100644--- a/apps/docs/core/social-providers/discord.mdx+++ b/apps/docs/core/social-providers/discord.mdx@@ -1,24 +1,45 @@----title: Discord-description: Discord is a social provider for Kaneo.+title: "Sign in with Discord"+description: "Let people use their Discord account to sign in to Kaneo."----## Overview+This sets up sign-in for your instance. It does not connect a repository or send project notifications.-Discord is a social provider for Kaneo. It allows users to sign in to Kaneo using their Discord account.+## Register the application-## Configuration+Open the [Discord developer console](https://discord.com/developers/applications). Create an application, open **OAuth2**, and add the address below under redirects. Copy the OAuth client ID and secret.-1. Go to the [Discord Developer Portal](https://discord.com/developers/applications).-2. Create a new application.-3. Navigate to the "OAuth2" section in the left sidebar.-4. Add a redirect URI: `KANEO_API_URL/api/auth/callback/discord.-5. Copy the client ID and client secret from the OAuth2 page.-6. Set the `DISCORD_CLIENT_ID` and `DISCORD_CLIENT_SECRET` environment variables.+For a bundled Kaneo deployment at `https://kaneo.example.com`, the callback is:-For more information on what your `KANEO_API_URL` is, see the [Environment variables](/core/installation/environment-variables#discord-sso) page.+```text+https://kaneo.example.com/api/auth/callback/discord+```-## Usage+Use your own hostname. If the API is hosted separately, use its public origin instead. The callback path is `/api/auth/callback/discord`; do not append a second `/api` when your API URL already includes it.-Once you have configured the social provider, you can sign in to Kaneo using your Discord account.+For provider-specific options, see the [official OAuth guide](https://docs.discord.com/developers/topics/oauth2).+## Configure Kaneo++Add the values from the provider to your server's `.env`:++```env+DISCORD_CLIENT_ID=your-client-id+DISCORD_CLIENT_SECRET=your-client-secret+```++Apply the change to the bundled deployment:++```bash+docker compose up -d --force-recreate kaneo+```++## Test sign-in++Open Kaneo in a private browser window and choose the Discord sign-in option. Complete authorization and confirm you return to Kaneo.++If the provider reports a redirect mismatch, compare the full URL, including the scheme, hostname, port, and path. If sign-in succeeds but joining a workspace fails, check the invitation email and instance registration settings.++## Turn it off++Remove the two environment variables and recreate Kaneo. Make sure people have another way to sign in before disabling the provider. Review [access settings](/core/installation/environment-variables#access-control) before enforcing SSO-only access.diff --git a/apps/docs/core/social-providers/github.mdx b/apps/docs/core/social-providers/github.mdxindex 184d30440..638cd5ff4 100644--- a/apps/docs/core/social-providers/github.mdx+++ b/apps/docs/core/social-providers/github.mdx@@ -1,22 +1,45 @@----title: GitHub-description: GitHub is a social provider for Kaneo.+title: "Sign in with GitHub"+description: "Let people use their GitHub account to sign in to Kaneo."----## Overview+This sets up sign-in for your instance. It does not connect a repository or send project notifications.-GitHub is a social provider for Kaneo. It allows users to sign in to Kaneo using their GitHub account.+## Register the application-## Configuration+Open the [GitHub developer console](https://github.com/settings/developers/). Create an OAuth App. Set its homepage to your Kaneo URL and its authorization callback URL to the address below.-1. Go to the [GitHub Developer Settings](https://github.com/settings/developers/).-2. Create a new OAuth app.-3. Set the redirect URI to `KANEO_API_URL/api/auth/callback/github`.-4. Copy the client ID and client secret.-5. Set `GITHUB_OAUTH_CLIENT_ID` and `GITHUB_OAUTH_CLIENT_SECRET` (or the legacy `GITHUB_CLIENT_ID` and `GITHUB_CLIENT_SECRET` if you prefer).+For a bundled Kaneo deployment at `https://kaneo.example.com`, the callback is:-For more information on what your `KANEO_API_URL` is, see the [Environment variables](/core/installation/environment-variables#github-sso) page.+```text+https://kaneo.example.com/api/auth/callback/github+```-## Usage+Use your own hostname. If the API is hosted separately, use its public origin instead. The callback path is `/api/auth/callback/github`; do not append a second `/api` when your API URL already includes it.-Once you have configured the social provider, you can sign in to Kaneo using your GitHub account.\ No newline at end of file+For provider-specific options, see the [official OAuth guide](https://docs.github.com/en/apps/oauth-apps/building-oauth-apps/creating-an-oauth-app).++## Configure Kaneo++Add the values from the provider to your server's `.env`:++```env+GITHUB_OAUTH_CLIENT_ID=your-client-id+GITHUB_OAUTH_CLIENT_SECRET=your-client-secret+```++Apply the change to the bundled deployment:++```bash+docker compose up -d --force-recreate kaneo+```++## Test sign-in++Open Kaneo in a private browser window and choose the GitHub sign-in option. Complete authorization and confirm you return to Kaneo.++If the provider reports a redirect mismatch, compare the full URL, including the scheme, hostname, port, and path. If sign-in succeeds but joining a workspace fails, check the invitation email and instance registration settings.++## Turn it off++Remove the two environment variables and recreate Kaneo. Make sure people have another way to sign in before disabling the provider. Review [access settings](/core/installation/environment-variables#access-control) before enforcing SSO-only access.diff --git a/apps/docs/core/social-providers/google.mdx b/apps/docs/core/social-providers/google.mdxindex e1e484137..2a255adeb 100644--- a/apps/docs/core/social-providers/google.mdx+++ b/apps/docs/core/social-providers/google.mdx@@ -1,25 +1,45 @@----title: Google-description: Google is a social provider for Kaneo.+title: "Sign in with Google"+description: "Let people use their Google account to sign in to Kaneo."----## Overview+This sets up sign-in for your instance. It does not connect a repository or send project notifications.-Google is a social provider for Kaneo. It allows users to sign in to Kaneo using their Google account.+## Register the application-## Configuration+Open the [Google developer console](https://console.cloud.google.com/). Choose a Google Cloud project, configure its OAuth consent screen and audience, and create an OAuth client of type **Web application**. Add the address below as an authorized redirect URI. If the app is in testing, add the people who will test it to the allowed test users.-1. Go to the [Google Cloud Console](https://console.cloud.google.com/).-2. Create a new project.-3. Enable the Google Sign In API.-4. Create a new OAuth client ID.-5. Set the redirect URI to `KANEO_API_URL/api/auth/callback/google`.-6. Copy the client ID and client secret.-7. Set the `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET` environment variables.+For a bundled Kaneo deployment at `https://kaneo.example.com`, the callback is:+```text+https://kaneo.example.com/api/auth/callback/google+```-For more information on what your `KANEO_API_URL` is, see the [Environment variables](/core/installation/environment-variables#google-sso--integration) page.+Use your own hostname. If the API is hosted separately, use its public origin instead. The callback path is `/api/auth/callback/google`; do not append a second `/api` when your API URL already includes it.-## Usage+For provider-specific options, see the [official OAuth guide](https://developers.google.com/identity/protocols/oauth2/web-server).-Once you have configured the social provider, you can sign in to Kaneo using your Google account.\ No newline at end of file+## Configure Kaneo++Add the values from the provider to your server's `.env`:++```env+GOOGLE_CLIENT_ID=your-client-id+GOOGLE_CLIENT_SECRET=your-client-secret+```++Apply the change to the bundled deployment:++```bash+docker compose up -d --force-recreate kaneo+```++## Test sign-in++Open Kaneo in a private browser window and choose the Google sign-in option. Complete authorization and confirm you return to Kaneo.++If the provider reports a redirect mismatch, compare the full URL, including the scheme, hostname, port, and path. If sign-in succeeds but joining a workspace fails, check the invitation email and instance registration settings.++## Turn it off++Remove the two environment variables and recreate Kaneo. Make sure people have another way to sign in before disabling the provider. Review [access settings](/core/installation/environment-variables#access-control) before enforcing SSO-only access.diff --git a/apps/docs/docs.json b/apps/docs/docs.jsonindex f34b1e108..ecc75a382 100644--- a/apps/docs/docs.json+++ b/apps/docs/docs.json@@ -40,93 +40,145 @@"navigation": {"tabs": [{- "tab": "Guides",+ "tab": "Using Kaneo","groups": [{- "group": "Overview",- "pages": ["index", "core/index"]+ "group": "Start here",+ "pages": [+ "index",+ "core/index",+ "core/functional/index",+ "core/functional/create-workspace-and-project"+ ]},{- "group": "Functional Guides",+ "group": "Work with tasks","pages": [- "core/functional/index",- "core/functional/create-workspace-and-project","core/functional/plan-and-execute-tasks","core/functional/backlog-planning",- "core/functional/collaborate-with-team",+ "core/functional/calendar-and-gantt","core/functional/configure-workflows",- "core/functional/account-notifications",- "core/functional/manage-your-account",- "core/functional/personalize-your-workspace","core/functional/manage-workspace-labels"]},{- "group": "Installation",+ "group": "Your team and account",+ "pages": [+ "core/functional/collaborate-with-team",+ "core/functional/account-notifications",+ "core/functional/personalize-your-workspace",+ "core/functional/manage-your-account"+ ]+ }+ ]+ },+ {+ "tab": "Self-hosting",+ "groups": [+ {+ "group": "Install","pages": ["core/installation/index",- "core/installation/drim",- "core/installation/drim-migration","core/installation/docker-compose",+ "core/installation/drim",+ "core/deployments/coolify",+ "core/deployments/railway"+ ]+ },+ {+ "group": "Configure",+ "pages": [+ "core/reverse-proxy/nginx","core/installation/object-storage-and-image-uploads",+ "core/installation/silo","core/installation/storage-backends",- "core/installation/environment-variables",- "core/installation/start-services"+ "core/installation/environment-variables"]},{- "group": "GitHub Integration",+ "group": "Sign-in providers","pages": [- "core/integrations/github/setup",- "core/integrations/github/configuration",- "core/integrations/github/troubleshooting"+ "core/social-providers/github",+ "core/social-providers/google",+ "core/social-providers/discord",+ "core/social-providers/custom-oauth"]},{- "group": "Gitea Integration",- "pages": ["core/integrations/gitea/setup"]+ "group": "Keep it running",+ "pages": [+ "core/operations/backups",+ "core/operations/upgrades",+ "core/operations/troubleshooting"+ ]},{- "group": "GitLab Integration",- "pages": ["core/integrations/gitlab/setup"]+ "group": "Move to Kaneo",+ "pages": [+ "core/migrations/from-planka",+ "core/installation/migration",+ "core/installation/drim-migration"+ ]+ }+ ]+ },+ {+ "tab": "Integrations",+ "groups": [+ {+ "group": "Overview",+ "pages": ["core/integrations/index"]},{- "group": "Integrations",+ "group": "Repositories",+ "pages": [+ "core/integrations/github/setup",+ "core/integrations/github/configuration",+ "core/integrations/github/troubleshooting",+ "core/integrations/gitea/setup",+ "core/integrations/gitlab/setup"+ ]+ },+ {+ "group": "Team updates","pages": [- "core/integrations/mcp",- "core/integrations/mcp-stateless",- "core/integrations/discord","core/integrations/slack",+ "core/integrations/discord",+ "core/integrations/mattermost","core/integrations/telegram","core/integrations/outgoing-webhooks"]},{- "group": "Authentication Providers",+ "group": "Personal notifications","pages": [- "core/social-providers/github",- "core/social-providers/google",- "core/social-providers/discord",- "core/social-providers/custom-oauth"+ "core/integrations/ntfy",+ "core/integrations/gotify",+ "core/integrations/personal-webhooks"]},{- "group": "Deployment & Operations",+ "group": "AI assistants",+ "pages": ["core/integrations/mcp"]+ }+ ]+ },+ {+ "tab": "Developers",+ "groups": [+ {+ "group": "Start building","pages": [- "core/reverse-proxy/nginx",- "core/deployments/railway",- "core/deployments/coolify"+ "api-reference/introduction",+ "api-reference/authentication",+ "core/integrations/mcp-stateless"]},{- "group": "Migration",- "pages": ["core/migrations/from-planka"]+ "group": "Endpoint reference",+ "openapi": "openapi.json"}]- },- {- "tab": "API Reference",- "openapi": "openapi.json"}],"global": {@@ -154,7 +206,7 @@"primary": {"type": "button","label": "Open Kaneo",- "href": "https://kaneo.app"+ "href": "https://cloud.kaneo.app"}},"contextual": {diff --git a/apps/docs/images/product/README.md b/apps/docs/images/product/README.mdnew file mode 100644index 000000000..eaabc5e78--- /dev/null+++ b/apps/docs/images/product/README.md@@ -0,0 +1,19 @@+# Documentation screenshots++These are captures of the real Kaneo frontend using fictional Studio North data. No live account or database is used.++Board, List, task, and Gantt images use the same fixture capture as `apps/site/public/images/product/`, in both light and dark themes. Their original viewport is 1728 × 1000 at 2× density. These eight images are checked-in captures; the settings capture script below does not regenerate them.++Backlog, members, labels, workflow, integrations, notifications, and security settings are captured at 1440 × 1000 with 2× density. From the repository root, run:++```bash+node scripts/ui-review-bot/docs-screenshots.mjs+```++The script requires the UI review bot's Playwright dependencies and Chromium. It starts its own Vite server on port 5188, intercepts API calls with fixtures, blocks external requests, checks for browser errors and missing fixtures, and stops its server when finished.++Place screenshots in a Mintlify `Frame`, with `block dark:hidden` on the light image and `hidden dark:block` on the dark image. Include alt text and a caption. Review each changed capture before publishing.++The current documentation captures were refreshed against the local frontend on 2026-09-26. The fixture date controls sample task deadlines, not the capture date.++To capture only one view, set `DOCS_SCREENSHOT_VIEW`, for example `DOCS_SCREENSHOT_VIEW=integrations node scripts/ui-review-bot/docs-screenshots.mjs`.diff --git a/apps/docs/images/product/backlog-dark.png b/apps/docs/images/product/backlog-dark.pngnew file mode 100644index 000000000..210c6f7cdBinary files /dev/null and b/apps/docs/images/product/backlog-dark.png differdiff --git a/apps/docs/images/product/backlog-light.png b/apps/docs/images/product/backlog-light.pngnew file mode 100644index 000000000..805dae103Binary files /dev/null and b/apps/docs/images/product/backlog-light.png differdiff --git a/apps/docs/images/product/board-dark.png b/apps/docs/images/product/board-dark.pngnew file mode 100644index 000000000..775f04841Binary files /dev/null and b/apps/docs/images/product/board-dark.png differdiff --git a/apps/docs/images/product/board-light.png b/apps/docs/images/product/board-light.pngnew file mode 100644index 000000000..652ac8f7eBinary files /dev/null and b/apps/docs/images/product/board-light.png differdiff --git a/apps/docs/images/product/integrations-dark.png b/apps/docs/images/product/integrations-dark.pngnew file mode 100644index 000000000..a83c3e57cBinary files /dev/null and b/apps/docs/images/product/integrations-dark.png differdiff --git a/apps/docs/images/product/integrations-light.png b/apps/docs/images/product/integrations-light.pngnew file mode 100644index 000000000..f12b3878bBinary files /dev/null and b/apps/docs/images/product/integrations-light.png differdiff --git a/apps/docs/images/product/labels-dark.png b/apps/docs/images/product/labels-dark.pngnew file mode 100644index 000000000..a452d0b86Binary files /dev/null and b/apps/docs/images/product/labels-dark.png differdiff --git a/apps/docs/images/product/labels-light.png b/apps/docs/images/product/labels-light.pngnew file mode 100644index 000000000..7f0b45cb3Binary files /dev/null and b/apps/docs/images/product/labels-light.png differdiff --git a/apps/docs/images/product/list-dark.png b/apps/docs/images/product/list-dark.pngnew file mode 100644index 000000000..77eb95a2dBinary files /dev/null and b/apps/docs/images/product/list-dark.png differdiff --git a/apps/docs/images/product/list-light.png b/apps/docs/images/product/list-light.pngnew file mode 100644index 000000000..7dd5d385eBinary files /dev/null and b/apps/docs/images/product/list-light.png differdiff --git a/apps/docs/images/product/members-dark.png b/apps/docs/images/product/members-dark.pngnew file mode 100644index 000000000..91d1a78eaBinary files /dev/null and b/apps/docs/images/product/members-dark.png differdiff --git a/apps/docs/images/product/members-light.png b/apps/docs/images/product/members-light.pngnew file mode 100644index 000000000..0d548b2d1Binary files /dev/null and b/apps/docs/images/product/members-light.png differdiff --git a/apps/docs/images/product/notifications-dark.png b/apps/docs/images/product/notifications-dark.pngnew file mode 100644index 000000000..941dd4eeeBinary files /dev/null and b/apps/docs/images/product/notifications-dark.png differdiff --git a/apps/docs/images/product/notifications-light.png b/apps/docs/images/product/notifications-light.pngnew file mode 100644index 000000000..31f7682c4Binary files /dev/null and b/apps/docs/images/product/notifications-light.png differdiff --git a/apps/docs/images/product/security-dark.png b/apps/docs/images/product/security-dark.pngnew file mode 100644index 000000000..9d7cfbcfeBinary files /dev/null and b/apps/docs/images/product/security-dark.png differdiff --git a/apps/docs/images/product/security-light.png b/apps/docs/images/product/security-light.pngnew file mode 100644index 000000000..d4745e7d6Binary files /dev/null and b/apps/docs/images/product/security-light.png differdiff --git a/apps/docs/images/product/task-dark.png b/apps/docs/images/product/task-dark.pngnew file mode 100644index 000000000..5ac25909cBinary files /dev/null and b/apps/docs/images/product/task-dark.png differdiff --git a/apps/docs/images/product/task-light.png b/apps/docs/images/product/task-light.pngnew file mode 100644index 000000000..3781db2b1Binary files /dev/null and b/apps/docs/images/product/task-light.png differdiff --git a/apps/docs/images/product/timeline-dark.png b/apps/docs/images/product/timeline-dark.pngnew file mode 100644index 000000000..cbb0dadbdBinary files /dev/null and b/apps/docs/images/product/timeline-dark.png differdiff --git a/apps/docs/images/product/timeline-light.png b/apps/docs/images/product/timeline-light.pngnew file mode 100644index 000000000..5978247b5Binary files /dev/null and b/apps/docs/images/product/timeline-light.png differdiff --git a/apps/docs/images/product/workflow-dark.png b/apps/docs/images/product/workflow-dark.pngnew file mode 100644index 000000000..53dc22375Binary files /dev/null and b/apps/docs/images/product/workflow-dark.png differdiff --git a/apps/docs/images/product/workflow-light.png b/apps/docs/images/product/workflow-light.pngnew file mode 100644index 000000000..fa07eec2dBinary files /dev/null and b/apps/docs/images/product/workflow-light.png differdiff --git a/apps/docs/index.mdx b/apps/docs/index.mdxindex 8993c2abf..de78b7187 100644--- a/apps/docs/index.mdx+++ b/apps/docs/index.mdx@@ -1,44 +1,41 @@----title: "Why Kaneo"-description: "Why Kaneo is built around focused planning and real execution"+title: "Kaneo docs"+description: "Get your team started, find your way around, or run Kaneo on your own server."----Kaneo (`/kəˈneɪ.oʊ/`) is project management that stays out of your way.-This docs site is built to get you from zero to a running instance fast, then help you operate it confidently.+Keep your projects, tasks, and conversations in one place. Start with a small project and add the setup your team needs as you go.-## Where to Begin+<Frame caption="A website launch in Board view. Each column shows a stage of the work.">+ <img className="block dark:hidden" src="/images/product/board-light.png" alt="A website launch in Board view. Each column shows a stage of the work." />+ <img className="hidden dark:block" src="/images/product/board-dark.png" alt="A website launch in Board view. Each column shows a stage of the work." />+</Frame>-- [Quick Start](/core/index) for the fastest path to a running instance-- [Installation Guide](/core/installation/index) to choose drim vs Docker Compose-- [GitHub Integration Setup](/core/integrations/github/setup) for repo sync-- [Gitea Integration Setup](/core/integrations/gitea/setup) for self-hosted Gitea-- [GitLab Integration Setup](/core/integrations/gitlab/setup) for GitLab.com or self-managed GitLab-- [Outgoing webhooks](/core/integrations/outgoing-webhooks) for Slack, Discord, and custom HTTP notifications-- [API Introduction](/api-reference/introduction) for authenticated API usage+<CardGroup cols={2}>+ <Card title="Your first project" icon="rocket" href="/core/index">+ Create a workspace, invite a teammate, and finish your first task.+ </Card>+ <Card title="Run your own instance" icon="server" href="/core/installation/index">+ Install Kaneo with Docker Compose, drim, or your hosting platform.+ </Card>+ <Card title="Connect your tools" icon="plug" href="/core/integrations/index">+ Sync repositories, send project updates, and connect an AI assistant.+ </Card>+ <Card title="Build with the API" icon="code" href="/api-reference/introduction">+ Make your first request and explore the endpoint reference.+ </Card>+</CardGroup>-## Why Kaneo Exists+## How Kaneo is organized-Kaneo follows a simple idea: **all you need, nothing you don’t**.+A **workspace** holds your team, projects, and shared labels. A **project** holds a body of work, such as a website launch. A **task** is one piece of that work, with its own status, assignee, description, and conversation.-I'm Andrej, and I created Kaneo because I was tired of project management tools that got in the way more than they helped. After years of using bloated, overcomplicated platforms that distracted from actual work, I knew there had to be a better way.+If someone invited you, open their invitation link and sign in with the email address they invited. You can join their workspace without creating a new one.-The problem wasn't that these tools lacked features. It was that they had too many. Every notification, every unnecessary button, every complex workflow was pulling my team away from what mattered: building great products.+## Looking for something specific?-I believe the best tools are invisible. They should amplify your team's natural workflow, not force you to adapt to theirs. Kaneo is built on the principle that less is more: every feature exists because it solves a real problem, not because it looks impressive in a demo.+- [Board and List](/core/functional/plan-and-execute-tasks): create, find, and update tasks.+- [Members and roles](/core/functional/collaborate-with-team): invite people and manage access.+- [Backups and recovery](/core/operations/backups): protect a self-hosted installation.+- [Troubleshooting](/core/operations/troubleshooting): work through common setup problems.-## Planning in Kaneo--Planning in Kaneo is intentionally lightweight: you define the work, assign clear ownership, and move forward without ceremony.--Labels are central to that flow. Use labels to group initiatives, surface cross-cutting work, and keep prioritization clear across board and list views.--- Use labels to represent streams like `onboarding`, `backend`, or `customer-feedback`-- Combine labels with priority and due dates for sharper planning-- Keep label naming consistent across the workspace so filtering stays useful--## Continue--- [Deployments](/core/deployments/railway)-- [Authentication Providers](/core/social-providers/github)-- [Migrating from PLANKA](/core/migrations/from-planka)-- [Kaneo on GitHub](https://github.com/usekaneo/kaneo)+Screenshots throughout these guides show the real app with a fictional team, Studio North.diff --git a/packages/planka-import/README.md b/packages/planka-import/README.mdindex ca6b550cf..ccb3b7c76 100644--- a/packages/planka-import/README.md+++ b/packages/planka-import/README.md@@ -2,9 +2,7 @@Migrate your [PLANKA](https://planka.app) boards into [Kaneo](https://kaneo.app).-PLANKA has no export feature, so this tool reads your boards through PLANKA's-REST API and recreates them in Kaneo through Kaneo's public API. Nothing is-written to PLANKA, and your PLANKA credentials never leave your machine.+The CLI reads boards directly from PLANKA’s REST API and creates them through Kaneo’s public API. It does not modify PLANKA or use an intermediary migration service.## Usage@@ -13,19 +11,18 @@ npx @kaneo/planka-import --planka-url https://planka.example.com --dry-run```A dry run reads PLANKA only and prints exactly what would be created. When the-plan looks right, add your Kaneo credentials and drop `--dry-run`:+plan looks right, set `KANEO_API_KEY` in your environment and drop `--dry-run`:```bashnpx @kaneo/planka-import \--planka-url https://planka.example.com \--kaneo-url https://cloud.kaneo.app \- --kaneo-api-key kaneo_xxx \--workspace ws_123```You'll be prompted for your PLANKA login and for which boards to migrate.-Create a Kaneo API key under **Settings → API keys**. Self-hosting? Point+Create a Kaneo API key under **Settings → Account → API Keys**. Self-hosting? Point`--kaneo-url` at your own instance.## What carries over@@ -41,7 +38,7 @@ Create a Kaneo API key under **Settings → API keys**. Self-hosting? Point| Labels | Labels, with their original colors || Card members | Assignee, matched by email address || Due date | Due date |-| Comments | Comments, prefixed with the original author and date |+| Comments | Comments, with the original author recorded separately and the original date added to the text |One Kaneo project is created per PLANKA **board**, since the board is what holdslists and cards. If a PLANKA project has several boards, each Kaneo project is@@ -55,9 +52,9 @@ named `Project - Board`.- **Comment authorship.** The comment is created by the API key's owner, but theoriginal PLANKA author is recorded and displayed alongside it. Requires Kaneo2.17.6 or newer.-- **Priorities.** PLANKA has no priority field, so every task starts at+- **Priorities.** The importer sets every task to`no-priority`.-- **Custom fields, stopwatches, and card subscriptions.** No Kaneo equivalent.+- **Custom fields, stopwatches, and card subscriptions.** The importer does not transfer these. Kaneo supports custom fields and time entries, but you need to recreate that information yourself.**Run the import as a PLANKA admin.** PLANKA hides other users' email addressesfrom non-admin accounts, and assignees are matched by email, so a non-admindiff --git a/scripts/ui-review-bot/docs-screenshots.mjs b/scripts/ui-review-bot/docs-screenshots.mjsnew file mode 100644index 000000000..674cd3090--- /dev/null+++ b/scripts/ui-review-bot/docs-screenshots.mjs@@ -0,0 +1,275 @@+import assert from "node:assert/strict";+import { spawn } from "node:child_process";+import { mkdir } from "node:fs/promises";+import { fileURLToPath } from "node:url";+import { chromium } from "playwright";+import { fixture, installFixtures } from "./fixtures.mjs";++// Real frontend, fictional data. The fixture layer blocks all live API traffic.+const root = fileURLToPath(new URL("../../", import.meta.url));+const output = `${root}apps/docs/images/product`;+const origin = "http://127.0.0.1:5188";+const api = "http://127.0.0.1:4799";+const workspaceId = "ui-review-workspace";+const projectId = "ui-review-project";+const date = "2026-09-23T10:00:00.000Z";+const people = ["Alex Morgan", "Jamie Chen", "Sam Rivera"].map((name, i) => ({+ ...fixture(`${api}/api/auth/get-session`, "GET").user,+ id: i === 0 ? "ui-review-user" : `docs-person-${i}`,+ name,+ email: `${name.split(" ")[0].toLowerCase()}@example.test`,+}));+const members = people.map((user, i) => ({+ id: `docs-member-${i}`,+ organizationId: workspaceId,+ userId: user.id,+ role: i === 0 ? "owner" : "member",+ createdAt: date,+ user,+}));+const project = {+ ...fixture(`${api}/api/project/${projectId}`, "GET"),+ name: "Website launch",+};+const labels = [+ ["Design", "#a78bfa"],+ ["Engineering", "#60a5fa"],+ ["Content", "#fbbf24"],+].map(([name, color], i) => ({+ id: `docs-label-${i}`,+ workspaceId,+ name,+ color,+}));+const columns = ["To Do", "In Progress", "In Review", "Done"].map(+ (name, i) => ({+ ...fixture(`${api}/api/column/${projectId}`, "GET")[0],+ id: `docs-column-${i}`,+ name,+ position: i,+ isFinal: i === 3,+ tasks: [],+ }),+);+const plannedTasks = [+ "Explore a customer stories page",+ "Plan the next accessibility review",+ "Translate the launch announcement",+].map((title, i) => ({+ ...fixture(`${api}/api/task/ui-review-task`, "GET"),+ id: `docs-planned-${i}`,+ number: 40 + i,+ title,+ status: "planned",+ columnId: null,+ position: i,+ priority: i === 0 ? "medium" : "low",+ labels: [labels[i]],+}));+project.columns = columns;+project.plannedTasks = plannedTasks;+const views = [+ [+ "backlog",+ `/dashboard/workspace/${workspaceId}/project/${projectId}/backlog`,+ "Explore a customer stories page",+ ],+ ["members", `/dashboard/workspace/${workspaceId}/members`, "Jamie Chen"],+ ["workflow", `/dashboard/settings/projects/${projectId}/workflow`, "Columns"],+ ["labels", "/dashboard/settings/workspace/labels", "Engineering"],+ [+ "integrations",+ `/dashboard/settings/projects/${projectId}/integrations`,+ "Telegram Integration",+ ],+ [+ "notifications",+ "/dashboard/settings/account/notifications",+ "Task assignments",+ ],+ ["security", "/dashboard/settings/account/security", "Current password"],+];+await mkdir(output, { recursive: true });+const server = spawn(+ process.execPath,+ [+ "node_modules/vite/bin/vite.js",+ "--host",+ "127.0.0.1",+ "--port",+ "5188",+ "--strictPort",+ ],+ {+ cwd: `${root}apps/web`,+ stdio: ["ignore", "pipe", "pipe"],+ env: {+ PATH: process.env.PATH,+ HOME: process.env.HOME,+ NODE_ENV: "development",+ VITE_API_URL: api,+ VITE_APP_URL: origin,+ BROWSER: "none",+ },+ },+);+let log = "";+server.stdout.on("data", (chunk) => {+ log += chunk;+});+server.stderr.on("data", (chunk) => {+ log += chunk;+});+let browser;+try {+ for (let attempt = 0; ; attempt++) {+ if (server.exitCode !== null || attempt > 60) throw new Error(log);+ if (+ await fetch(origin).then(+ (r) => r.ok,+ () => false,+ )+ )+ break;+ await new Promise((resolve) => setTimeout(resolve, 500));+ }+ browser = await chromium.launch();+ for (const theme of ["light", "dark"]) {+ for (const [view, path, readyText] of views) {+ if (+ process.env.DOCS_SCREENSHOT_VIEW &&+ process.env.DOCS_SCREENSHOT_VIEW !== view+ )+ continue;+ const context = await browser.newContext({+ viewport: { width: 1440, height: 1000 },+ deviceScaleFactor: 2,+ locale: "en-US",+ timezoneId: "UTC",+ colorScheme: theme,+ reducedMotion: "reduce",+ serviceWorkers: "block",+ });+ const diagnostics = { unhandled: [], blocked: [] };+ await installFixtures(context, origin, diagnostics);+ await context.addInitScript((theme) => {+ localStorage.setItem(+ "user-preferences",+ JSON.stringify({ state: { theme }, version: 0 }),+ );+ }, theme);+ await context.route("**/api/**", async (route) => {+ const request = route.request();+ const p = new URL(request.url()).pathname;+ let data;+ if (p === "/api/user/security") data = { hasPassword: true };+ else if (p.replace(/\/$/, "") === "/api/notification-preferences")+ data = {+ emailAddress: "[email protected]",+ emailEnabled: false,+ ntfyEnabled: false,+ ntfyConfigured: false,+ ntfyServerUrl: null,+ ntfyTopic: null,+ ntfyTokenConfigured: false,+ maskedNtfyToken: null,+ gotifyEnabled: false,+ gotifyConfigured: false,+ gotifyServerUrl: null,+ gotifyTokenConfigured: false,+ maskedGotifyToken: null,+ webhookEnabled: false,+ webhookConfigured: false,+ webhookUrl: null,+ webhookSecretConfigured: false,+ maskedWebhookSecret: null,+ taskAssignmentEnabled: true,+ taskCommentEnabled: true,+ taskStatusChangeEnabled: true,+ dueDateReminderEnabled: true,+ dueDateReminderLeadTimeMinutes: 1440,+ workspaces: [],+ createdAt: date,+ updatedAt: date,+ };+ else if (p === "/api/project") data = [project];+ else if (p === `/api/project/${projectId}`) data = project;+ else if (p === `/api/task/tasks/${projectId}`)+ data = {+ data: project,+ pagination: {+ page: 1,+ pageSize: 50,+ totalPages: 1,+ total: plannedTasks.length,+ },+ };+ else if (p === `/api/column/${projectId}`) data = columns;+ else if (+ p === `/api/custom-field/project/${projectId}/values` ||+ p === `/api/custom-field/project/${projectId}/filter-values`+ )+ data = [];+ else if (p.endsWith("/organization/list-invitations"))+ data = [+ {+ id: "docs-invitation",+ organizationId: workspaceId,+ email: "[email protected]",+ role: "member",+ status: "pending",+ inviterId: people[0].id,+ createdAt: date,+ expiresAt: "2026-09-30T10:00:00.000Z",+ },+ ];+ else if (p.endsWith("/organization/list-members"))+ data = { members, total: members.length };+ else if (p.endsWith("/organization/list-roles")) data = [];+ else if (p.endsWith("/organization/get-full-organization"))+ data = {+ ...fixture(request.url(), request.method()),+ name: "Studio North",+ members,+ };+ else if (p.endsWith("/organization/list"))+ data = fixture(request.url(), request.method()).map((o) => ({+ ...o,+ name: "Studio North",+ }));+ else if (p === `/api/label/workspace/${workspaceId}`) data = labels;+ if (data === undefined || request.method() === "OPTIONS")+ return route.fallback();+ await route.fulfill({+ status: 200,+ contentType: "application/json",+ headers: {+ "access-control-allow-origin": origin,+ "access-control-allow-credentials": "true",+ },+ body: JSON.stringify(data),+ });+ });+ const page = await context.newPage();+ const errors = [];+ page.on("pageerror", (e) => errors.push(e.message));+ await page.clock.setFixedTime(new Date(date));+ await page.goto(`${origin}${path}`);+ await page.getByText(readyText, { exact: true }).first().waitFor();+ await page.waitForLoadState("networkidle");+ await page.evaluate(() => document.fonts.ready);+ await page.mouse.move(0, 0);+ await page.screenshot({+ path: `${output}/${view}-${theme}.png`,+ animations: "disabled",+ });+ console.log(JSON.stringify({ view, theme, errors, ...diagnostics }));+ assert.deepEqual(errors, []);+ assert.deepEqual(diagnostics.unhandled, []);+ await context.close();+ }+ }+} finally {+ await browser?.close();+ server.kill("SIGTERM");+}