Environment Variables

Overview

ShopStack Platform uses environment variables to configure both the Python and Node.js services. This page documents all available variables with their default values and usage.

Python Service Variables

The Python service uses Flask and supports multiple configuration environments.

Flask Environment

FLASK_ENV

string

default:"development"

Flask environment mode. Controls which configuration class is loaded.Options:

development - Development mode with debug enabled
staging - Staging mode with debug disabled
production - Production mode with debug disabled
testing - Testing mode with in-memory SQLite database

Example:

FLASK_ENV=staging

Security

SECRET_KEY

string

default:"dev-secret-key"

Secret key for Flask session encryption and JWT token signing. Used for both SECRET_KEY and JWT_SECRET_KEY in the application.

Always use a strong, randomly generated secret in production. Never use the default value.

Example:

SECRET_KEY=supersecretkey123

Generate a secure key:

python -c "import secrets; print(secrets.token_hex(32))"

Database Configuration (Development)

Used when FLASK_ENV=development:

DATABASE_USER

string

default:"appuser"

PostgreSQL username for database connection in development mode.Example:

DATABASE_USER=appuser

DATABASE_PASSWORD

string

default:"apppassword"

PostgreSQL password for database connection in development mode.Example:

DATABASE_PASSWORD=apppassword

DATABASE_PORT

string

default:"5432"

PostgreSQL port for database connection in development mode.Example:

DATABASE_PORT=5432

DATABASE_NAME

string

default:"ecommerce"

PostgreSQL database name in development mode.Example:

DATABASE_NAME=ecommerce

Database Configuration (Staging/Production)

Used when FLASK_ENV=staging or FLASK_ENV=production:

DB_USER

string

default:"appuser"

PostgreSQL username for database connection in staging/production mode.Example:

DB_USER=appuser

DB_PASS

string

default:"apppassword"

PostgreSQL password for database connection in staging/production mode.Example:

DB_PASS=apppassword

DB_HOST

string

default:"localhost"

PostgreSQL host for database connection in staging/production mode.Example:

DB_HOST=postgres

DB_PORT

string

default:"5432"

PostgreSQL port for database connection in staging/production mode.Example:

DB_PORT=5432

DB_NAME

string

default:"ecommerce"

PostgreSQL database name in staging/production mode.Example:

DB_NAME=ecommerce

Database Host Configuration: In development mode, the host is hardcoded to localhost. In staging/production modes, use the DB_HOST variable documented above to specify the PostgreSQL host.

Caching

REDIS_URL

string

default:"redis://localhost:6379/0"

Redis connection URL for caching. The Python service uses Redis database 0.Format: redis://[host]:[port]/[db]Example:

REDIS_URL=redis://redis:6379/0

Python Service Configuration Summary

The Python service builds its database connection string based on the FLASK_ENV setting: Development (FLASK_ENV=development):

postgresql://[DATABASE_USER]:[DATABASE_PASSWORD]@localhost:[DATABASE_PORT]/[DATABASE_NAME]

Staging/Production (FLASK_ENV=staging or FLASK_ENV=production):

postgresql://[DB_USER]:[DB_PASS]@[DB_HOST]:[DB_PORT]/[DB_NAME]

Testing (FLASK_ENV=testing):

sqlite:///:memory:

Node.js Service Variables

The Node.js service uses environment variables for database, JWT, and server configuration.

Server Configuration

PORT

string

default:"3000"

Port number for the Node.js server to listen on.Example:

PORT=3000

NODE_ENV

string

default:"development"

Node.js environment mode. Controls logging and other environment-specific behavior.Options:

development - Enables SQL query logging
production - Disables SQL query logging

Example:

NODE_ENV=production

Database Configuration

DB_HOST

string

default:"localhost"

PostgreSQL host for database connection.Example:

DB_HOST=postgres

DB_PORT

string

default:"5432"

PostgreSQL port for database connection.Example:

DB_PORT=5432

DB_USER

string

default:"appuser"

PostgreSQL username for database connection.Example:

DB_USER=appuser

DB_PASSWORD

string

default:"apppassword"

PostgreSQL password for database connection.Example:

DB_PASSWORD=apppassword

DB_NAME

string

default:"ecommerce"

PostgreSQL database name.Example:

DB_NAME=ecommerce

Security

JWT_SECRET

string

default:"dev-secret-key"

Secret key for JWT token signing and verification. JWT tokens expire after 24 hours.

Always use a strong, randomly generated secret in production. Never use the default value.

Example:

JWT_SECRET=anothersecretkey456

Generate a secure key:

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

Caching

REDIS_URL

string

default:"redis://localhost:6379/0"

Redis connection URL for caching. The Node.js service uses Redis database 1.Format: redis://[host]:[port]/[db]Example:

REDIS_URL=redis://redis:6379/1

Docker Compose Environment

When using Docker Compose, environment variables are set in the docker-compose.yml file:

Python Service Docker Environment

python-service:
  environment:
    - DATABASE_HOST=postgres
    - DATABASE_PORT=5432
    - DATABASE_USER=appuser
    - DATABASE_PASSWORD=apppassword
    - DATABASE_NAME=ecommerce
    - REDIS_URL=redis://redis:6379/0
    - FLASK_ENV=staging
    - SECRET_KEY=supersecretkey123

Node Service Docker Environment

node-service:
  environment:
    - DB_HOST=postgres
    - DB_PORT=5432
    - DB_USER=appuser
    - DB_PASSWORD=apppassword
    - DB_NAME=ecommerce
    - REDIS_URL=redis://redis:6379/1
    - NODE_ENV=production
    - JWT_SECRET=anothersecretkey456

Using .env Files

For local development, create a .env file in each service directory:

Python Service .env

# python-service/.env
FLASK_ENV=development
SECRET_KEY=dev-secret-key
DATABASE_USER=appuser
DATABASE_PASSWORD=apppassword
DATABASE_PORT=5432
DATABASE_NAME=ecommerce
REDIS_URL=redis://localhost:6379/0

Node Service .env

# node-service/.env
NODE_ENV=development
PORT=3000
DB_HOST=localhost
DB_PORT=5432
DB_USER=appuser
DB_PASSWORD=apppassword
DB_NAME=ecommerce
JWT_SECRET=dev-secret-key
REDIS_URL=redis://localhost:6379/1

Never commit .env files to version control. Add them to .gitignore.

Environment-Specific Configuration

Development

Optimal settings for local development:

# Python Service
FLASK_ENV=development
SECRET_KEY=dev-secret-key
DATABASE_USER=appuser
DATABASE_PASSWORD=apppassword
DATABASE_PORT=5432
DATABASE_NAME=ecommerce

# Node Service
NODE_ENV=development
JWT_SECRET=dev-secret-key

Staging

Settings for staging environment:

# Python Service
FLASK_ENV=staging
SECRET_KEY=<strong-secret-key>
DB_HOST=postgres
DB_USER=appuser
DB_PASS=<strong-password>
DB_NAME=ecommerce

# Node Service
NODE_ENV=production
JWT_SECRET=<strong-secret-key>
DB_HOST=postgres
DB_PASSWORD=<strong-password>

Production

Settings for production environment:

# Python Service
FLASK_ENV=production
SECRET_KEY=<strong-secret-key>
DB_HOST=<production-db-host>
DB_USER=<production-user>
DB_PASS=<strong-password>
DB_NAME=ecommerce
REDIS_URL=redis://<production-redis-host>:6379/0

# Node Service
NODE_ENV=production
JWT_SECRET=<strong-secret-key>
DB_HOST=<production-db-host>
DB_USER=<production-user>
DB_PASSWORD=<strong-password>
DB_NAME=ecommerce
REDIS_URL=redis://<production-redis-host>:6379/1

Security Best Practices

Secret Management

Never use default secrets in production

Generate strong random secrets:

# Python
python -c "import secrets; print(secrets.token_hex(32))"

# Node.js
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

Use secret management tools: AWS Secrets Manager, HashiCorp Vault, etc.
Rotate secrets regularly

Database Credentials

Use strong passwords: Minimum 16 characters with mixed case, numbers, and symbols
Restrict database access: Only allow connections from application services
Use SSL/TLS: Enable SSL connections for production databases
Principle of least privilege: Grant only necessary permissions

Environment Isolation

Separate credentials per environment: Different secrets for dev, staging, and production
Network isolation: Use private networks for database and Redis
Access control: Implement proper firewall rules and security groups

Troubleshooting

Database Connection Issues

If services can’t connect to the database:

Verify environment variables: Check that DB_HOST, DB_PORT, DB_USER, DB_PASSWORD, and DB_NAME are correct
Check network connectivity: Ensure services can reach the database host

Verify credentials: Test database login manually:

psql -h localhost -U appuser -d ecommerce

Configuration Mismatches

For Python service configuration issues:

Development mode: Uses DATABASE_* variables
Staging/Production mode: Uses DB_* variables (except DATABASE_HOST)
Ensure you’re setting the correct variables for your FLASK_ENV

Redis Connection Issues

If caching isn’t working:

Check Redis URL format: Should be redis://host:port/db
Verify Redis is running: redis-cli ping should return PONG
Check database separation: Python uses DB 0, Node uses DB 1

Next Steps

Learn about Docker deployment
Review the Python API documentation
Review the Node API documentation
Set up monitoring and logging for your deployment

Get Started

Services

Deployment

Testing

Overview

Python Service Variables

Flask Environment

Security

Database Configuration (Development)

Database Configuration (Staging/Production)

Caching

Python Service Configuration Summary

Node.js Service Variables

Server Configuration

Database Configuration

Security

Caching

Docker Compose Environment

Python Service Docker Environment

Node Service Docker Environment

Using .env Files

Python Service .env

Node Service .env

Environment-Specific Configuration

Development

Staging

Production

Security Best Practices

Secret Management

Database Credentials

Environment Isolation

Troubleshooting

Database Connection Issues

Configuration Mismatches

Redis Connection Issues

Next Steps

Build docs developers (and LLMs) love

Get Started

Services

Deployment

Testing

​Overview

​Python Service Variables

​Flask Environment

​Security

​Database Configuration (Development)

​Database Configuration (Staging/Production)

​Caching

​Python Service Configuration Summary

​Node.js Service Variables

​Server Configuration

​Database Configuration

​Security

​Caching

​Docker Compose Environment

​Python Service Docker Environment

​Node Service Docker Environment

​Using .env Files

​Python Service .env

​Node Service .env

​Environment-Specific Configuration

​Development

​Staging

​Production

​Security Best Practices

​Secret Management

​Database Credentials

​Environment Isolation

​Troubleshooting

​Database Connection Issues

​Configuration Mismatches

​Redis Connection Issues

​Next Steps

Build docs developers (and LLMs) love

Overview

Python Service Variables

Flask Environment

Security

Database Configuration (Development)

Database Configuration (Staging/Production)

Caching

Python Service Configuration Summary

Node.js Service Variables

Server Configuration

Database Configuration

Security

Caching

Docker Compose Environment

Python Service Docker Environment

Node Service Docker Environment

Using .env Files

Python Service .env

Node Service .env

Environment-Specific Configuration

Development

Staging

Production

Security Best Practices

Secret Management

Database Credentials

Environment Isolation

Troubleshooting

Database Connection Issues

Configuration Mismatches

Redis Connection Issues

Next Steps