Skip to content

F1.7 — Environment Variables Management ​

What This Feature Does ​

F1.7 introduces project-scoped environment variables management in Vexlyx.

  1. Authenticated Encryption at Rest: All variable values are encrypted with AES-256-GCM using a 32-byte key derived from ENCRYPTION_KEY or SESSION_SECRET. Plaintext secrets are never stored in the database.
  2. 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.
  3. 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.yml service block.
  4. Key-Value Editor & .env Importer/Exporter: A dashboard UI supporting single variable addition, inline editing, search/filter, delete confirmations, .env export, and bulk .env raw 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 via node:crypto.randomBytes(12).
  • Auth Tag: 16 bytes (128 bits) generated by GCM to guarantee ciphertext authenticity and prevent tampering.
  • Storage Format: Stored in the value column as colon-delimited hex strings:
    <iv_hex>:<auth_tag_hex>:<cipher_text_hex>
  • Key Derivation: SHA-256 digest of ENCRYPTION_KEY (or SESSION_SECRET fallback) producing a 256-bit key.

Key Files ​

FileRole
packages/shared/src/schemas/env.tsZod validation schemas (SetEnvVarSchema, BulkSetEnvVarsSchema, ImportEnvFileSchema)
packages/shared/src/types/index.tsPublic EnvVar and DecryptedEnvVar TypeScript types
apps/api/src/utils/encryption.tsAES-256-GCM encryption, decryption, and authentication tag validation
apps/api/src/modules/env/service.tsBusiness logic for list (masked), reveal (decrypted), upsert, bulk upsert, delete, .env parser
apps/api/src/modules/env/routes.tsREST endpoints mounted at /api/projects/:id/env
apps/api/src/modules/deploy/service.tsInjects decrypted env map into runDockerDeploy
apps/api/src/modules/build/service.tsInjects decrypted env map into Nixpacks Phase 3 container deployment
apps/dashboard/src/hooks/useEnvVars.tsReact state management hook for environment variables
apps/dashboard/src/components/projects/EnvVarEditor.tsxInteractive 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[] } where maskedValue is "••••••••".

2. GET /api/projects/:id/env/:key/reveal ​

  • Auth: Required (Owner only)
  • Response: { id, key, value, createdAt, updatedAt } with plain decrypted value.

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.

EnvironmentENCRYPTION_KEY unsetPlaceholder / equal to SESSION_SECRET
development / testFalls back to SESSION_SECRET (zero-config local dev); boot logs a warningAccepted
productionBoot fails unless ENCRYPTION_KEY_LEGACY_FALLBACK=trueBoot 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.

  1. Generate a key: openssl rand -hex 32.
  2. Set ENCRYPTION_KEY=<that key> and ENCRYPTION_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.
  3. Re-encrypt the old values: pnpm db:reencrypt --dry-run to preview, then pnpm db:reencrypt (from apps/api; in production run it in the API container). It is idempotent and never modifies a value it cannot decrypt.
  4. Remove ENCRYPTION_KEY_LEGACY_FALLBACK and 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):

SurfaceBehaviour
EnvService.getDecryptedMap()Throws EnvError ENV_DECRYPT_FAILED (HTTP 500) naming every affected key
POST /api/projects/:id/deployResponds 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 jobDeployment is marked FAILED and the build log contains [vexlyx:error] Could not decrypt environment variable "KEY"…
GET …/env/:key/reveal500 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.

VariableUsed byNotes
REDIS_PASSWORDRedis (--requirepass), the API via REDIS_URLGenerated on first install, or added on upgrade when absent. Production refuses to start without it. Development defaults to vexlyx_dev
REDIS_URLAPIredis://:<REDIS_PASSWORD>@redis:6379; the API rejects a production URL without a password

Panel DNS Hosting ​

VariableUsed byNotes
DNS_NAMESERVERSAPIComma-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 ​

  1. Open any project detail page /projects/:id in the dashboard.
  2. Scroll to the Environment Variables section.
  3. Enter KEY_NAME and Value... in the quick add form.
  4. Click Add.
  5. Inspect the list: the new key appears with value masked as ••••••••.
  6. Inspect the database via pnpm db:studio: verify value in env_vars table is stored as an encrypted hex string (iv:tag:cipher) and not plaintext.

2. Reveal and Copy Value ​

  1. Click the Eye icon on any variable row.
  2. The decrypted plaintext value is retrieved and displayed.
  3. Click the Copy icon next to the value to copy it to clipboard.
  4. Click the EyeOff icon to re-mask the value.

3. Import .env File ​

  1. Click Import .env button in the header.
  2. Paste raw .env text 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"
  3. Click Import Variables.
  4. Confirm all 3 variables are parsed, encrypted, and listed.

4. Export .env File ​

  1. Click Export in the header.
  2. An .env.<projectId> file downloads containing all decrypted variables properly quoted.

5. Container Deployment Injection ​

  1. Deploy the project via the Deploy button.
  2. Check workspaces/projects/:id/deploy/docker-compose.yml.
  3. Verify all decrypted variables are formatted under the environment: section of the service.

Released under the MIT license.