⚡ 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
feat: add Redis-backed broadcast adapter for WebSocket scaling
tiran133326149400a86
diff --git a/.env.sample b/.env.sampleindex f17a843e5..17c743e4a 100644--- a/.env.sample+++ b/.env.sample@@ -8,6 +8,9 @@ POSTGRES_DB=kaneoPOSTGRES_USER=kaneoPOSTGRES_PASSWORD=+# Pub/Sub for Websockets (Optional) -> auto fallback to in memory+#REDIS_URL=+# AuthenticationAUTH_SECRET=diff --git a/CLAUDE.md b/CLAUDE.mdindex 0582f5fea..42c530c3a 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -183,6 +183,7 @@ Required variables:Optional:- `CORS_ORIGINS` - Comma-separated allowed origins (empty = allow all in dev)- `VITE_API_URL` - API URL for web dev (defaults to http://localhost:1337)+- `REDIS_URL` - Redis connection string for multi-instance WebSocket broadcasts via Pub/Sub (omit for single-instance in-memory mode)- SSO providers (GitHub, Google, Discord, Custom OAuth/OIDC)- SMTP configurationdiff --git a/ENVIRONMENT_SETUP.md b/ENVIRONMENT_SETUP.mdindex 460cbfe3c..bc8d06ed5 100644--- a/ENVIRONMENT_SETUP.md+++ b/ENVIRONMENT_SETUP.md@@ -47,6 +47,11 @@ Kaneo supports many optional configuration options including:- SMTP configuration for email- Access control settings- CORS configuration+- Redis for horizontal scaling++#### Redis Configuration++- `REDIS_URL` - Redis connection string (e.g., `redis://localhost:6379`). When set, WebSocket broadcasts use Redis Pub/Sub, allowing multiple API instances to relay real-time updates. When not set, an in-memory adapter is used (single-instance only).#### SMTP Configurationdiff --git a/apps/api/package.json b/apps/api/package.jsonindex 215cc07ae..fbe91515c 100644--- a/apps/api/package.json+++ b/apps/api/package.json@@ -47,6 +47,7 @@"drizzle-orm": "^0.45.1","hono": "^4.12.7","hono-openapi": "^1.3.0",+ "ioredis": "^5.10.1","octokit": "^5.0.5","pg": "^8.20.0","valibot": "^1.2.0",diff --git a/apps/api/src/index.ts b/apps/api/src/index.tsindex 9630c8c18..02a4963bc 100644--- a/apps/api/src/index.ts+++ b/apps/api/src/index.ts@@ -68,7 +68,12 @@ import {import { validateWorkspaceAccess } from "./utils/validate-workspace-access";import workflowRule from "./workflow-rule";import workspace from "./workspace";-import { addConnection, removeConnection } from "./ws";+import {+ addConnection,+ initializeWebSocketAdapter,+ removeConnection,+ shutdownWebSocketAdapter,+} from "./ws";type ApiKey = {id: string;@@ -601,6 +606,7 @@ export async function runStartupTasks() {initializePlugins();initializeScheduler();+ await initializeWebSocketAdapter();}export async function startServer(@@ -614,9 +620,7 @@ export async function startServer(process.exit(1);}- process.on("SIGTERM", () => {- shutdownScheduler();- });+ let shuttingDown = false;const server = serve({@@ -631,6 +635,25 @@ export async function startServer();injectWebSocket(server);++ const gracefulShutdown = async () => {+ if (shuttingDown) return;+ shuttingDown = true;++ console.log("🛑 Shutting down gracefully...");+ shutdownScheduler();+ await shutdownWebSocketAdapter();+ server.close();+ process.exit(0);+ };++ process.on("SIGTERM", () => {+ void gracefulShutdown();+ });++ process.on("SIGINT", () => {+ void gracefulShutdown();+ });}const createdApp = createApp();diff --git a/apps/api/src/redis/index.ts b/apps/api/src/redis/index.tsnew file mode 100644index 000000000..411bc20ec--- /dev/null+++ b/apps/api/src/redis/index.ts@@ -0,0 +1,43 @@+import Redis from "ioredis";++let _redisPub: Redis | null = null;+let _redisSub: Redis | null = null;++function getRedisUrl(): string {+ const url = process.env.REDIS_URL;+ if (!url) {+ throw new Error("REDIS_URL is not set — cannot create Redis client");+ }+ return url;+}++export function getRedisPub(): Redis {+ if (!_redisPub) {+ _redisPub = new Redis(getRedisUrl());+ _redisPub.on("error", (err) =>+ console.error("Redis pub client error:", err),+ );+ }+ return _redisPub;+}++export function getRedisSub(): Redis {+ if (!_redisSub) {+ _redisSub = new Redis(getRedisUrl());+ _redisSub.on("error", (err) =>+ console.error("Redis sub client error:", err),+ );+ }+ return _redisSub;+}++export function closeRedis(): void {+ if (_redisPub) {+ _redisPub.disconnect();+ _redisPub = null;+ }+ if (_redisSub) {+ _redisSub.disconnect();+ _redisSub = null;+ }+}diff --git a/apps/api/src/ws/broadcast-adapter.ts b/apps/api/src/ws/broadcast-adapter.tsnew file mode 100644index 000000000..566743033--- /dev/null+++ b/apps/api/src/ws/broadcast-adapter.ts@@ -0,0 +1,24 @@+export type ProjectBroadcastMessage = {+ type: string;+ projectId: string;+ taskId?: string;+ sourceTaskId?: string;+ targetTaskId?: string;+};++export type BroadcastMessage = {+ projectId: string;+ message: ProjectBroadcastMessage;+ excludeInitiatorId?: string;+};++export interface BroadcastAdapter {+ /** Publish a message to all instances watching this project */+ publish(msg: BroadcastMessage): Promise<void>;++ /** Subscribe to messages for delivery to local connections */+ subscribe(handler: (msg: BroadcastMessage) => void): Promise<void>;++ /** Cleanup on shutdown */+ shutdown(): Promise<void>;+}diff --git a/apps/api/src/ws/in-memory-broadcast-adapter.ts b/apps/api/src/ws/in-memory-broadcast-adapter.tsnew file mode 100644index 000000000..2c4bd1269--- /dev/null+++ b/apps/api/src/ws/in-memory-broadcast-adapter.ts@@ -0,0 +1,18 @@+import type { BroadcastAdapter, BroadcastMessage } from "./broadcast-adapter";++export class InMemoryBroadcastAdapter implements BroadcastAdapter {+ private handler?: (msg: BroadcastMessage) => void;++ async publish(msg: BroadcastMessage): Promise<void> {+ // Deliver directly in the same process+ this.handler?.(msg);+ }++ async subscribe(handler: (msg: BroadcastMessage) => void): Promise<void> {+ this.handler = handler;+ }++ async shutdown(): Promise<void> {+ this.handler = undefined;+ }+}diff --git a/apps/api/src/ws/index.ts b/apps/api/src/ws/index.tsindex bae72b440..92a14decc 100644--- a/apps/api/src/ws/index.ts+++ b/apps/api/src/ws/index.ts@@ -1,5 +1,12 @@import type { WSContext } from "hono/ws";import { subscribeToEvent } from "../events";+import type {+ BroadcastAdapter,+ BroadcastMessage,+ ProjectBroadcastMessage,+} from "./broadcast-adapter";+import { InMemoryBroadcastAdapter } from "./in-memory-broadcast-adapter";+import { RedisBroadcastAdapter } from "./redis-broadcast-adapter";type ProjectConnection = {ws: WSContext;@@ -7,7 +14,15 @@ type ProjectConnection = {initiatorId: string;};+/**+ * Local connections — Each instance tracks only its own WebSocket connections.+ */const projectConnections = new Map<string, Set<ProjectConnection>>();++/**+ * Batching queues and timers local per-instance.+ * They accumulate messages before flushing to the broadcast adapter.+ */const projectBroadcastQueues = new Map<string,Map<string, { message: ProjectBroadcastMessage; excludeInitiatorId?: string }>@@ -17,6 +32,57 @@ const projectBroadcastTimeouts = new Map<ReturnType<typeof setTimeout>>();+let adapter: BroadcastAdapter | null = null;++// --- Subscribe to incoming broadcasts and deliver to local connections ---+export async function initializeWebSocketAdapter() {+ if (adapter) return;++ adapter = process.env.REDIS_URL+ ? new RedisBroadcastAdapter()+ : new InMemoryBroadcastAdapter();++ await adapter.subscribe((msg: BroadcastMessage) => {+ deliverToLocalConnections(+ msg.projectId,+ msg.message,+ msg.excludeInitiatorId,+ );+ });++ console.log(`📡 WebSockets Initialized using: "${adapter.constructor.name}"`);+}++export async function shutdownWebSocketAdapter() {+ for (const timeout of projectBroadcastTimeouts.values()) {+ clearTimeout(timeout);+ }+ projectBroadcastTimeouts.clear();+ projectBroadcastQueues.clear();++ await adapter?.shutdown();+ adapter = null;+}++function deliverToLocalConnections(+ projectId: string,+ message: ProjectBroadcastMessage,+ excludeInitiatorId?: string,+) {+ const connections = projectConnections.get(projectId);+ if (!connections) return;++ const payload = JSON.stringify(message);+ for (const conn of connections) {+ if (excludeInitiatorId && conn.initiatorId === excludeInitiatorId) continue;+ try {+ conn.ws.send(payload);+ } catch {+ // Connection might be closed, will be cleaned up on close event+ }+ }+}+export function addConnection(projectId: string,ws: WSContext,@@ -41,19 +107,16 @@ export function removeConnection(projectId: string, conn: ProjectConnection) {}}-type ProjectBroadcastMessage = {- type: string;- projectId: string;- taskId?: string;- sourceTaskId?: string;- targetTaskId?: string;-};-export function broadcastToProject(projectId: string,message: ProjectBroadcastMessage,excludeInitiatorId?: string,) {+ if (!adapter) {+ console.warn("broadcastToProject called before adapter initialization");+ return;+ }+if (!projectBroadcastQueues.has(projectId)) {projectBroadcastQueues.set(projectId, new Map());}@@ -72,19 +135,22 @@ export function broadcastToProject(const queue = projectBroadcastQueues.get(projectId);projectBroadcastQueues.delete(projectId);- const connections = projectConnections.get(projectId);- if (!connections || !queue) return;+ if (!queue || !adapter) return;+ // Publish each queued message through the adapterfor (const { message: msg, excludeInitiatorId: exId } of queue.values()) {- const payload = JSON.stringify(msg);- for (const conn of connections) {- if (exId && conn.initiatorId === exId) continue;- try {- conn.ws.send(payload);- } catch {- // Connection might be closed, will be cleaned up on close event- }- }+ void adapter+ .publish({+ projectId,+ message: msg,+ excludeInitiatorId: exId,+ })+ .catch((err) => {+ console.error(+ `Failed to publish broadcast for project ${projectId}:`,+ err,+ );+ });}}, 100);diff --git a/apps/api/src/ws/redis-broadcast-adapter.ts b/apps/api/src/ws/redis-broadcast-adapter.tsnew file mode 100644index 000000000..18bfadc8c--- /dev/null+++ b/apps/api/src/ws/redis-broadcast-adapter.ts@@ -0,0 +1,65 @@+import * as v from "valibot";+import { closeRedis, getRedisPub, getRedisSub } from "../redis";+import type { BroadcastAdapter, BroadcastMessage } from "./broadcast-adapter";++const CHANNEL_PREFIX = "kaneo:ws:";+const CHANNEL_SUFFIX = ":broadcast";+const CHANNEL_PATTERN = `${CHANNEL_PREFIX}*${CHANNEL_SUFFIX}`;++const broadcastMessageSchema = v.object({+ projectId: v.string(),+ message: v.object({+ type: v.string(),+ projectId: v.string(),+ taskId: v.optional(v.string()),+ sourceTaskId: v.optional(v.string()),+ targetTaskId: v.optional(v.string()),+ }),+ excludeInitiatorId: v.optional(v.string()),+});++export class RedisBroadcastAdapter implements BroadcastAdapter {+ private subscribed = false;++ async publish(msg: BroadcastMessage): Promise<void> {+ await getRedisPub().publish(+ this.channelForProject(msg.projectId),+ JSON.stringify(msg),+ );+ }++ async subscribe(handler: (msg: BroadcastMessage) => void): Promise<void> {+ if (this.subscribed) return;+ this.subscribed = true;++ // Pattern-subscribe to ALL project channels at once+ await getRedisSub().psubscribe(CHANNEL_PATTERN);++ // "pmessage" fires for pattern subscriptions (not "message")+ getRedisSub().on(+ "pmessage",+ (_pattern: string, _channel: string, data: string) => {+ try {+ const parsed = v.safeParse(broadcastMessageSchema, JSON.parse(data));+ if (!parsed.success) {+ console.error("Invalid broadcast message:", parsed.issues);+ return;+ }+ handler(parsed.output);+ } catch (err) {+ console.error("Failed to parse broadcast message:", err);+ }+ },+ );+ }++ async shutdown(): Promise<void> {+ // Unsubscribe from the pattern — covers all project channels+ await getRedisSub().punsubscribe(CHANNEL_PATTERN);+ closeRedis();+ }++ private channelForProject(projectId: string): string {+ return `${CHANNEL_PREFIX}${projectId}${CHANNEL_SUFFIX}`;+ }+}diff --git a/apps/docs/core/installation/environment-variables.mdx b/apps/docs/core/installation/environment-variables.mdxindex 88ddb986e..3151079d6 100644--- a/apps/docs/core/installation/environment-variables.mdx+++ b/apps/docs/core/installation/environment-variables.mdx@@ -19,6 +19,7 @@ The variables are split up into the following sections:- [Google SSO](#google-sso)- [Discord SSO](#discord-sso)- [Custom OAuth/OIDC](#custom-oauth-oidc)+- [Redis](#redis)- [SMTP Configuration](#smtp-configuration)## Required variables@@ -78,7 +79,7 @@ Name | Description | Default |Name | Description | Default |--- | --- | --- || `DISABLE_GUEST_ACCESS` | Disable anonymous/guest sign-in. When set to `true`, the guest access button will not be shown on sign-in and sign-up pages. | `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:** Users with valid workspace invitations can still register even when this is enabled. | `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:** Users with valid workspace invitations can still register even when this is enabled. | `false` || `DISABLE_PASSWORD_REGISTRATION` | Disable password-based account creation. When set to `true`, email/password sign-up is blocked, but social/OIDC registration remains available unless `DISABLE_REGISTRATION=true`. | `false` |### GitHub SSO & Integration@@ -119,6 +120,14 @@ Name | Description || `CUSTOM_OAUTH_RESPONSE_TYPE` | (Optional) OAuth response type. Default: `code`.| `CUSTOM_AUTH_PKCE` | (Optional) Enable/disable PKCE. Default: `true`.+### Redis++Kaneo supports Redis for horizontal scaling of WebSocket broadcasts. When `REDIS_URL` is set, multiple API instances can relay real-time updates via Redis Pub/Sub. When not set, an in-memory adapter is used (single-instance only).++Name | Description |+--- | --- |+| `REDIS_URL` | Redis connection string (e.g., `redis://localhost:6379`). Enables multi-instance WebSocket broadcasts via Redis Pub/Sub.+### SMTP ConfigurationName | Description |diff --git a/compose.local.yml b/compose.local.ymlindex 630c4d97c..7df0df598 100644--- a/compose.local.yml+++ b/compose.local.yml@@ -27,6 +27,12 @@ services:condition: service_healthyrestart: unless-stopped+# Optional+# redis:+# image: valkey/valkey+# ports:+# - "6379:6379"+web:build:context: .diff --git a/compose.yml b/compose.ymlindex 05bf98378..bf0fe2626 100644--- a/compose.yml+++ b/compose.yml@@ -25,6 +25,12 @@ services:condition: service_healthyrestart: unless-stopped+# Optional for HA Setup+# redis:+# image: valkey/valkey+# ports:+# - "6379:6379"+web:image: ghcr.io/usekaneo/web:latestports:diff --git a/pnpm-lock.yaml b/pnpm-lock.yamlindex 718ab6d1f..9ab851eba 100644--- a/pnpm-lock.yaml+++ b/pnpm-lock.yaml@@ -123,6 +123,9 @@ importers:hono-openapi:specifier: ^1.3.0version: 1.3.0(@hono/[email protected](@standard-schema/[email protected])([email protected]))(@standard-community/[email protected](@standard-schema/[email protected])(@types/[email protected])(@valibot/[email protected]([email protected]([email protected])))([email protected])([email protected])([email protected]([email protected]))([email protected]([email protected]))([email protected]))(@standard-community/[email protected](@standard-community/[email protected](@standard-schema/[email protected])(@types/[email protected])(@valibot/[email protected]([email protected]([email protected])))([email protected])([email protected])([email protected]([email protected]))([email protected]([email protected]))([email protected]))(@standard-schema/[email protected])([email protected])([email protected])([email protected]([email protected]))([email protected]))(@types/[email protected])([email protected])([email protected])+ ioredis:+ specifier: ^5.10.1+ version: 5.10.1octokit:specifier: ^5.0.5version: 5.0.5@@ -1730,6 +1733,9 @@ packages:'@types/node':optional: true+ '@ioredis/[email protected]':+ resolution: {integrity: sha512-JH8ZL/ywcJyR9MmJ5BNqZllXNZQqQbnVZOqpPQqE1vHiFgAw4NHbvE0FOduNU8IX9babitBT46571OnPTT0Zcw==}+'@jridgewell/[email protected]':resolution: {integrity: sha512-2kkt/7niJ6MgEPxF0bYdQ6etZaA+fQvDcLKckhy1yIQOzaoKjBBjSj63/aLVjYE3qhRt5dvM+uUyfCg6UKCBbA==}@@ -4675,6 +4681,10 @@ packages:resolution: {integrity: sha512-eYm0QWBtUrBWZWG0d386OGAw16Z995PiOVo2B7bjWSbHedGl5e0ZWaq65kOGgUSNesEIDkB9ISbTg/JK9dhCZA==}engines: {node: '>=6'}+ resolution: {integrity: sha512-RMr0FhtfXemyinomL4hrWcYJxmX6deFdCxpJzhDttxgO1+bcCnkk+9drydLVDmAMG7NE6aN/fl4F7ucU/90gAA==}+ engines: {node: '>=0.10.0'}+resolution: {integrity: sha512-Vsv7kFaXm+ptHDMZ7izaRsP70GgrW9NBNGswt9OZaVBLlE0SNpDq8eu/VGXyF9r7M0azK3Wy7OlYXsuyYLFzHg==}peerDependencies:@@ -5568,6 +5578,10 @@ packages:react: ^16.8 || ^17.0 || ^18.0 || ^19.0.0 || ^19.0.0-rcreact-dom: ^16.8 || ^17.0 || ^18.0 || ^19.0.0 || ^19.0.0-rc+ resolution: {integrity: sha512-HuEDBTI70aYdx1v6U97SbNx9F1+svQKBDo30o0b9fw055LMepzpOOd0Ccg9Q6tbqmBSJaMuY0fB7yw9/vjBYCA==}+ engines: {node: '>=12.22.0'}+resolution: {integrity: sha512-XXADHxXmvT9+CRxhXg56LJovE+bmWnEWB78LB83VZTprKTmaC5QfruXocxzTZ2Kl0DNwKuBdlIhjL8LeY8Sf8Q==}engines: {node: '>= 12'}@@ -5943,6 +5957,12 @@ packages:resolution: {integrity: sha512-TwuEnCnxbc3rAvhf/LbG7tJUDzhqXyFnv3dtzLOPgCG/hODL7WFnsbwktkD7yUV0RrreP/l1PALq/YSg6VvjlA==}+ resolution: {integrity: sha512-qjxPLHd3r5DnsdGacqOMU6pb/avJzdh9tFX2ymgoZE27BmjXrNy/y4LoaiTeAb+O3gL8AfpJGtqfX/ae2leYYQ==}++ resolution: {integrity: sha512-chi4NHZlZqZD18a0imDHnZPrDeBbTtVN7GXMwuGdRH9qotxAjYs3aVLKc7zNOG9eddR5Ksd8rvFEBc9SsggPpg==}+resolution: {integrity: sha512-oSXzaWypCMHkPC3NvBEaPHf0KsA5mvPrOPgQWDsbg8n7orZ290M0BmC/jgRZ4vcJ6DTAhjrsSYgdsW/F+MFOBA==}@@ -6864,6 +6884,14 @@ packages:resolution: {integrity: sha512-6tDA8g98We0zd0GvVeMT9arEOnTw9qM03L9cJXaCjrip1OO764RDBLBfrB4cwzNGDj5OA5ioymC9GkizgWJDUg==}engines: {node: '>=8'}+ resolution: {integrity: sha512-1qny3OExCf0UvUV/5wpYKf2YwPcOqXzkwKKSmKHiE6ZMQs5heeE/c8eXK+PNllPvmjgAbfnsbpkGZWy8cBpn9w==}+ engines: {node: '>=4'}++ resolution: {integrity: sha512-DJnGAeenTdpMEH6uAJRK/uiyEIH9WVsUmoLwzudwGJUwZPp80PDBWPHXSAGNPwNvIXAbe7MSUB1zQFugFml66A==}+ engines: {node: '>=4'}+resolution: {integrity: sha512-0YCaSCq2VRIebiaUviZNs0cBz1kg5kVS2UKUfNIx8YVs1cN3AV7NTctO5FOKBA+UT2BPJIWZauYHPqJODG50cg==}@@ -7103,6 +7131,9 @@ packages:resolution: {integrity: sha512-1XMJE5fQo1jGH6Y/7ebnwPOBEkIEnT4QF32d5R1+VXdXveM0IBMJt8zfaxX1P3QhVwrYe+576+jkANtSS2mBbw==}+ resolution: {integrity: sha512-qoRRSyROncaz1z0mvYqIE4lCd9p2R90i6GxW3uZv5ucSu8tU7B5HXUP1gG8pVZsYNVaXjk8ClXHPttLyxAL48A==}+resolution: {integrity: sha512-DvEy55V3DB7uknRo+4iOGT5fP1slR8wQohVdknigZPMpMstaKJQWhwiYBACJE3Ul2pTnATihhBYnRhZQHGBiRw==}engines: {node: '>= 0.8'}@@ -9234,6 +9265,8 @@ snapshots:'@types/node': 25.5.0optional: true+ '@ioredis/[email protected]': {}+'@jridgewell/[email protected]':dependencies:'@jridgewell/sourcemap-codec': 1.5.5@@ -13143,6 +13176,8 @@ snapshots:+ [email protected]: {}+[email protected](@types/[email protected](@types/[email protected]))(@types/[email protected])([email protected]([email protected]))([email protected]):dependencies:'@radix-ui/react-compose-refs': 1.1.2(@types/[email protected])([email protected])@@ -13316,8 +13351,7 @@ snapshots:- optional: true+ [email protected]: {}@@ -13997,6 +14031,20 @@ snapshots:react: 19.2.4react-dom: 19.2.4([email protected])+ dependencies:+ '@ioredis/commands': 1.5.1+ cluster-key-slot: 1.1.2+ debug: 4.4.3+ denque: 2.1.0+ lodash.defaults: 4.2.0+ lodash.isarguments: 3.1.0+ redis-errors: 1.2.0+ redis-parser: 3.0.0+ standard-as-callback: 2.1.0+ transitivePeerDependencies:+ - supports-color+@@ -14271,6 +14319,10 @@ snapshots:+ [email protected]: {}++ [email protected]: {}+@@ -15630,6 +15682,12 @@ snapshots:indent-string: 4.0.0strip-indent: 3.0.0+ [email protected]: {}++ dependencies:+ redis-errors: 1.2.0+dependencies:regex-utilities: 2.3.0@@ -15995,6 +16053,8 @@ snapshots:+ [email protected]: {}+