SaleSpider

Appearance

Environment Variables Reference ​

This document provides a comprehensive reference for all environment variables used in SaleSpider. These variables control application behavior, deployment configuration, and system settings.

Table of Contents ​

  1. Deployment Configuration
  2. Application Configuration
  3. Database Configuration
  4. SSL/HTTPS Configuration
  5. Backup Configuration
  6. Cloud Storage Configuration
  7. Development & Debugging
  8. Troubleshooting

Deployment Configuration ​

Core Deployment Settings ​

VariableDefaultDescriptionRequired
COMPOSE_PROJECT_NAMEsalespiderDocker Compose project name prefixYes
COMPOSE_FILE.docker/docker-compose.ymlDocker Compose file to useYes
DOMAINsalespider.localPrimary domain for the applicationYes
HOST_IPautoServer IP address (auto for auto-detection)Yes
HTTP_PORT80HTTP port for the proxyNo
HTTPS_PORT443HTTPS port for the proxyNo

Storage Paths ​

VariableDefaultDescriptionRequired
DATA_PATH./dataBase directory for persistent dataYes
BACKUP_PATH./data/backupsDirectory for backup filesYes

Usage Examples:

bash
# Internal company deployment
DOMAIN=salespider.company.com
HOST_IP=192.168.1.100

# Local development
DOMAIN=salespider.local
HOST_IP=127.0.0.1

Application Configuration ​

Core Application Settings ​

VariableDefaultDescriptionRequired
NODE_ENVproductionNode.js environment (production, development)Yes
APP_PORT3000Port for the Next.js applicationYes
LOG_LEVELinfoLogging level (error, warn, info, debug)No

Security Configuration ​

VariableDefaultDescriptionRequired
JWT_SECRET(none)Secret key for JWT tokens (min 32 chars)Yes
TOKEN_EXPIRY12hJWT token expiration timeNo
COOKIE_SECUREtrueEnable secure cookies (HTTPS only)No
APP_URLhttps://salespider.localBase URL for the applicationYes

Admin Account ​

VariableDefaultDescriptionRequired
SUPER_ADMIN_EMAILadmin@salespider.localSuper admin email addressYes
SUPER_ADMIN_PASSWORD(none)Super admin passwordYes

AI Configuration ​

VariableDefaultDescriptionRequired
GEMINI_API_KEY(none)Google Gemini API key for AI featuresNo

Default App Settings ​

These can be overridden through the application UI (Settings page, Super Admin only):

Note on Payment Methods: The available payment methods are defined in the database schema. To add custom payment methods:

  1. Update prisma/schema.prisma to add new values to the PaymentMode enum
  2. Update src/lib/constants.ts to add the new payment method to PAYMENT_MODE_VALUES and PAYMENT_METHODS
  3. Create and run a Prisma migration: npx prisma migrate dev --name add_payment_method
  4. Rebuild and redeploy the application

Available Payment Methods (defined in schema):

  • CASH - Cash payments
  • CARD - Card/credit card payments
  • BANK_TRANSFER - Bank transfer payments
  • CRYPTO - Cryptocurrency payments
  • OTHER - Other payment methods
VariableDefaultDescription
APP_NAMESaleSpiderApplication display name
APP_LOGO(empty)URL or path to application logo
PRIMARY_COLOR#3b82f6Primary theme color (hex)
SECONDARY_COLOR#10b981Secondary theme color (hex)
ACCENT_COLOR#f59e0bAccent theme color (hex)
CURRENCYNGNDefault currency code
CURRENCY_SYMBOL₦Currency symbol
VAT_PERCENTAGE7.5Default VAT/tax percentage
TIMEZONEAfrica/LagosDefault timezone
DATE_FORMATdd/MM/yyyyDate display format
TIME_FORMATHH:mmTime display format
LANGUAGEenDefault language (en, fr, es, de)
THEMElightDefault theme (light, dark)
MAINTENANCE_MODEfalseEnable maintenance mode
SHOW_DELETED_PRODUCTSfalseShow deleted products in lists
ENABLED_PAYMENT_METHODSCASH,CARD,BANK_TRANSFER,CRYPTO,OTHERComma-separated payment methods (must match Prisma schema enum values)

Client-Side Settings ​

These variables are exposed to the browser (prefixed with NEXT_PUBLIC_):

All the above app settings have corresponding NEXT_PUBLIC_ versions that make them available on the client side.

Feature Flags ​

VariableDefaultDescription
ENABLE_ANALYTICSfalseEnable analytics features
ENABLE_REPORTStrueEnable reporting features
OFFLINE_MODEtrueEnable offline functionality

Performance Settings ​

VariableDefaultDescription
APP_MEMORY_LIMIT2GDocker memory limit for app container
APP_CPU_LIMIT2.0Docker CPU limit for app container
APP_MEMORY_RESERVATION1GDocker memory reservation for app
APP_CPU_RESERVATION1.0Docker CPU reservation for app
DATABASE_POOL_SIZE10Database connection pool size
DATABASE_TIMEOUT30000Database query timeout (ms)
CACHE_TTL3600Cache time-to-live (seconds)

Database Configuration ​

