F1.7 — Environment Variables Management
What This Feature Does
F1.7 introduces project-scoped environment variables management in Vexlyx.
- Authenticated Encryption at Rest: All variable values are encrypted with AES-256-GCM using a 32-byte key derived from
ENCRYPTION_KEYorSESSION_SECRET. Plaintext secrets are never stored in the database. - Masked By Default: Variable listing endpoints and dashboard views mask values with
••••••••to prevent shoulder-surfing and accidental disclosure. Authorized project owners can toggle and reveal or copy individual values on demand. - Container Runtime Injection: During deployment (both via manual deploy and automated Nixpacks build pipeline), project environment variables are decrypted in-memory and injected directly into the project's generated
docker-compose.ymlservice block. - Key-Value Editor & .env Importer/Exporter: A dashboard UI supporting single variable addition, inline editing, search/filter, delete confirmations, .env export, and bulk
.envraw text import (with comments and multiline value support).
Architecture
┌─────────────────────────────────────────────────────────────┐
│ Next.js Dashboard │
│ • EnvVarEditor (Key-Value Table, Search, Quick Add) │
│ • Import .env Modal (Raw parser, overwrite/merge) │
│ • On-demand decrypt/reveal toggle │
└──────────────────────────────┬──────────────────────────────┘
│ REST (Session Cookie)
▼
┌─────────────────────────────────────────────────────────────┐
│ Fastify API │
│ • modules/env/routes.ts │
│ • modules/env/service.ts (list, reveal, upsert, import) │
│ • utils/encryption.ts (AES-256-GCM encrypt/decrypt) │
└──────────────┬───────────────────────────────┬──────────────┘
│ │
SQL (Prisma) Deploy / Build Service
│ │
▼ ▼
┌──────────────────────────────┐ ┌─────────────────────────────┐
│ PostgreSQL (env_vars) │ │ system/python/ │
│ • id, projectId, key │ │ docker_manager.py │
│ • value: iv:tag:ciphertext │ │ • injects into compose │
└──────────────────────────────┘ └─────────────────────────────┘Security & Encryption Specification
- Algorithm:
aes-256-gcm(Galois/Counter Mode with Authenticated Encryption). - IV (Initialization Vector): 12 bytes (
96 bits) cryptographically random buffer generated per encryption vianode:crypto.randomBytes(12). - Auth Tag: 16 bytes (
128 bits) generated by GCM to guarantee ciphertext authenticity and prevent tampering. - Storage Format: Stored in the
valuecolumn as colon-delimited hex strings:<iv_hex>:<auth_tag_hex>:<cipher_text_hex> - Key Derivation: SHA-256 digest of
ENCRYPTION_KEY(orSESSION_SECRETfallback) producing a 256-bit key.
Key Files
| File | Role |
|---|---|
packages/shared/src/schemas/env.ts | Zod validation schemas (SetEnvVarSchema, BulkSetEnvVarsSchema, ImportEnvFileSchema) |
packages/shared/src/types/index.ts | Public EnvVar and DecryptedEnvVar TypeScript types |
apps/api/src/utils/encryption.ts | AES-256-GCM encryption, decryption, and authentication tag validation |
apps/api/src/modules/env/service.ts | Business logic for list (masked), reveal (decrypted), upsert, bulk upsert, delete, .env parser |
apps/api/src/modules/env/routes.ts | REST endpoints mounted at /api/projects/:id/env |
apps/api/src/modules/deploy/service.ts | Injects decrypted env map into runDockerDeploy |
apps/api/src/modules/build/service.ts | Injects decrypted env map into Nixpacks Phase 3 container deployment |
apps/dashboard/src/hooks/useEnvVars.ts | React state management hook for environment variables |
apps/dashboard/src/components/projects/EnvVarEditor.tsx | Interactive UI table, quick add, live reveal, search, edit, delete, and import modal |
API Endpoints
1. GET /api/projects/:id/env
- Auth: Required (Owner only)
- Response:
{ variables: EnvVar[] }wheremaskedValueis"••••••••".
2. GET /api/projects/:id/env/:key/reveal
- Auth: Required (Owner only)
- Response:
{ id, key, value, createdAt, updatedAt }with plain decryptedvalue.
3. POST /api/projects/:id/env
- Auth: Required (Owner only)
- Body: Single
{ key: string, value: string }OR bulk{ variables: Array<{ key: string, value: string }> }. - Response: Upserted record or
{ count, variables }.
4. POST /api/projects/:id/env/import
- Auth: Required (Owner only)
- Body:
{ content: string, overwrite?: boolean } - Response:
{ count, variables }
5. DELETE /api/projects/:id/env/:key
- Auth: Required (Owner only)
- Response:
{ message: string }
Encryption Key Requirements (#69)
Everything encrypted at rest (env vars, database and SFTP passwords, 2FA secrets, TLS private keys, GitHub App secrets) uses ENCRYPTION_KEY.
| Environment | ENCRYPTION_KEY unset | Placeholder / equal to SESSION_SECRET |
|---|---|---|
development / test | Falls back to SESSION_SECRET (zero-config local dev); boot logs a warning | Accepted |
production | Boot fails unless ENCRYPTION_KEY_LEGACY_FALLBACK=true | Boot fails |
The installer already generates a dedicated key, so installer-based deployments are unaffected.
Upgrading an install that never set ENCRYPTION_KEY
Its data is encrypted under a key derived from SESSION_SECRET. Do not just add a key: existing values would become undecryptable.
- Generate a key:
openssl rand -hex 32. - Set
ENCRYPTION_KEY=<that key>andENCRYPTION_KEY_LEGACY_FALLBACK=true, then restart the API. Old values stay readable; new writes use the new key. A boot warning reminds you the fallback is on. - Re-encrypt the old values:
pnpm db:reencrypt --dry-runto preview, thenpnpm db:reencrypt(fromapps/api; in production run it in the API container). It is idempotent and never modifies a value it cannot decrypt. - Remove
ENCRYPTION_KEY_LEGACY_FALLBACKand restart.
Back up the database before step 3. Tests: utils/encryption-legacy.test.ts, config/env.test.ts.
Undecryptable Variables (ENV_DECRYPT_FAILED, #49)
If ENCRYPTION_KEY (or SESSION_SECRET, when no key is set outside production) changes, or a stored value is corrupted, a variable can no longer be decrypted. The pipeline fails loudly instead of substituting an empty string, because a container booted with an empty password or API key fails confusingly at runtime (or connects with an empty credential):
| Surface | Behaviour |
|---|---|
EnvService.getDecryptedMap() | Throws EnvError ENV_DECRYPT_FAILED (HTTP 500) naming every affected key |
POST /api/projects/:id/deploy | Responds 500 ENV_DECRYPT_FAILED with the message; the project is left in its previous status (the env map is decrypted before the status flips to CREATING) |
| Build job | Deployment is marked FAILED and the build log contains [vexlyx:error] Could not decrypt environment variable "KEY"… |
GET …/env/:key/reveal | 500 ENV_DECRYPT_FAILED for that key |
GET …/env (list) | Unaffected — values stay masked and are never decrypted |
Empty values are valid. A variable intentionally set to an empty string encrypts to a ciphertext with an empty data part (the GCM authentication tag is still present and verified), decrypts back to "", and never triggers ENV_DECRYPT_FAILED. Only a missing IV or tag, or a ciphertext that fails authentication, is treated as corrupted (utils/encryption.test.ts).
Recovery: restore the previous ENCRYPTION_KEY, or re-enter the named variables (saving re-encrypts them with the current key). Tests: apps/api/src/modules/env/service.test.ts and apps/api/src/modules/deploy/service.test.ts.
Not done here: a dedicated "re-enter this value" prompt in the dashboard UI — the error message names the key and the API returns a stable code the UI can key off.
Panel Secrets
These belong to the panel itself, not to a project. The installer generates them once into /etc/vexlyx/vexlyx.env and never rotates them on a re-run.
| Variable | Used by | Notes |
|---|---|---|
REDIS_PASSWORD | Redis (--requirepass), the API via REDIS_URL | Generated on first install, or added on upgrade when absent. Production refuses to start without it. Development defaults to vexlyx_dev |
REDIS_URL | API | redis://:<REDIS_PASSWORD>@redis:6379; the API rejects a production URL without a password |
Panel DNS Hosting
| Variable | Used by | Notes |
|---|---|---|
DNS_NAMESERVERS | API | Comma-separated nameservers users delegate a domain to for "Host DNS on Vexlyx". Unset by default: the panel then reports DNS hosting as not configured and refuses to enable it (409 DNS_HOSTING_NOT_CONFIGURED). Set it to nameservers you actually operate, e.g. ns1.example.com,ns2.example.com. See DNS management |
See Network layout.
How to Test
1. Add Environment Variable
- Open any project detail page
/projects/:idin the dashboard. - Scroll to the Environment Variables section.
- Enter
KEY_NAMEandValue...in the quick add form. - Click Add.
- Inspect the list: the new key appears with value masked as
••••••••. - Inspect the database via
pnpm db:studio: verifyvalueinenv_varstable is stored as an encrypted hex string (iv:tag:cipher) and not plaintext.
2. Reveal and Copy Value
- Click the Eye icon on any variable row.
- The decrypted plaintext value is retrieved and displayed.
- Click the Copy icon next to the value to copy it to clipboard.
- Click the EyeOff icon to re-mask the value.
3. Import .env File
- Click Import .env button in the header.
- Paste raw
.envtext containing multiple variables, comments (#), and quoted values:dotenv# Database connection DATABASE_URL="postgres://admin:secret@localhost:5432/myapp" PORT=8000 API_KEY="sk_live_998877" - Click Import Variables.
- Confirm all 3 variables are parsed, encrypted, and listed.
4. Export .env File
- Click Export in the header.
- An
.env.<projectId>file downloads containing all decrypted variables properly quoted.
5. Container Deployment Injection
- Deploy the project via the Deploy button.
- Check
workspaces/projects/:id/deploy/docker-compose.yml. - Verify all decrypted variables are formatted under the
environment:section of the service.