How to Configure Environment Variables for Kaneo: Complete Setup Guide

Kaneo uses a single .env file at the repository root to configure both the API server and the web frontend, with all supported variables documented in ENVIRONMENT_SETUP.md and templated in .env.sample.

The open-source project management platform Kaneo (usekaneo/kaneo) centralizes its configuration through environment variables, allowing both the Hono-based API and the Vite-powered web application to read from the same source. This unified approach simplifies deployment across development and production environments while supporting optional integrations like Redis, SMTP, and SSO providers.

Core Configuration Architecture

Kaneo follows a single-source-of-truth pattern where one .env file serves the entire stack. According to the ENVIRONMENT_SETUP.md documentation, variables defined here are automatically available to both the backend API and the frontend build process, eliminating mismatched URLs between client and server.

The API server consumes variables directly via process.env, while the web application accesses them through import.meta.env for Vite-specific prefixes. In apps/api/src/index.ts, the server reads KANEO_CLIENT_URL and KANEO_API_URL to configure CORS and routing, while apps/web/src/lib/invitation-link.ts demonstrates how the frontend consumes VITE_APP_URL or falls back to KANEO_CLIENT_URL.

Required Environment Variables

To run Kaneo locally, you must define a minimum set of variables in the repository root .env file:

• KANEO_CLIENT_URL – The base URL of the web frontend (e.g., http://localhost:5173).
• KANEO_API_URL – The base URL of the API server (e.g., http://localhost:1337). If omitted, the API assumes the client URL with /api appended.
• AUTH_SECRET – A secret string for signing JWTs. Must be at least 32 characters in production; if omitted, a random secret generates at startup (sessions will not survive restarts).
• DATABASE_URL – A PostgreSQL connection string (e.g., postgresql://kaneo:password@localhost:5432/kaneo).

Alternatively, you may omit DATABASE_URL and provide the PostgreSQL credentials separately:

• POSTGRES_DB – Database name.
• POSTGRES_USER – Database user.
• POSTGRES_PASSWORD – Database password.
• POSTGRES_HOST and POSTGRES_PORT – Optional; default to localhost and 5432.

Minimal Development Configuration

# .env (copy from .env.sample)

KANEO_CLIENT_URL=http://localhost:5173
KANEO_API_URL=http://localhost:1337
AUTH_SECRET=0123456789abcdef0123456789abcdef
POSTGRES_DB=kaneo
POSTGRES_USER=kaneo
POSTGRES_PASSWORD=secret

Development-Specific Variables

When running the Vite development server, these variables override behavior for the web client:

• VITE_API_URL – Overrides the API endpoint URL for the frontend dev server.
• VITE_APP_URL – Used by the web app to generate absolute links (e.g., in email invitations).
• CORS_ORIGINS – Comma-separated list of allowed origins for cross-origin requests. Leaving this empty enables all origins in development mode.

In apps/api/src/auth.ts, the server references process.env.KANEO_CLIENT_URL to construct callback URLs, while the web layer uses import.meta.env.VITE_APP_URL as shown in the invitation link utility.

Optional Integrations

Kaneo supports extensive optional features toggled via environment variables:

Redis Pub/Sub for WebSocket Scaling

For horizontal scaling of real-time features, configure one of three Redis modes:

• Standalone: REDIS_URL=redis://localhost:6379
• Sentinel: REDIS_SENTINELS, REDIS_SENTINEL_MASTER_NAME, REDIS_SENTINEL_PASSWORD, REDIS_SENTINEL_TLS
• Cluster: REDIS_CLUSTER_NODES, REDIS_PASSWORD

SMTP Email Delivery

Enable email-based sign-in and invitation notifications:

SMTP_HOST=smtp.mailtrap.io
SMTP_PORT=2525
SMTP_USER=your_user
SMTP_PASSWORD=your_pass
SMTP_FROM=no-reply@mydomain.com
SMTP_SECURE=true
SMTP_REQUIRE_TLS=true

Single Sign-On (SSO)

Configure OAuth providers using the following patterns:

• GitHub: GITHUB_OAUTH_CLIENT_ID and GITHUB_OAUTH_CLIENT_SECRET (or legacy GITHUB_CLIENT_ID/GITHUB_CLIENT_SECRET).
• Google and Discord: Similar patterns documented in ENVIRONMENT_SETUP.md.

Cloud-Mode Abuse Mitigation

For hosted SaaS deployments, enable KANEO_CLOUD=true to activate stricter rate limits and disposable email blocking. This mode requires Turnstile captcha configuration:

• TURNSTILE_SECRET_KEY – Server-side secret.
• KANEO_TURNSTILE_SITE_KEY and VITE_TURNSTILE_SITE_KEY – Public site keys for server and client.

Sentry Error Monitoring

Optional error tracking supports dual DSN configuration:

• SENTRY_DSN and KANEO_SENTRY_DSN – API side.
• VITE_SENTRY_DSN – Client side.
• SENTRY_ENVIRONMENT and SENTRY_TRACES_SAMPLE_RATE – Shared configuration.

Configuration Examples

Enabling Redis for Multi-Instance Deployments

# Add to .env for WebSocket scaling

REDIS_URL=redis://localhost:6379

GitHub OAuth Setup

GITHUB_OAUTH_CLIENT_ID=your_github_app_id
GITHUB_OAUTH_CLIENT_SECRET=your_github_app_secret

Production Database URL

DATABASE_URL=postgresql://kaneo:secure_password@db.example.com:5432/kaneo_production

Summary

• Kaneo reads configuration from a single .env file at the repository root, shared between the API (apps/api/src/index.ts) and web frontend (apps/web/src/lib/invitation-link.ts).
• Required variables include KANEO_CLIENT_URL, KANEO_API_URL, AUTH_SECRET (≥32 characters), and PostgreSQL credentials via either DATABASE_URL or POSTGRES_DB/POSTGRES_USER/POSTGRES_PASSWORD.
• Development-specific prefixes (VITE_API_URL, VITE_APP_URL) configure the Vite dev server independently from production API routing.
• Optional integrations require specific variable sets: Redis for scaling, SMTP for email, OAuth credentials for SSO, and Turnstile keys for cloud-mode security.
• The repository provides .env.sample as a complete template and ENVIRONMENT_SETUP.md as the authoritative reference for all supported variables.

Frequently Asked Questions

What happens if I don't set AUTH_SECRET?

If AUTH_SECRET is omitted, Kaneo generates a random secret at startup. While this allows the application to run, user sessions will not survive server restarts, forcing all users to log in again after each deployment. In production, always set a persistent secret of at least 32 characters.

Can I use environment variables for database configuration instead of a connection string?

Yes. If you omit DATABASE_URL, Kaneo constructs the connection string from individual components: POSTGRES_DB, POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_HOST (default: localhost), and POSTGRES_PORT (default: 5432). This approach simplifies local development setups where connection string formatting might vary by platform.

How do I configure Kaneo for horizontal scaling across multiple servers?

Enable Redis Pub/Sub by setting REDIS_URL for standalone mode, or configure Sentinel/Cluster variables (REDIS_SENTINELS, REDIS_CLUSTER_NODES, etc.) for high-availability setups. This allows WebSocket connections to synchronize across multiple API instances, ensuring real-time updates propagate to all connected clients regardless of which server handles their connection.

What is the difference between KANEO_CLIENT_URL and VITE_APP_URL?

KANEO_CLIENT_URL is the canonical server-side reference to the frontend URL, used by the API for CORS configuration and callback generation in apps/api/src/auth.ts. VITE_APP_URL is a development-specific override consumed by the Vite dev server in apps/web/src/lib/invitation-link.ts to generate absolute links during local development. In production builds, the application typically relies on KANEO_CLIENT_URL.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}