Running the Project Locally

The Realtime Kanban app is in the GitHub repository .

Copy the app. This also installs the dependencies:

npx create-next-app@latest --example https://github.com/finom/vovk/tree/main/examples/realtime-kanban realtime-kanban && cd realtime-kanban

Create a .env file in the project root with your OpenAI API key and the database connection strings:

OPENAI_API_KEY=change_me
DATABASE_URL="postgresql://postgres:password@localhost:5432/realtime-kanban-db?schema=public"
DATABASE_URL_UNPOOLED="postgresql://postgres:password@localhost:5432/realtime-kanban-db?schema=public"
REDIS_URL=redis://localhost:6379

Start the Docker containers:

docker-compose up -d

Start the development server. It first generates the Prisma client, the Zod schemas and the Vovk.ts client, and creates the database tables:

npm run dev

Open http://localhost:3000  in your browser. Create users and tasks in the UI (click “+ Add a Team Member” and so on), or with one of the floating AI buttons: Text or Voice.

The variables in .env:

• OPENAI_API_KEY – your OpenAI API key, needed for the AI features. Creating or updating a user or a task also calls the embeddings API. Without a working key, the row is saved without an embedding, and search skips it until an update adds one.
• DATABASE_URL – the database connection string. database-service.ts  creates the Prisma client with it.
• DATABASE_URL_UNPOOLED – the connection string for direct connections. prisma.config.ts  uses it for migrations.
• REDIS_URL – the Redis connection string for the realtime features. See the Polling article.

Optional variables:

• PASSWORD – password protection for the app’s pages and API. It doesn’t cover the MCP server or the Telegram webhook, which have their own keys below. See the Authentication article.
• SESSION_SECRET – the key that signs the session cookie. Set it whenever you set PASSWORD. Without it, the app uses a default key from the public repository. Generate one with openssl rand -base64 32.
• MCP_ACCESS_KEY – an authorization key for the MCP server, sent in the ?mcp_access_key=your_key query parameter. If it isn’t set, the MCP server needs no key. See the MCP article.
• TELEGRAM_BOT_TOKEN – turns on the Telegram bot. See the Telegram Integration article.
• TELEGRAM_WEBHOOK_SECRET – the secret Telegram sends with each webhook call. The webhook answers only when both Telegram variables are set.