Environment Configuration
The FreightFlow ecosystem relies on environment variables for service discovery, security orchestration, and terminal connectivity. This guide details the configuration for both the Backend and the Scraper services.
WARNING
Keep your .env files secure. Never commit them to version control. Replace the placeholders below with your actual credentials.
1. FreightFlow Backend Configuration
The backend manages the primary logic, database, and task orchestration.
Core Configuration
| Variable | Description | Default / Example |
|---|---|---|
ENVIRONMENT | Deployment mode (development or production). | development |
DEBUG | Enables detailed error logging. | True |
SECRET_KEY | Key for JWT signing. Generate using openssl rand -hex 32. | <SHARED_SECRET_KEY> |
ACCESS_TOKEN_EXPIRE_MINUTES | JWT token validity duration. | 11520 (8 days) |
Database & Message Broker
| Variable | Description | Placeholder |
|---|---|---|
DATABASE_URL | Asyncpg connection string for PostgreSQL. | postgresql+asyncpg://user:pass@host:5432/db |
CELERY_BROKER_URL | Redis URL for Celery task queuing. | redis://redis:6379/0 |
REDIS_CACHE_HOST | Redis host for application-level caching. | redis |
Cargoes Flow Integration
| Variable | Description |
|---|---|
CARGOES_FLOW_API_KEY | API Key for external Cargoes Flow services. |
CARGOES_FLOW_ORG_TOKEN | Organizational token for Cargoes Flow. |
WEBHOOK_SECRET | Secret to validate incoming Cargoes Flow webhooks. |
Microsoft OAuth (SSO)
| Variable | Description |
|---|---|
MICROSOFT_TENANT_ID | Azure AD Tenant ID for organization-level SSO. |
MICROSOFT_CLIENT_ID | Client ID for your Azure registered application. |
MICROSOFT_CLIENT_SECRET | Client Secret for your Azure application. |
MICROSOFT_REDIRECT_URI | callback URL registered in the Azure portal. |
Scraper Orchestration
| Variable | Description |
|---|---|
SCRAPER_ENDPOINTS | JSON Array of terminal scraper URLs. |
SCRAPER_API_KEY | The X-API-TOKEN used to authenticate with the scraper. |
IMPORTANT
Precedence Warning: Within SCRAPER_ENDPOINTS, ensure the PNCT terminal is listed first if it contains legacy data that must be processed before other updates.
2. Freight Flow Scraper Configuration
The scraper handles terminal-specific automation and requires credentials for each port portal.
Security & Connectivity
| Variable | Description |
|---|---|
X_API_TOKEN | Shared secret to allow the backend to call the scraper. |
BACKEND_WEBHOOK_URL | The URL where the scraper posts results back to the backend. |
WEBHOOK_SECRET_KEY | Secret key for webhook signature validation. |
Microsoft/Outlook Automation
Used to automate the retrieval of verification codes for terminal logins.
OUTLOOK_EMAIL: Automation account email.OUTLOOK_PASSWORD: App password for the automation account.
Terminal Credentials
Provide credentials for each terminal portal implemented in the system.
- Maher Terminal:
MAHER_TERMINAL_USERNAME,MAHER_TERMINAL_PASSWORD,MAHER_CSP_URL - Port Houston:
PORT_HOUSTON_USERNAME,PORT_HOUSTON_PASSWORD - Fenix Marine:
FENIX_MARINE_USERNAME,FENIX_MARINE_PASSWORD - Yusen / YTI:
YUSEN_USERNAME,YUSEN_PASSWORD - EModal:
EMODAL_USERNAME,EMODAL_PASSWORD - POMTOC:
POMTOC_USERNAME,POMTOC_PASSWORD - Conley:
CONLEY_USERNAME,CONLEY_PASSWORD - ITS:
ITS_USERNAME,ITS_PASSWORD - ONE Carrier:
ONE_USERNAME,ONE_PASSWORD
Deployment Logic
The system is configured to prioritize environment-specific files:
- Development: Use
.env.devfor local Docker environments. - Production: Use
.env.prod. This file is loaded by Docker Compose in production and typically contains the long-lived secrets and domain-managed URLs.