Skip to main content
KnowledgeCheckr uses Zod for runtime environment variable validation. All variables are validated at application startup, ensuring configuration errors are caught early.

​
Required Variables

These environment variables must be set for the application to start:

​
Application URLs

​
BETTER_AUTH_URL
string
required
Defines the trusted domains at which users can authenticate themselves. Must be a valid URL.Example: https://your-domain.com or http://localhost:3000
​
NEXT_PUBLIC_BASE_URL
string
required
The base URL for the application. Must start with http and include ://.Example: http://localhost:3000 or https://app.example.com

​
Authentication

​
AUTH_SECRET
string
required
Base64-encoded secret used for signing authentication tokens. Must be cryptographically secure.Generate a secret:
openssl rand -base64 32
Example: dGhpc2lzYXNlY3VyZXJhbmRvbXN0cmluZw==

​
Database Configuration

​
DATABASE_HOST
string
required
Database host URL, IP address, or Docker service name. Must not contain spaces when using a service name.Examples:
  • Docker Compose: db or mysql
  • External host: 192.168.1.100
  • URL: mysql.example.com
​
DATABASE_PORT
number
required
Database port number. Converted to integer internally.Default: 3306 (MySQL standard port)
​
DATABASE_NAME
string
required
Name of the database to use.Example: KnowledgeCheckr
​
DATABASE_USER
string
required
Database username for authentication.Example: root or appuser
​
DATABASE_PASSWORD
string
Database password. Optional for development, but strongly recommended for production.Example: secure_password_123

​
Optional Variables

​
OAuth Providers

​
GitHub Authentication

​
AUTH_GITHUB_ID
string
GitHub OAuth application client ID. Both AUTH_GITHUB_ID and AUTH_GITHUB_SECRET must be provided to enable GitHub authentication.How to obtain:
  1. Go to GitHub Settings > Developer settings > OAuth Apps
  2. Create a new OAuth application
  3. Copy the Client ID
​
AUTH_GITHUB_SECRET
string
GitHub OAuth application client secret. Required if AUTH_GITHUB_ID is set.Security: Never commit this value to version control.

​
Google Authentication

​
AUTH_GOOGLE_ID
string
Google OAuth 2.0 client ID. Both AUTH_GOOGLE_ID and AUTH_GOOGLE_SECRET must be provided to enable Google authentication.How to obtain:
  1. Go to Google Cloud Console
  2. Create OAuth 2.0 credentials
  3. Copy the Client ID
​
AUTH_GOOGLE_SECRET
string
Google OAuth 2.0 client secret. Required if AUTH_GOOGLE_ID is set.Security: Never commit this value to version control.

​
Custom Authentication Provider (Dex)

​
DEX_PROVIDER_URL
string
URL, IP, or service name for the Dex OIDC provider. Required when NEXT_PUBLIC_MODE is set to test.Examples:
  • Docker Compose: dex
  • External: https://dex.example.com
  • Development: http://localhost:5556
​
DEX_CLIENT_ID
string
default:"nextjs-client"
Client ID for Dex authentication. Defaults to nextjs-client.
​
DEX_CLIENT_SECRET
string
default:"dev-secret"
Client secret for Dex authentication. Defaults to dev-secret.Production: Always override the default value.

​
Application Behavior

​
NEXT_PUBLIC_MODE
enum
default:"production"
Application mode. Determines which features are enabled.Options: development, production, testNote: When set to test, Dex configuration becomes required.
​
SHOW_APP_VERSION
boolean
default:"false"
Whether to display the application version in the UI. Set to true to enable.Example: true or false

​
Logging & Monitoring

​
CAPTURE_CLIENT_LOGS
boolean
default:"false"
Enable capture of client-side logs for debugging. Set to true to enable.Example: true
​
ENABLE_FILE_LOGGING
boolean
default:"true"
Enable file-based logging using Winston. Set to false to disable.Example: true

​
Environment File Examples

​
Minimal Configuration (Development)

# Application URLs
BETTER_AUTH_URL=http://localhost:3000
NEXT_PUBLIC_BASE_URL=http://localhost:3000

# Authentication
AUTH_SECRET=dGhpc2lzYXNlY3VyZXJhbmRvbXN0cmluZw==

# Database
DATABASE_HOST=db
DATABASE_PORT=3306
DATABASE_NAME=KnowledgeCheckr
DATABASE_USER=root
DATABASE_PASSWORD=123

​
Production Configuration

# Application URLs
BETTER_AUTH_URL=https://app.example.com
NEXT_PUBLIC_BASE_URL=https://app.example.com

# Authentication
AUTH_SECRET=<base64-encoded-secret-here>

# Database
DATABASE_HOST=mysql.example.com
DATABASE_PORT=3306
DATABASE_NAME=KnowledgeCheckr
DATABASE_USER=appuser
DATABASE_PASSWORD=<secure-password-here>

# GitHub OAuth
AUTH_GITHUB_ID=<your-github-client-id>
AUTH_GITHUB_SECRET=<your-github-client-secret>

