Configuration

Veckl reads configuration from environment variables. For local development, copy .env.template to .env.

Required Variables

Variable	Purpose
`GITHUB_API_BASE_URL`	GitHub API URL. Use `https://api.github.com` for GitHub.com or `https://<ghes-host>/api/v3` for GHES.
`GITHUB_APP_ID`	GitHub App ID used for repository access.
`GITHUB_APP_INSTALLATION_ID`	Installation ID for the GitHub App on the target repository.
`GITHUB_APP_PRIVATE_KEY_PATH`	Path to the GitHub App private key PEM.
`GITHUB_OWNER`	Repository owner or organization.
`GITHUB_REPO`	Repository name.
`GITHUB_OAUTH_CLIENT_ID`	OAuth App client ID used for sign-in.
`GITHUB_OAUTH_CLIENT_SECRET`	OAuth App client secret used for sign-in.
`SESSION_HASH_KEY`	32-byte base64 key for authenticating session cookies.
`SESSION_BLOCK_KEY`	32-byte base64 key for encrypting session cookies.

Variable	Purpose
`GITHUB_BRANCH`	Branch to read and write. Leave empty to use the repository default branch.
`GITHUB_CA_BUNDLE_PATH`	CA bundle path for GHES instances with private TLS certificates.
`PORT`	Backend HTTP port. Defaults to `8080`.
`DISABLE_AUTH`	Local-only auth bypass. Never enable in production.
`FRONTEND_BASE_URL`	Frontend origin used after local OAuth login. `scripts/dev.sh` sets this to `http://localhost:3000` by default.
`GITHUB_OAUTH_REDIRECT_URL`	Exact OAuth redirect URL sent to GitHub. Useful in local development when frontend and backend use different ports.

Generate keys with:

./scripts/generate-session-keys.sh

Or generate each key manually:

openssl rand -base64 32

Then verify:

./scripts/verify-env.sh .env

When you use make dev, the helper script sets:

FRONTEND_BASE_URL=http://localhost:3000
GITHUB_OAUTH_REDIRECT_URL=http://localhost:3000/auth/github/callback

Your OAuth App must use the same callback URL.

In production, the Ingress should put backend and frontend paths behind the same browser origin. Register that public callback URL in the OAuth App:

https://<your-veckl-host>/auth/github/callback

DISABLE_AUTH=true is only for local development. It lets you work on the app without completing the OAuth flow.

Never set DISABLE_AUTH=true in production or in a shared environment.