Backend Environment Variables

This document provides the authoritative list of all environment variables required to run the Plings backend application. These variables should be placed in a .env file in the root of the Plings-Backend directory for local development.

For deployment environments like Vercel, these should be set as environment variables in the project settings.

1. Supabase

These variables connect the backend to the Supabase project for PostgreSQL database access, user authentication, and storage.

Variable Name	Description	Example
`SUPABASE_URL`	The unique URL for your Supabase project.	`https://<your-project-ref>.supabase.co`
`SUPABASE_ANON_KEY`	The public “anonymous” key for your project.	`ey...`
`SUPABASE_DB_URL`	The direct connection string for the PostgreSQL database. Important: It must include the password for the `postgres` user.	`postgresql://postgres:<your-password>@db.<project-ref>.supabase.co:5432/postgres`

2. Neo4j Aura

These variables connect the backend to the Neo4j Aura graph database, which stores the core object graph.

Variable Name	Description	Example
`NEO4J_URI`	The connection URI for your Neo4j Aura instance.	`neo4j+s://<id>.databases.neo4j.io`
`NEO4J_USER`	The username for the database. This is typically `neo4j`.	`neo4j`
`NEO4J_PASSWORD`	The password for your Neo4j database user.	`your-secure-password`

3. General Settings

Variable Name	Description	Default
`DEBUG`	If set to `true`, this enables verbose SQL query logging by printing every database query to the console. This is useful for debugging database interactions. Note: This does not control the GraphQL Playground interface.	`false`

4. HD Wallet Key Management

These variables manage the cryptographic keys used for Plings’ HD (Hierarchical Deterministic) wallet system, which generates unique identifiers for all physical objects.

Variable Name	Description	Security Level	Example
`PLINGS_MASTER_KEY`	CRITICAL: Base58-encoded master private key for HD wallet derivation. This key is used to generate all product identifiers.	TOP SECRET	`5KYZdUEo39z3FPLjCKpxKkGXstPbqGiELQgSXzFm9ysh`

Security Requirements

Master Key Security:

Never commit to version control
Use different keys for dev/staging/production
Manage wallet versions strategically (not quarterly rotation)
Restrict team access
Enable audit logging

Critical Note: HD wallet master keys are NOT rotated like traditional API keys. Master key rotation creates a completely new wallet version with different identifier space. Instead, use planned wallet versioning for security lifecycle management.

Key Generation:

# Generate a 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));
"

Environment-Specific Keys:

Development: Use dedicated development key
Staging: Use separate staging key
Production: Use unique production key

Key Management Implementation

This master key is used in the Initial Tier of Plings’ three-tier key management strategy:

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

For detailed implementation, see Vercel Key Management Guide.

Technical Note: GraphQL Debug Mode

It is important to know that the GraphQL application itself is currently hardcoded to run in its own “debug mode” within app/graphql.py. This is what enables the interactive GraphiQL Playground in your browser and provides detailed error stack traces in API responses.

This GraphQL-specific debug mode is independent of the DEBUG environment variable and is always active in the current codebase.

Search Results: