Skip to main content
EverShop uses environment variables for sensitive configuration and deployment settings. This guide covers all available environment variables.

​
Setting Environment Variables

​
Local Development

Create a .env file in your project root: 
DB_HOST="localhost"
DB_PORT="5432"
DB_NAME="evershop"
DB_USER="postgres"
DB_PASSWORD="your_password"
DB_SSLMODE="disable"

​
Docker Deployment

Set variables in docker-compose.yml: 
services:
  app:
    environment:
      DB_HOST: database
      DB_PORT: 5432
      DB_NAME: evershop
      DB_USER: postgres
      DB_PASSWORD: secure_password

​
Production Servers

Set variables in your hosting environment (Heroku, AWS, etc.) or use a process manager like PM2.

​
Database Configuration

​
DB_HOST
string
required
PostgreSQL database hostDefault: localhostExample: database (Docker), db.example.com (remote)
​
DB_PORT
number
required
PostgreSQL database portDefault: 5432
​
DB_NAME
string
required
Database name for EverShopDefault: evershop
​
DB_USER
string
required
Database usernameDefault: postgres
​
DB_PASSWORD
string
required
Database password
Never commit this to version control
​
DB_SSLMODE
enum
SSL mode for database connectionOptions:
  • disable - No SSL connection
  • require - SSL required
  • prefer - Prefer SSL if available
  • verify-ca - Verify certificate authority
  • verify-full - Full SSL verification
  • no-verify - SSL without verification
Default: disable
​
DB_SSLROOTCERT
string
Path to SSL root certificate fileRequired when using verify-ca or verify-full SSL modes.Example: /path/to/ca-cert.pem
​
DB_SSLCERT
string
Path to SSL client certificate fileExample: /path/to/client-cert.pem
​
DB_SSLKEY
string
Path to SSL client key fileExample: /path/to/client-key.pem

​
Server Configuration

​
PORT
number
HTTP server portDefault: 3000Example: 8080, 80
​
NODE_ENV
enum
Node.js environment modeOptions:
  • development - Development mode with hot reload
  • production - Production mode with optimizations
  • test - Testing mode
Default: development

​
JWT Authentication

EverShop uses JWT tokens for authentication with separate configurations for admin and customer sessions.
​
JWT_ISSUER
string
JWT token issuer identifierDefault: evershop

​
Admin JWT Configuration

​
JWT_ADMIN_SECRET
string
required
Secret key for admin access tokens
Must be at least 32 characters long. Generate a secure random string.
Example: your-secret-admin-key-min-32-chars
​
JWT_ADMIN_REFRESH_SECRET
string
required
Secret key for admin refresh tokensShould be different from JWT_ADMIN_SECRET.Example: your-refresh-admin-key-min-32-chars
​
JWT_ADMIN_TOKEN_EXPIRY
number
Admin access token expiration time in secondsDefault: 900 (15 minutes)
​
JWT_ADMIN_REFRESH_TOKEN_EXPIRY
number
Admin refresh token expiration time in secondsDefault: 54000 (15 hours)

​
Customer JWT Configuration

​
JWT_CUSTOMER_SECRET
string
required
Secret key for customer access tokens
Must be at least 32 characters long and different from admin secrets.
Example: your-secret-customer-key-min-32-chars
​
JWT_CUSTOMER_REFRESH_SECRET
string
required
Secret key for customer refresh tokensShould be different from JWT_CUSTOMER_SECRET.Example: your-refresh-customer-key-min-32-chars
​
JWT_CUSTOMER_TOKEN_EXPIRY
number
Customer access token expiration time in secondsDefault: 1800 (30 minutes)
​
JWT_CUSTOMER_REFRESH_TOKEN_EXPIRY
number
Customer refresh token expiration time in secondsDefault: 108000 (30 hours)

​
Installation Variables

These variables are used during the npm run setup installation process:
​
ADMIN_FULLNAME
string
Full name of the initial admin userExample: John Doe
​
ADMIN_EMAIL
string
Email address for the initial admin userDefault: [email protected]Example: [email protected]
​
ADMIN_PASSWORD
string
Password for the initial admin userMust meet requirements:
  • At least 8 characters
  • Contains at least one letter
  • Contains at least one digit
Default: 123456 (change this!)

​
Internal Variables

