Environment Configuration

Updated: Wed 06 May 2026 17:14:18 CEST — Phase 1 naming migration: removed Lovable dashboard reference; updated frontend env section to “Plings-Web (Vercel project)”

All runtime configuration is provided via environment variables, set in Vercel project settings (one project per service: Plings-API, Plings-Gateway, Plings-Web).

Frontend Environment Variables

Variable	Example	Purpose
`VITE_GRAPHQL_ENDPOINT`	`https://api.plings.io/graphql/`	Points Apollo Client to backend
`VITE_SUPABASE_URL`	`https://xyz.supabase.co`	Supabase project base URL
`VITE_SUPABASE_ANON_KEY`	`eyJhbGciOiJI...`	Public anon key for client auth
`SENTRY_DSN`	`https://abc.ingest.sentry.io/123`	Error tracking

Backend Environment Variables

Variable	Example	Purpose	Security Level
`PLINGS_MASTER_KEY`	`5KYZdUEo39z3FPLjCKpxKkGXstPbqGiELQgSXzFm9ysh`	Master key for HD wallet derivation	TOP SECRET
`SUPABASE_URL`	`https://xyz.supabase.co`	Supabase project URL	Standard
`SUPABASE_ANON_KEY`	`eyJhbGciOiJI...`	Public anon key	Standard
`SUPABASE_DB_URL`	`postgresql://postgres:pw@host:5432/db`	Direct PostgreSQL connection	Secret
`NEO4J_URI`	`neo4j+s://xyz.databases.neo4j.io`	Neo4j graph database connection	Secret
`NEO4J_USER`	`neo4j`	Neo4j username	Standard
`NEO4J_PASSWORD`	`your-password`	Neo4j password	Secret

Key Management Strategy

Plings uses a three-tier key management approach:

Initial Tier: Vercel environment variables (current)
Next Level: SoftHSM with PKCS#11 interface
Final Level: Hardware HSM (AWS CloudHSM/Thales Luna)

Production Deployment Variables

For production deployment, ensure these variables are set:

# Plings-Web (Vercel project)
VITE_GRAPHQL_ENDPOINT=https://api.plings.io/graphql
VITE_SUPABASE_URL=your_supabase_url
VITE_SUPABASE_ANON_KEY=your_supabase_anon_key

# Plings-API (Vercel project)
PLINGS_MASTER_KEY=your_master_key_base58
SUPABASE_URL=your_supabase_url
SUPABASE_ANON_KEY=your_supabase_anon_key
SUPABASE_DB_URL=your_postgres_connection_string
NEO4J_URI=your_neo4j_connection_uri
NEO4J_USER=neo4j
NEO4J_PASSWORD=your_neo4j_password

Environment-Specific Configuration

Create separate configurations for each environment:

Development

# .env.development
PLINGS_MASTER_KEY=dev_master_key_base58
SUPABASE_URL=https://dev-project.supabase.co
NEO4J_URI=neo4j+s://dev-instance.databases.neo4j.io

Staging

# .env.staging
PLINGS_MASTER_KEY=staging_master_key_base58
SUPABASE_URL=https://staging-project.supabase.co
NEO4J_URI=neo4j+s://staging-instance.databases.neo4j.io

Production

# .env.production
PLINGS_MASTER_KEY=prod_master_key_base58
SUPABASE_URL=https://prod-project.supabase.co
NEO4J_URI=neo4j+s://prod-instance.databases.neo4j.io

Security Best Practices

Never commit environment files to version control
Use different keys for each environment
Manage wallet versions strategically (not arbitrary rotation)
Restrict team access to production keys
Enable audit logging for key access

Master Key Lifecycle Management

Important: HD wallet master keys are NOT rotated like traditional API keys. Instead, Plings uses wallet versioning for key lifecycle management:

When to Create New Wallet Versions:

Security incidents: Suspected key compromise
Infrastructure upgrades: Migration to SoftHSM or Hardware HSM
Business expansion: Geographic or regulatory requirements
Planned migrations: Annual security reviews

Vercel Environment Variable Strategy:

# Current approach - single wallet version
PLINGS_MASTER_KEY=wallet_v1_master_key

# Multi-wallet approach (when needed)
PLINGS_MASTER_KEY_V1=wallet_v1_master_key  # Existing identifiers
PLINGS_MASTER_KEY_V2=wallet_v2_master_key  # New identifiers
# Default wallet for new identifiers
PLINGS_DEFAULT_WALLET=2

Key Management Logic:

// Multi-wallet key derivation
function getMasterKey(walletVersion = null) {
  const defaultWallet = process.env.PLINGS_DEFAULT_WALLET || '1';
  const version = walletVersion || defaultWallet;
  
  // Try version-specific key first
  const versionKey = process.env[`PLINGS_MASTER_KEY_V${version}`];
  if (versionKey) {
    return versionKey;
  }
  
  // Fallback to single key (v1 compatibility)
  if (version === '1' && process.env.PLINGS_MASTER_KEY) {
    return process.env.PLINGS_MASTER_KEY;
  }
  
  throw new Error(`Master key not found for wallet version ${version}`);
}

Vercel Variable Limits:

Maximum: 64 environment variables
Current Usage: ~10 variables for core services
Available for Wallets: ~50 variables
Maximum Wallet Versions: ~25 wallet versions (2 variables per wallet)

This provides decades of wallet lifecycle management capacity.

Key Generation

# Generate new master key
node -e "
const crypto = require('crypto');
const bs58 = require('bs58');
const masterKey = crypto.randomBytes(32);
console.log('PLINGS_MASTER_KEY=' + bs58.encode(masterKey));
"

Deployment Checklist

All environment variables configured
Separate keys for each environment
Master key security verified
Database connections tested
Frontend/backend integration verified
Error tracking configured

For detailed implementation, see Vercel Key Management Guide.

Status: Updated for three-tier key management strategy.

Search Results: