Environment Variables & Secrets

Learn how TurboV stores, encrypts, and injects application secrets using industry-standard envelope encryption.

1. Security Architecture: Envelope Encryption

Storing plain-text environment variables or relying on single database-level passwords exposes applications to critical credential leakage. TurboV implements envelope encryption using AES-256-GCM:

[ Central Key Management Engine ]
                 │
                 │ Manages Root Key Encryption Key (KEK)
                 ▼
[ Per-Environment Data Encryption Key (DEK) ]
                 │ Generated as a dedicated, random 256-bit key
                 │ Encrypted via KEK into envelope format
                 ▼
[ Application Environment Variables & Secrets ]
                 │ Encrypted with DEK using AES-256-GCM
                 │ Stored with unique IV and authentication tag
                 ▼
[ Injected into Memory at Runtime ]
  Never baked into Docker images, never exposed in build caches

Key Security Guarantees

At-Rest Protection: All secrets are stored in encrypted ciphertext form. They cannot be decrypted without authorized access to the key management service.
Cryptographic Isolation: Every project and environment has an isolated Data Encryption Key (DEK). A secret in staging is encrypted with a completely different key than production.
Integrity Validation: AES-256-GCM includes an authentication tag for every ciphertext, ensuring secrets cannot be altered or corrupted in storage without failing validation immediately.

2. Managing Variables in the Dashboard

Adding Individual Variables

Navigate to your application's Environment → Settings → Environment Variables.
Click Add Variable.
Enter Key (e.g. STRIPE_API_KEY) and Value.
Click Save.

Bulk Import from `.env`

If you already have a local .env file:

Click Bulk Import.

Paste the contents of your .env file directly into the textarea:

# Database Configuration
DATABASE_URL="postgres://user:pass@db-postgres:5432/app"
PORT=3000
NODE_ENV="production"
API_KEY="sk_live_948fbc..."

The parser automatically handles comments (#), quotes (" or '), and multiline values cleanly.
Click Import & Encrypt.

Reveal & Hide Values

By default, secret values are masked in the dashboard UI with bullet points. Team members with OWNER or ADMIN privileges can click the eye icon to reveal the plaintext value during debugging sessions.

3. Variable Expansion & Cross-Referencing

Variables can reference other variables within the same environment using ${VAR} syntax:

DB_HOST=db-postgres
DB_PORT=5432
DB_USER=app_user
DB_PASS=secret123
DB_NAME=production_db
 
# Evaluated automatically at runtime
DATABASE_URL=postgres://${DB_USER}:${DB_PASS}@${DB_HOST}:${DB_PORT}/${DB_NAME}

4. Runtime Injection vs Build-Time Arguments

Understanding where environment variables exist in the deployment lifecycle is critical for security:

Phase	Variable Exposure	Security Behavior
Docker Build	Not exposed by default	Secrets are never baked into image layers. Build-time arguments must be explicitly enabled if required by static site generators.
Container Runtime	Injected via secure memory array	The agent passes decrypted variables in memory directly to the container during startup.
Version Control	Never stored in Git	Kept completely separate from code repositories.

5. Updates Trigger Zero-Downtime Redeployment

When you update, add, or delete an environment variable:

TurboV re-encrypts the secret store and records an audit log entry.
The agent automatically triggers a blue-green redeployment of your running containers.
The new container spins up with the updated environment variables.
Once verified healthy, Traefik routes traffic to the updated container.
In-flight requests are not interrupted.

6. Shared Project Variables

If you have multiple microservices sharing common configuration (such as AUTH_URL, SENTRY_DSN, or company-wide API keys), define them once as Project-Level Environment Variables. All applications inside the project inherit them automatically.