PostgreSQL Core Settings ​

VariableDefaultDescriptionRequired
POSTGRES_HOSTpostgresPostgreSQL server hostname (used by setup/backup services)Yes
POSTGRES_DBsalespiderDatabase nameYes
POSTGRES_USERpostgresDatabase usernameYes
POSTGRES_PASSWORD(none)Database passwordYes
POSTGRES_PORT5432Database portYes
DATABASE_URL(constructed)Full database connection stringYes

Note: The backup service internally maps these to standard PostgreSQL client variables (PGHOST, PGUSER, PGPASSWORD, PGPORT). You don't need to set those directly.

PostgreSQL Performance Tuning ​

VariableDefaultDescription
POSTGRES_MEMORY_LIMIT1GDocker memory limit
POSTGRES_CPU_LIMIT1.0Docker CPU limit
POSTGRES_MEMORY_RESERVATION512MDocker memory reservation
POSTGRES_CPU_RESERVATION0.5Docker CPU reservation
POSTGRES_SHARED_BUFFERS256MBPostgreSQL shared buffers
POSTGRES_EFFECTIVE_CACHE_SIZE1GBPostgreSQL cache size hint
POSTGRES_WORK_MEM4MBMemory for sort/hash operations
POSTGRES_MAINTENANCE_WORK_MEM64MBMemory for maintenance operations
POSTGRES_MAX_CONNECTIONS100Maximum concurrent connections
POSTGRES_MAX_WAL_SENDERS3Maximum WAL sender processes
POSTGRES_WAL_KEEP_SIZE1GBWAL retention size

PostgreSQL Logging ​

VariableDefaultDescription
POSTGRES_LOG_STATEMENTnoneLog SQL statements (none, ddl, mod, all)
POSTGRES_LOG_MIN_DURATION_STATEMENT1000Log slow queries (ms, -1 to disable)

SSL/HTTPS Configuration ​

VariableDefaultDescription
SSL_ENABLEDtrueEnable SSL/HTTPS
FORCE_HTTPStrueRedirect HTTP to HTTPS
SECURITY_HEADERStrueEnable security headers
HSTS_ENABLEDtrueEnable HTTP Strict Transport Security
HSTS_MAX_AGE31536000HSTS max age (seconds)
RATE_LIMIT_ENABLEDtrueEnable rate limiting
RATE_LIMIT_REQUESTS100Rate limit requests per window
RATE_LIMIT_WINDOW1mRate limit time window

Backup Configuration ​

pgBackRest Settings ​

Note: Backup configuration only applies to self-hosted database deployments. For hosted database providers (Neon, Supabase, etc.), set PGBACKREST_REPO1_TYPE=none and SETUP_BACKUP=false as the provider manages backups.

VariableDefaultDescriptionRequired
PGBACKREST_REPO1_TYPEnoneBackup repository type (see details below)Yes
PGBACKREST_REPO1_PATH/var/lib/pgbackrestLocal backup path (used with posix type)Conditional
BACKUP_SCHEDULE_FULL0 2 * * 0Full backup cron schedule (weekly at 2 AM Sunday)No
BACKUP_RETENTION_FULL7Number of full backups to retainNo
BACKUP_RETENTION_DIFF3Number of differential backups to retainNo

PGBACKREST_REPO1_TYPE Values ​

  • none (default): No backup system. Fastest setup, no cloud storage required. Recommended for:

    • Initial testing and development
    • Hosted database deployments (provider manages backups)
    • Environments where backups are handled externally

  • posix: Local filesystem backups. Stores backups on the local disk or mounted volume. Recommended for:

    • Self-hosted deployments with dedicated backup storage
    • When using external drives or network-attached storage (NAS)
    • Important: Use a separate partition or external drive to avoid filling the system disk
    • Required variables: PGBACKREST_REPO1_PATH

  • s3: AWS S3 cloud backups. Stores backups in Amazon S3 or S3-compatible storage. Recommended for:

    • Production deployments requiring off-site backups
    • Automated disaster recovery scenarios
    • Required variables: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_REGION, AWS_S3_BUCKET
    • Optional variables: AWS_S3_ENDPOINT (for S3-compatible services)

  • azure: Azure Blob Storage backups. Stores backups in Microsoft Azure. Recommended for:

    • Azure-hosted deployments
    • Organizations using Azure infrastructure
    • Required variables: AZURE_STORAGE_ACCOUNT, AZURE_STORAGE_KEY, AZURE_STORAGE_CONTAINER

  • gcs: Google Cloud Storage backups. Stores backups in Google Cloud. Recommended for:

    • Google Cloud-hosted deployments
    • Organizations using Google Cloud infrastructure
    • Required variables: GCS_BUCKET, GCS_KEY (service account JSON)

Backup Resource Limits ​

VariableDefaultDescription
BACKUP_MEMORY_LIMIT512MDocker memory limit for backup container
BACKUP_CPU_LIMIT0.5Docker CPU limit for backup container
BACKUP_MEMORY_RESERVATION256MDocker memory reservation
BACKUP_CPU_RESERVATION0.25Docker CPU reservation

Cloud Storage Configuration ​

