Environment Variables

Referenced Files in This Document - config.py - server.py - docker-compose.yml - Dockerfile - chains.yaml - crypto.py - base.py - manager.py - engine.py - listener.py - README.md

Introduction

This document explains how environment variables are defined, loaded, validated, and used across the cTrip Payment Gateway. It covers required and optional variables, precedence rules, sensitive data handling, development versus production differences, and practical configuration scenarios. It also documents configuration validation and error handling for missing or invalid values.

Project Structure

The configuration system centers around a single settings class that loads values from environment variables and a .env file, with defaults applied when variables are absent. Services and workers consume these settings to configure databases, blockchains, Redis, and cryptographic keys.

graph TB subgraph "Runtime" S["FastAPI App
server.py"] W["ARQ Workers
listener.py"] end subgraph "Config Layer" C["Settings (pydantic-settings)
app/core/config.py"] E[".env file
loaded by Settings"] end subgraph "External Systems" DB["PostgreSQL / SQLite
app/db/engine.py"] R["Redis
Docker compose"] BC["EVM RPCs
chains.yaml"] end S --> C W --> C C --> DB C --> R C --> BC C -. "loads from" .-> E

Diagram sources - config.py - server.py - engine.py - docker-compose.yml - chains.yaml

Section sources - config.py - server.py - engine.py - docker-compose.yml - chains.yaml

Core Components

This section enumerates all environment variables recognized by the application, their roles, and whether they are required or optional. Defaults are documented where applicable.

Required variables
PRIVATE_KEY: Ethereum private key used for signing transactions. Required in production.
DATABASE_URL: Full database URL for the running environment. Production uses the production URL; development uses the dev URL. The compose file sets this for containers.
REDIS_URL: Redis connection URL for background workers.
Optional variables
ENV: Application environment selector ("development", "production", "testing"). Defaults to "development".
MNEMONIC: HD wallet mnemonic phrase used to derive payment addresses. Defaults to a test phrase.
CHAINS_YAML_PATH: Path to the YAML file containing chain configurations. Defaults to "chains.yaml".
WEBHOOK_URL: Global webhook URL for payment notifications.
WEBHOOK_SECRET: Secret key for signing webhook payloads.
SECRET_KEY: Application secret for cryptography. Must be changed in production.

Notes: - The settings class loads variables from a .env file located at the repository root and applies defaults when variables are missing. - The application selects the appropriate database URL based on the environment setting.

Section sources - config.py - docker-compose.yml - engine.py

Architecture Overview

The configuration loading pipeline and runtime usage are illustrated below.

sequenceDiagram participant Env as "Environment Variables" participant DotEnv as ".env file" participant Settings as "Settings (pydantic-settings)" participant App as "FastAPI App" participant Worker as "ARQ Worker" Env-->>DotEnv : "Compose/runtime sets variables" DotEnv-->>Settings : "Loaded via env_file" Settings-->>App : "Expose validated fields" Settings-->>Worker : "Expose validated fields" App->>Settings : "Access env, database_url, mnemonic" Worker->>Settings : "Access env, database_url, mnemonic"

Diagram sources - config.py - server.py - listener.py

Detailed Component Analysis

Configuration Loading Mechanism and Precedence

Source order and precedence:
Environment variables set at runtime override values in the .env file.
The .env file is loaded automatically by the settings class.
Defaults are applied when neither environment nor .env provide a value.
Case sensitivity:
Environment variable names are case-insensitive.
Prefix and extras:
No environment variable prefix is expected.
Unknown variables are ignored.
Validation:
Private key is validated as a valid Ethereum private key.
Secret key must be changed from default in production.

flowchart TD Start(["Startup"]) --> LoadEnv["Load .env file"] LoadEnv --> MergeEnv["Merge runtime environment variables"] MergeEnv --> ApplyDefaults["Apply defaults for missing values"] ApplyDefaults --> Validate["Validate required and typed fields"] Validate --> Ready(["Settings ready for use"])

Diagram sources - config.py - config.py

Section sources - config.py - config.py

Sensitive Data Management

Private key handling:
Stored as a secret field and validated as a valid Ethereum private key.
Required in production; must not be committed to source control.
Mnemonic phrase storage:
Used to derive HD wallet payment addresses.
Defaults to a test mnemonic for development; must be replaced with a secure, offline-backed mnemonic in production.
Credential rotation:
Rotate SECRET_KEY in production by replacing the value in .env or environment.
Replace PRIVATE_KEY periodically using secure key management systems.

classDiagram class Settings { +env +database_url_prod +database_url_dev +redis_url +chains_yaml_path +mnemonic +webhook_url +webhook_secret +private_key +secret_key +database_url() +chains() } class HDWalletManager { +get_address(index) +get_multiple_addresses(count, start_index) +get_mnemonic() } Settings --> HDWalletManager : "uses mnemonic"

Diagram sources - config.py - crypto.py

Section sources - config.py - config.py - crypto.py

Database Configuration

Dynamic selection:
The effective database URL is chosen based on the environment setting.
URL transformation:
The engine module converts PostgreSQL and SQLite URLs to async variants for async database operations.
Compose defaults:
The compose file sets DATABASE_URL for app and worker services.

flowchart TD A["env == production?"] --> |Yes| P["Use database_url_prod"] A --> |No| D["Use database_url_dev"] P --> U["Transform to async URL if needed"] D --> U U --> Conn["Create engines and sessions"]

Diagram sources - config.py - engine.py

Section sources - config.py - config.py - engine.py - docker-compose.yml

Blockchain RPC Configuration

Chain definitions:
Chains are loaded from a YAML file; each chain defines a name and RPC URL.
Fallback:
If the YAML file is missing or empty, a default Anvil chain is used with the RPC URL from settings.
Runtime usage:
Blockchains are instantiated per configured chain and used by workers and services.

sequenceDiagram participant Settings as "Settings.chains" participant Manager as "get_blockchains()" participant BC as "Blockchain instances" Settings-->>Manager : "List of chain configs" Manager->>BC : "Instantiate per chain (Ethereum/BSCTest/Anvil/default)" BC-->>Manager : "Map of chain_name -> BlockchainBase"

Diagram sources - config.py - manager.py - chains.yaml

Section sources - config.py - config.py - manager.py - chains.yaml

Redis and Background Workers

Redis URL:
Provided via REDIS_URL environment variable and used by ARQ workers.
Worker startup:
Workers are started separately via python run_worker.py and inherit the same environment configuration.
In Docker Compose, the worker service runs python run_worker.py.

Section sources - config.py - docker-compose.yml - listener.py

Webhook Configuration

Optional webhook URL and secret:
Used to sign and deliver payment notifications.
Not enforced as required; absence disables webhook features.

Section sources - config.py

Development vs Production Differences

Environment mode:
ENV controls which database URL is selected and whether strict secret key validation applies.
Production requirements:
PRIVATE_KEY must be present and valid.
SECRET_KEY must not match default values.
Development defaults:
DATABASE_URL_DEV points to a local SQLite database.
MNEMONIC defaults to a test phrase.

Section sources - config.py - config.py - config.py - engine.py

Dependency Analysis

The following diagram shows how configuration is consumed across the system.

graph LR Settings["Settings
app/core/config.py"] --> Engine["DB Engines
app/db/engine.py"] Settings --> Manager["Blockchains Factory
app/blockchain/manager.py"] Settings --> Crypto["HDWalletManager
app/utils/crypto.py"] Settings --> App["FastAPI App
server.py"] Settings --> Worker["ARQ Workers
app/workers/*.py"] Settings --> Redis["Redis URL
compose env"] Settings --> DB["PostgreSQL/SQLite
compose env"]

Diagram sources - config.py - engine.py - manager.py - crypto.py - server.py - listener.py - docker-compose.yml

Section sources - config.py - engine.py - manager.py - crypto.py - server.py - listener.py - docker-compose.yml

Performance Considerations

Keep RPC endpoints responsive; consider multiple RPC URLs for redundancy.
Use async database engines for throughput; ensure connection pooling settings match workload.
Avoid frequent private key rotations during peak operation; schedule maintenance windows.

Troubleshooting Guide

Common issues and resolutions:

Missing PRIVATE_KEY in production
Symptom: Validation error indicating invalid private key or missing required value.
Resolution: Set PRIVATE_KEY in .env or environment and ensure it is a valid Ethereum private key.
Invalid SECRET_KEY in production
Symptom: Validation error requiring a non-default secret key.
Resolution: Change SECRET_KEY to a strong, random value in .env or environment.
Database connectivity errors
Symptom: Connection failures when starting the app or workers.
Resolution: Verify DATABASE_URL matches the running database service; confirm network connectivity and credentials.
Blockchain connectivity errors
Symptom: Failure to connect to RPC endpoints.
Resolution: Confirm rpc_url in chains.yaml is reachable and valid.
Redis connectivity errors for workers
Symptom: Workers cannot connect to Redis.
Resolution: Verify REDIS_URL points to the running Redis instance.
HD wallet mnemonic issues
Symptom: Unexpected payment addresses or mnemonic-related errors.
Resolution: Replace MNEMONIC with a secure, offline-backed phrase in production.
Environment mode misconfiguration
Symptom: Wrong database URL selected or unexpected behavior.
Resolution: Set ENV to "development", "production", or "testing" appropriately.

Section sources - config.py - engine.py - manager.py - docker-compose.yml

Conclusion

The cTrip Payment Gateway centralizes configuration through a validated settings class that reads from .env and environment variables, with sensible defaults and strict validation for production safety. By following the guidance here—securing secrets, validating configuration, and using environment-specific overrides—you can reliably operate the system across development and production.

Appendices

Environment Variable Reference

PRIVATE_KEY: Ethereum private key (required in production)
DATABASE_URL: Database URL for app and workers
REDIS_URL: Redis connection URL for workers
ENV: Environment mode ("development", "production", "testing")
MNEMONIC: HD wallet mnemonic phrase
CHAINS_YAML_PATH: Path to chain configuration YAML
WEBHOOK_URL: Webhook notification URL
WEBHOOK_SECRET: Webhook signature secret
SECRET_KEY: Application cryptography secret (must change in production)

Section sources - config.py - docker-compose.yml

Configuration Loading Flow

flowchart TD A["Set process environment"] --> B["Settings loads .env"] B --> C["Merge runtime env vars"] C --> D["Apply defaults"] D --> E["Validate fields"] E --> F["Settings ready"]

Diagram sources - config.py

Example Scenarios

Development with local services
Use compose defaults for DATABASE_URL, REDIS_URL, PRIVATE_KEY, and MNEMONIC.
Keep ENV=development to select the dev database URL.
Production with managed services
Provide DATABASE_URL pointing to PostgreSQL, REDIS_URL to Redis, PRIVATE_KEY, SECRET_KEY, and a secure MNEMONIC.
Set ENV=production to enforce secret key validation and select the production database URL.
Multi-chain configuration
Define chains in chains.yaml with names and RPC URLs.

Section sources - docker-compose.yml - manager.py - chains.yaml - engine.py - config.py