Skip to main content

Environment Variables

Environment variables allow you to configure your application without changing code. Use them for API keys, database credentials, feature flags, and other configuration values.

Adding Environment Variables​

  1. Navigate to your application
  2. Go to the Environment tab
  3. Click Add Variable
  4. Enter the key and value
  5. Click Save
# Example format
DATABASE_URL=postgresql://user:password@host:5432/database
API_KEY=your-secret-api-key
NODE_ENV=production
Security Note

Environment variables containing secrets are encrypted at rest and never exposed in logs or the UI after creation.

Build vs Runtime Variables​

Kuploy distinguishes between two types of environment variables:

Build Variables​

Available during the build process. Use these for:

  • Build-time configuration
  • Installing private dependencies
  • Conditional compilation
# Example build variables
NPM_TOKEN=npm_xxx          # For private npm packages
BUILD_ENV=production       # Build optimization flags
NEXT_PUBLIC_API_URL=...    # Public client-side values

To mark a variable as build-time:

  1. Add the variable
  2. Check the Available at build time option

Runtime Variables​

Available when your application runs. Use these for:

  • Database connections
  • API keys and secrets
  • Feature flags
# Example runtime variables
DATABASE_URL=postgresql://...
STRIPE_SECRET_KEY=sk_live_xxx
FEATURE_NEW_UI=true
tip

Variables are runtime by default. Only enable build-time access when necessary, as it increases build times if values change.

Bulk Import from .env​

Import multiple variables at once from a .env file:

  1. Go to the Environment tab
  2. Click Bulk Import
  3. Paste your .env file contents or upload the file
  4. Review the variables
  5. Click Import
# Example .env file format
DATABASE_URL=postgresql://localhost:5432/myapp
REDIS_URL=redis://localhost:6379
SECRET_KEY=your-secret-key-here
DEBUG=false

# Comments are ignored
# Empty lines are also ignored
info

The bulk import parser supports:

  • KEY=value format
  • Quoted values: KEY="value with spaces"
  • Comments starting with #
  • Multi-line values with quotes

Referencing Kuploy-Managed Databases​

When you create a database in Kuploy, connection details are automatically available as variables:

PostgreSQL​

# Automatically available when you link a PostgreSQL database
POSTGRES_HOST=pg-xxx.kuploy.internal
POSTGRES_PORT=5432
POSTGRES_USER=kuploy
POSTGRES_PASSWORD=generated-password
POSTGRES_DATABASE=app_production

# Full connection string
DATABASE_URL=postgresql://kuploy:password@pg-xxx.kuploy.internal:5432/app_production

MySQL / MariaDB​

MYSQL_HOST=mysql-xxx.kuploy.internal
MYSQL_PORT=3306
MYSQL_USER=kuploy
MYSQL_PASSWORD=generated-password
MYSQL_DATABASE=app_production

DATABASE_URL=mysql://kuploy:password@mysql-xxx.kuploy.internal:3306/app_production

MongoDB​

MONGO_HOST=mongo-xxx.kuploy.internal
MONGO_PORT=27017
MONGO_USER=kuploy
MONGO_PASSWORD=generated-password
MONGO_DATABASE=app_production

MONGO_URL=mongodb://kuploy:password@mongo-xxx.kuploy.internal:27017/app_production

Redis​

REDIS_HOST=redis-xxx.kuploy.internal
REDIS_PORT=6379
REDIS_PASSWORD=generated-password

REDIS_URL=redis://:password@redis-xxx.kuploy.internal:6379

Linking Databases​

To automatically inject database variables:

  1. Go to your application's Environment tab
  2. Click Link Resource
  3. Select the database from your project
  4. Choose which variables to inject
  5. Click Link

The variables are automatically updated if the database credentials change.

Variable Interpolation​

Reference other variables within values:

# Define base values
APP_HOST=myapp.com
APP_PORT=3000

# Interpolate in other variables
APP_URL=https://${APP_HOST}:${APP_PORT}

Variable Groups​

Create reusable variable groups for common configurations:

  1. Go to Project Settings → Variable Groups
  2. Click Create Group
  3. Add your shared variables
  4. Link the group to applications

This is useful for:

  • Shared API keys across microservices
  • Common configuration for staging/production
  • Team-wide defaults

Environment-Specific Values​

Use different values for different environments:

VariableDevelopmentStagingProduction
NODE_ENVdevelopmentstagingproduction
LOG_LEVELdebuginfoerror
API_URLlocalhost:3000staging.api.comapi.com

Set environment-specific values:

  1. Create separate applications for each environment
  2. Or use branch-based deployments with different variable sets

Best Practices​

  1. Never commit secrets - Always use environment variables for sensitive data
  2. Use descriptive names - STRIPE_API_KEY is better than KEY1
  3. Document required variables - Keep a .env.example file in your repository
  4. Rotate secrets regularly - Update API keys and passwords periodically
  5. Use variable groups - Share common configuration across services
  6. Separate build and runtime - Only expose variables where needed
# .env.example - commit this to your repository
DATABASE_URL=
REDIS_URL=
API_KEY=
SECRET_KEY=

# .env - never commit this
DATABASE_URL=postgresql://...
REDIS_URL=redis://...
API_KEY=actual-key
SECRET_KEY=actual-secret