# How to Configure Environment Variables for Kaneo: Complete Setup Guide

> Learn how to configure environment variables for Kaneo. This guide details setup using the .env file for API server and web frontend in the usekaneo/kaneo repository.

- Repository: [kaneo.app/kaneo](https://github.com/usekaneo/kaneo)
- Tags: how-to-guide
- Published: 2026-08-09

---

**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`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/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

```text

# .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`](https://github.com/usekaneo/kaneo/blob/main/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:

```text
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`](https://github.com/usekaneo/kaneo/blob/main/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

```text

# Add to .env for WebSocket scaling

REDIS_URL=redis://localhost:6379

```

### GitHub OAuth Setup

```text
GITHUB_OAUTH_CLIENT_ID=your_github_app_id
GITHUB_OAUTH_CLIENT_SECRET=your_github_app_secret

```

### Production Database URL

```text
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`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/index.ts)) and web frontend ([`apps/web/src/lib/invitation-link.ts`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/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`](https://github.com/usekaneo/kaneo/blob/main/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`.