# Google OAuth
AUTH_GOOGLE_ID=<your-google-client-id>
AUTH_GOOGLE_SECRET=<your-google-client-secret>

# Application Settings
NEXT_PUBLIC_MODE=production
SHOW_APP_VERSION=true
ENABLE_FILE_LOGGING=true

​
Test Environment with Dex

# Application URLs
BETTER_AUTH_URL=http://localhost:3000
NEXT_PUBLIC_BASE_URL=http://localhost:3000

# Authentication
AUTH_SECRET=dGhpc2lzYXNlY3VyZXJhbmRvbXN0cmluZw==

# Database
DATABASE_HOST=db
DATABASE_PORT=3306
DATABASE_NAME=KnowledgeCheckr
DATABASE_USER=root
DATABASE_PASSWORD=123

# Test Mode with Dex
NEXT_PUBLIC_MODE=test
DEX_PROVIDER_URL=http://dex:5556
DEX_CLIENT_ID=nextjs-client
DEX_CLIENT_SECRET=test-secret

# Logging
CAPTURE_CLIENT_LOGS=true

​
Validation Rules

The application enforces strict validation rules defined in ~/workspace/source/src/lib/Shared/Env.ts:1-145:

​
OAuth Provider Validation

For each OAuth provider (GitHub, Google):
  • If both ID and secret are missing: Provider is disabled (no error)
  • If only one is provided: Validation error - both must be set
  • If both are provided: Provider is enabled
Example validation error: 
GitHub auth requires BOTH AUTH_GITHUB_ID and AUTH_GITHUB_SECRET
(either set both or leave both empty)

​
Test Mode Requirements

When NEXT_PUBLIC_MODE=test:
  • DEX_PROVIDER_URL is required
  • DEX_CLIENT_ID is required
  • DEX_CLIENT_SECRET is required

​
Type Conversions

Certain variables are automatically converted:
  • DATABASE_PORT: String → Integer
  • SHOW_APP_VERSION: String → Boolean
  • CAPTURE_CLIENT_LOGS: String → Boolean
  • ENABLE_FILE_LOGGING: String → Boolean
Boolean conversion: Case-insensitive “true” → true, anything else → false

​
Validation at Runtime

Environment variables are validated at two points:
  1. Build time: During npm run build (optional)
  2. Runtime: Before application starts (mandatory)
The validation script can be run manually: 
npm run validateEnvironment
If validation fails, the application will not start and will display a detailed error message: 
{
  "DATABASE_HOST": ["Please provide a valid database host url / ip / service-name"],
  "AUTH_SECRET": ["Invalid base64"]
}

​
Docker-Specific Configuration

When using Docker Compose (~/workspace/source/docker-compose.yml:1-41):

​
Environment Variables in docker-compose.yml

Some variables can be set directly in the compose file: 
environment:
  DATABASE_HOST: mysql
  DATABASE_PORT: 3306
  DATABASE_USER: root
  DATABASE_PASSWORD: 123
  DATABASE_NAME: KnowledgeCheckr

​
Using .env File

For sensitive data, use an .env file referenced in docker-compose.yml: 
env_file:
  - .env
Variables in the .env file override those in the environment section.

​
Service Name as Host

In Docker Compose, use the service name as the database host: 
DATABASE_HOST=db  # Matches the service name in docker-compose.yml

​
Security Best Practices

Never commit sensitive environment variables to version control. Use .env files and add them to .gitignore.
  1. Generate secure secrets: Use cryptographic tools like openssl to generate random secrets
  2. Use environment-specific files: Maintain separate .env.development, .env.production, etc.
  3. Restrict file permissions: Set .env files to read-only for the application user
  4. Rotate credentials regularly: Change passwords and secrets periodically
  5. Use secret management: In production, consider using secret management tools (Vault, AWS Secrets Manager, etc.)

​
Troubleshooting

​
”Missing Environment Variables” error

The application will print the exact variables that are missing or invalid: 
Missing Environment Variables:
{
  "AUTH_SECRET": ["Required"],
  "DATABASE_HOST": ["Required"]
}
Add these variables to your .env file.

​
OAuth provider not appearing

Check the application logs on startup: 
[.env] GitHub sign-in disabled (provide AUTH_GITHUB_ID and AUTH_GITHUB_SECRET to enable it)
[.env] Google sign-in disabled (provide AUTH_GOOGLE_ID and AUTH_GOOGLE_SECRET to enable it)
Both the ID and secret must be provided to enable a provider.

​
Database connection failures

Verify your database configuration:
  1. Ensure DATABASE_HOST is reachable from the application
  2. Check that DATABASE_PORT is correct (default: 3306)
  3. Verify credentials are correct
  4. Confirm the database exists

​
Boolean values not working

Boolean environment variables must be strings: 
# Correct
SHOW_APP_VERSION=true
CAPTURE_CLIENT_LOGS=false

# Incorrect (no quotes, but value must be the string "true")
SHOW_APP_VERSION=1
Only the exact string “true” (case-insensitive) is converted to boolean true.

Build docs developers (and LLMs) love

Get started for freeTalk to us