Note: These variables are only required when using cloud-based backups with self-hosted databases. Not applicable for hosted database deployments.

AWS S3 (set PGBACKREST_REPO1_TYPE=s3) ​

Required for S3 backups only. These variables must be set when PGBACKREST_REPO1_TYPE=s3.

VariableDefaultDescriptionRequired
AWS_ACCESS_KEY_ID(none)AWS access keyYes
AWS_SECRET_ACCESS_KEY(none)AWS secret keyYes
AWS_REGIONeu-north-1AWS regionYes
AWS_S3_BUCKET(none)S3 bucket nameYes
AWS_S3_ENDPOINTs3.eu-north-1.amazonaws.comS3 endpoint URL (for S3-compatible services)No

Azure Blob Storage (set PGBACKREST_REPO1_TYPE=azure) ​

Required for Azure backups only. These variables must be set when PGBACKREST_REPO1_TYPE=azure.

VariableDefaultDescriptionRequired
AZURE_STORAGE_ACCOUNT(none)Azure storage account nameYes
AZURE_STORAGE_KEY(none)Azure storage account keyYes
AZURE_STORAGE_CONTAINER(none)Azure blob container nameYes

Google Cloud Storage (set PGBACKREST_REPO1_TYPE=gcs) ​

Required for GCS backups only. These variables must be set when PGBACKREST_REPO1_TYPE=gcs.

VariableDefaultDescriptionRequired
GCS_BUCKET(none)GCS bucket nameYes
GCS_KEY(none)GCS service account key (JSON)Yes

Development & Debugging ​

Setup Control Variables ​

VariableDefaultDescriptionUse Cases
SKIP_SEEDfalseSkip database seeding during setup• Database already has data
• Redeployment without data loss
• Testing with existing data
FORCE_RESETfalseForce database reset and recreate• Fresh start needed
• Database corruption
• Schema changes require reset
SETUP_BACKUPtrueConfigure backup system during setup• Self-hosted deployments
• Set to false for hosted DB
KEEP_RUNNINGfalseKeep setup containers running after completion• Debugging setup issues
• Inspecting setup logs
• Development troubleshooting

Development Settings ​

VariableDefaultDescription
DEBUGfalseEnable debug mode (set to false in production)
VERBOSE_LOGGINGfalseEnable verbose logging (set to false in production)

Logging ​

VariableDefaultDescription
ACCESS_LOG_ENABLEDtrueEnable access logging
ERROR_LOG_ENABLEDtrueEnable error logging

Troubleshooting ​

Common Setup Issues ​

Database Connection Problems ​

bash
# Check database variables
POSTGRES_PASSWORD=SecurePassword123!
DATABASE_URL="postgresql://postgres:SecurePassword123!@postgres:5432/salespider?schema=public"

# For hosted databases
DATABASE_URL="postgresql://user:pass@host:5432/db?sslmode=require"
SETUP_BACKUP=false

SSL Certificate Issues ​

bash
# Force certificate regeneration
rm -rf .docker/ssl/*
.docker/scripts/setup/setup-ssl.sh

# Disable HTTPS for testing
SSL_ENABLED=false
FORCE_HTTPS=false

Memory Issues ​

bash
# Reduce memory limits for low-memory systems
APP_MEMORY_LIMIT=1G
APP_MEMORY_RESERVATION=512M
POSTGRES_MEMORY_LIMIT=512M
POSTGRES_SHARED_BUFFERS=128MB

Skip Setup Steps ​

bash
# Skip seeding if database has data
SKIP_SEED=true

# Skip backup setup for hosted databases
SETUP_BACKUP=false

# Keep setup container running for debugging
KEEP_RUNNING=true

Development vs Production Settings ​

Development ​

bash
NODE_ENV=development
DEBUG=true
VERBOSE_LOGGING=true
SKIP_SEED=false
DOMAIN=salespider.local
HOST_IP=127.0.0.1

Production ​

bash
NODE_ENV=production
DEBUG=false
VERBOSE_LOGGING=false
SKIP_SEED=true  # After initial deployment
DOMAIN=salespider.company.com
HOST_IP=192.168.1.100

Hosted Database Deployment ​

bash
COMPOSE_FILE=.docker/docker-compose.hosted-db.yml
DATABASE_URL="postgresql://user:pass@host:5432/db?sslmode=require"
SETUP_BACKUP=false

Environment Variable Validation ​

The system validates critical environment variables on startup. Missing required variables will cause deployment to fail with clear error messages.

Required Variables:

  • JWT_SECRET (min 32 characters)
  • SUPER_ADMIN_EMAIL
  • SUPER_ADMIN_PASSWORD
  • POSTGRES_PASSWORD (for self-hosted)
  • DATABASE_URL (for hosted database)

Getting Help ​

If you encounter issues:

  1. Check the logs: docker compose logs
  2. Verify environment variables: docker compose config
  3. Test database connection: make db-test (if available)
  4. Review this documentation for proper variable formats
  5. Check the troubleshooting section for your specific issue

Note: Always secure sensitive variables like passwords and API keys. Never commit .env files to version control.

Released under the MIT License.

Copyright © 2024-present SaleSpider Contributors