Environment variables

Use environment variables to configure CamelMind at runtime. This page explains which variables you need, when to set them, and where to configure them.

You typically configure environment variables in one of these places:

• Local development: .env.local
• Production: Your hosting platform's environment variable settings

You do not need to configure every variable on this page. Start with the variables required for your setup, then add optional variables when you enable features such as authentication, Last Updated information, offline exports, or the feedback widget.

Configure environment variables for local development

For local development, create .env.local from the example file included with your CamelMind project:

cp .env.example .env.local

Open .env.local and set the values required for your site.

Configure environment variables for production

For production deployments, configure environment variables in your hosting platform instead of committing an .env file to your repository.

For example, on Vercel, go to Project Settings → Environment Variables. Vercel makes the variables available to your application at build time and runtime.

The variables you need depend on which CamelMind features you use:

Site configuration environment variables and public URL settings

Configure general site configuration options, canonical domain settings, and base public URLs by setting the CAMELMIND_URL environment variable for your CamelMind documentation site:

For local development, use the default:

CAMELMIND_URL=http://localhost:3000

For production, replace it with your site's public URL:

CAMELMIND_URL=https://docs.example.com

Authentication environment variables and access control

Set these authentication environment variables when you enable CamelMind authentication to manage user sessions and control access to your documentation site:

For example, to enable authentication with the development mock provider:

CAMELMIND_AUTH_ENABLED=true
CAMELMIND_AUTH_REQUIRE_LOGIN=true
CAMELMIND_AUTH_PROVIDER=dev-mock
SESSION_SECRET=your-random-32-character-secret

For the complete authentication setup, see Authentication and RBAC.

OIDC and SSO identity provider environment variables

Configure these OpenID Connect (OIDC) and Single Sign-On (SSO) environment variables when CAMELMIND_AUTH_PROVIDER=oidc to integrate your identity provider with CamelMind:

Example:

CAMELMIND_AUTH_PROVIDER=oidc
OIDC_ISSUER=https://keycloak.example.com/realms/my-realm
OIDC_CLIENT_ID=my-docs
OIDC_CLIENT_SECRET=your-client-secret
OIDC_ROLES_CLAIM=realm_access.roles

Only configure these variables if you are using an OIDC provider. You do not need them when using the default dev-mock provider.

Configure Git access for Last Updated information

CamelMind can show the date and author of the most recent documentation change in the Last Updated footer.

To determine this information, CamelMind queries the GitHub or GitLab REST API. It checks public repositories without a token, subject to unauthenticated API rate limits. Private repositories require an API token.

This access is separate from your hosting provider's repository access. For example, Vercel may have permission to clone a private GitHub repository, but CamelMind still needs its own token to make an authenticated GitHub API request.

GitHub repositories environment variables

Configure GITHUB_TOKEN environment variables when your GitHub documentation repository is private or when you want to avoid unauthenticated GitHub API rate limits for Last Updated data:

GitLab repositories environment variables

Configure GITLAB_TOKEN environment variables when your GitLab documentation repository is private or when you want to avoid unauthenticated GitLab API rate limits for Last Updated data:

For more information about how CamelMind determines the date and author, see Last Updated.

Configure offline and static builds

Set OFFLINE_MODE when you want to generate a static version of your CamelMind site for offline use.

For example:

OFFLINE_MODE=true

You do not need to set this variable for a normal CamelMind deployment.

Configure the feedback widget

Set these variables when you want the CamelMind feedback widget to send visitor feedback by email through Resend.

At minimum, configure:

RESEND_API_KEY=your-resend-api-key
FEEDBACK_EMAIL_TO=feedback@example.com

Example .env.local development environment file

For local development, use the following .env.local configuration. The example uses the default development mock provider, so it comments out the OIDC environment variables:

# Site
CAMELMIND_URL=http://localhost:3000

# Authentication
CAMELMIND_AUTH_ENABLED=false
CAMELMIND_AUTH_REQUIRE_LOGIN=false
CAMELMIND_AUTH_PROVIDER=dev-mock
SESSION_SECRET=change-me-to-a-random-32-character-string

# OIDC — only needed when AUTH_PROVIDER=oidc
# OIDC_ISSUER=https://keycloak.example.com/realms/my-realm
# OIDC_CLIENT_ID=my-docs
# OIDC_CLIENT_SECRET=
# OIDC_ROLES_CLAIM=realm_access.roles

You can add other variables from this page as you enable the corresponding features.

Example production environment variables

The following example shows a production configuration using OIDC authentication:

CAMELMIND_URL=https://docs.example.com

# Authentication
CAMELMIND_AUTH_ENABLED=true
CAMELMIND_AUTH_REQUIRE_LOGIN=true
CAMELMIND_AUTH_PROVIDER=oidc
SESSION_SECRET=a-truly-random-32-character-secret

# OIDC
OIDC_ISSUER=https://keycloak.example.com/realms/prod
OIDC_CLIENT_ID=docs-prod
OIDC_CLIENT_SECRET=prod-secret-from-your-idp
OIDC_ROLES_CLAIM=realm_access.roles

Add GITHUB_TOKEN or GITLAB_TOKEN if your repository requires authentication to retrieve Last Updated information.

Add the Resend variables if you want to enable the feedback widget.

Environment variable checklist

Before deploying your CamelMind site, check which of these apply to your setup:

• Set CAMELMIND_URL to your production site URL.
• Set authentication variables if your site requires user login.
• Set OIDC variables if you use an OIDC identity provider.
• Set GITHUB_TOKEN or GITLAB_TOKEN if your repository is private or you want authenticated Git API access.
• Set OFFLINE_MODE=true only if you are generating a static offline build.
• Set Resend variables if you want to receive feedback widget submissions.
• Store secrets in your hosting platform's environment variable settings rather than in your repository.
• Never commit .env.local or files containing secrets to Git.