​
ALLOW_CONFIG_MUTATIONS
boolean
Allow configuration changes at runtime
This is used internally and automatically set to false after bootstrap. Do not set manually in production.
Default: false (after startup)

​
Example Configurations

​
Development Environment

# .env file for development
DB_HOST="localhost"
DB_PORT="5432"
DB_NAME="evershop_dev"
DB_USER="postgres"
DB_PASSWORD="devpassword"
DB_SSLMODE="disable"

PORT="3000"
NODE_ENV="development"

# JWT Secrets (generate secure random strings)
JWT_ISSUER="evershop"
JWT_ADMIN_SECRET="dev-admin-secret-key-at-least-32-characters-long"
JWT_ADMIN_REFRESH_SECRET="dev-admin-refresh-key-at-least-32-characters-long"
JWT_CUSTOMER_SECRET="dev-customer-secret-key-at-least-32-characters-long"
JWT_CUSTOMER_REFRESH_SECRET="dev-customer-refresh-key-at-least-32-characters-long"

# Admin user
ADMIN_EMAIL="admin@localhost"
ADMIN_PASSWORD="DevPassword123"
ADMIN_FULLNAME="Admin User"

​
Production Environment

# Production environment variables (set in hosting platform)
DB_HOST="prod-db.example.com"
DB_PORT="5432"
DB_NAME="evershop_production"
DB_USER="evershop_user"
DB_PASSWORD="<use-strong-password>"
DB_SSLMODE="verify-full"
DB_SSLROOTCERT="/etc/ssl/certs/ca-certificate.crt"

PORT="80"
NODE_ENV="production"

# Strong JWT secrets (use a password generator)
JWT_ISSUER="evershop-production"
JWT_ADMIN_SECRET="<generate-strong-secret>"
JWT_ADMIN_REFRESH_SECRET="<generate-strong-secret>"
JWT_ADMIN_TOKEN_EXPIRY="900"
JWT_ADMIN_REFRESH_TOKEN_EXPIRY="86400"

JWT_CUSTOMER_SECRET="<generate-strong-secret>"
JWT_CUSTOMER_REFRESH_SECRET="<generate-strong-secret>"
JWT_CUSTOMER_TOKEN_EXPIRY="3600"
JWT_CUSTOMER_REFRESH_TOKEN_EXPIRY="604800"

​
Docker Compose

version: '3.8'

services:
  app:
    image: evershop/evershop:latest
    environment:
      DB_HOST: database
      DB_PORT: 5432
      DB_NAME: evershop
      DB_USER: evershop
      DB_PASSWORD: ${DB_PASSWORD}
      DB_SSLMODE: disable
      
      NODE_ENV: production
      PORT: 3000
      
      JWT_ISSUER: evershop
      JWT_ADMIN_SECRET: ${JWT_ADMIN_SECRET}
      JWT_ADMIN_REFRESH_SECRET: ${JWT_ADMIN_REFRESH_SECRET}
      JWT_CUSTOMER_SECRET: ${JWT_CUSTOMER_SECRET}
      JWT_CUSTOMER_REFRESH_SECRET: ${JWT_CUSTOMER_REFRESH_SECRET}
    ports:
      - "3000:3000"

​
Security Best Practices

Use Strong Secrets

Generate JWT secrets using a cryptographically secure random generator:
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

Never Commit Secrets

Add .env to your .gitignore file:
.env
.env.local
.env.production

Use Environment-Specific Values

Use different secrets for development, staging, and production environments.

Rotate Secrets Regularly

Change JWT secrets and database passwords periodically, especially after team member changes.

​
Troubleshooting

​
JWT Secrets Not Set

If you see errors about missing JWT secrets: 
JWT secret for admin is not configured
Ensure all required JWT environment variables are set:
  • JWT_ADMIN_SECRET
  • JWT_ADMIN_REFRESH_SECRET
  • JWT_CUSTOMER_SECRET
  • JWT_CUSTOMER_REFRESH_SECRET

​
Database Connection Fails

  1. Verify all database credentials are correct
  2. Check that the database server is running
  3. Ensure the database user has proper permissions
  4. Verify SSL mode matches your database configuration

​
Port Already in Use

Change the PORT variable to use a different port: 
PORT=8080

Build docs developers (and LLMs) love

Get started for freeTalk to us