Environment Variables

Environment variables store configuration that changes between environments (development, staging, production) or contains sensitive information like API keys and secrets.

Overview

APSO supports three types of environment configuration:

Type	Use Case	Example
Variables	Non-sensitive config	`API_PREFIX`, `LOG_LEVEL`
Secrets	Sensitive data	`JWT_SECRET`, `STRIPE_KEY`
System	APSO-managed	`DATABASE_URL`, `PORT`

Managing Variables

From Dashboard

Navigate to your service
Go to Settings > Environment
Add, edit, or delete variables
Click Save to apply changes

From CLI


# Set a variable
apso env set API_PREFIX=/api/v2
 
# Set a secret (prompts for value)
apso env set --secret STRIPE_KEY
 
# List all variables
apso env list
 
# Delete a variable
apso env delete API_PREFIX

Variable Types

Standard Variables

Visible in logs and to all team members:


API_PREFIX=/api/v1
LOG_LEVEL=info
FEATURE_NEW_UI=true

Secrets

Encrypted and masked in logs:


JWT_SECRET=••••••••
STRIPE_SECRET_KEY=••••••••
DATABASE_PASSWORD=••••••••

Secrets:

Cannot be viewed after creation
Are encrypted at rest
Are masked in logs
Can only be replaced, not read

System Variables

Automatically set by APSO:

Variable	Description
`DATABASE_URL`	PostgreSQL connection string
`PORT`	Server port (3000)
`NODE_ENV`	`production` or `development`
`APSO_SERVICE_ID`	Unique service identifier
`APSO_DEPLOYMENT_ID`	Current deployment ID

System variables cannot be overridden.

Common Variables

Authentication


# JWT configuration
JWT_SECRET=your-super-secret-key-min-32-chars
JWT_EXPIRES_IN=7d
 
# Better Auth
BETTER_AUTH_SECRET=your-auth-secret
BETTER_AUTH_URL=https://your-app.com
 
# OAuth providers
GOOGLE_CLIENT_ID=...
GOOGLE_CLIENT_SECRET=...
GITHUB_CLIENT_ID=...
GITHUB_CLIENT_SECRET=...

Database


# Custom database (overrides APSO Cloud DB)
DATABASE_URL=postgresql://user:pass@host:5432/db
 
# Redis for caching
REDIS_URL=redis://localhost:6379

External Services


# Email
SENDGRID_API_KEY=...
SMTP_HOST=smtp.example.com
SMTP_USER=...
SMTP_PASS=...
 
# Storage
AWS_ACCESS_KEY_ID=...
AWS_SECRET_ACCESS_KEY=...
S3_BUCKET=my-bucket
 
# Payments
STRIPE_SECRET_KEY=...
STRIPE_WEBHOOK_SECRET=...

Feature Flags


FEATURE_NEW_DASHBOARD=true
FEATURE_BETA_API=false
MAINTENANCE_MODE=false

Accessing Variables

In Generated Code

Variables are available via process.env:


const apiPrefix = process.env.API_PREFIX || '/api';
const isProduction = process.env.NODE_ENV === 'production';

In Extensions


// src/extensions/services/email.service.ts
@Injectable()
export class EmailService {
  private readonly apiKey = process.env.SENDGRID_API_KEY;
 
  async send(to: string, subject: string, body: string) {
    // Use this.apiKey
  }
}

In Configuration

.apsorc


{
  "api": {
    "prefix": "${API_PREFIX}"
  }
}

Environment-Specific Configuration

Development

.env.development


DATABASE_URL=postgresql://dev:dev@localhost:5432/dev_db
LOG_LEVEL=debug
DEBUG=*

Staging

Set in APSO Dashboard for staging environment:


DATABASE_URL=<staging-db-url>
LOG_LEVEL=info

Production

Set in APSO Dashboard for production:


DATABASE_URL=<production-db-url>
LOG_LEVEL=warn

Best Practices

1. Never Commit Secrets

Add .env to .gitignore:


.env
.env.local
.env.*.local

2. Use Meaningful Names


# Good
STRIPE_SECRET_KEY=...
DATABASE_MAX_CONNECTIONS=20
 
# Bad
KEY1=...
DB_NUM=20

3. Provide Defaults


const port = process.env.PORT || 3000;
const logLevel = process.env.LOG_LEVEL || 'info';

4. Validate Required Variables


const required = ['JWT_SECRET', 'DATABASE_URL'];
for (const key of required) {
  if (!process.env[key]) {
    throw new Error(`Missing required env var: ${key}`);
  }
}

5. Use Secrets for Sensitive Data

Never use standard variables for:

Passwords
API keys
Private keys
Tokens

Troubleshooting

Variable Not Available

Verify it’s set in the dashboard
Check for typos in the variable name
Redeploy after adding new variables
Check if it’s a system variable (cannot override)

Secret Not Working

Secrets cannot be read, only replaced
Create a new secret if unsure of the value
Check the variable name exactly matches usage

Environment Mismatch

Verify you’re editing the correct environment
Check dashboard environment selector
Redeploy after making changes