Environment Variable Configuration Guide
This document explains what each .env value is used for and what to configure it with for this project.
How To Use This Guide
- Start from
.env.example. - Copy it to
.env. - Fill required values first, then optional integrations.
- For deployed environments, store sensitive values in your secret manager and inject them at runtime.
Quick Start (Local)
Minimum values to run app + queue worker locally:
APP_NAME="Scottsdale Hub"
APP_ENV=local
APP_KEY=base64:GENERATED_BY_ARTISAN
APP_DEBUG=true
APP_URL=http://127.0.0.1:8000
DB_CONNECTION=sqlite
QUEUE_CONNECTION=sqs
AWS_DEFAULT_REGION=us-west-2
SQS_PREFIX=https://sqs.us-west-2.amazonaws.com/YOUR_AWS_ACCOUNT_ID
SCOTTSDALE_WEBHOOK_SECRET=change-me-local
BUSINESS_CENTRAL_WEBHOOK_SECRET=change-me-local
SDM_RETAIL_WEBHOOK_SECRET=change-me-local
SDM_WHOLESALE_WEBHOOK_SECRET=change-me-local
WALMART_WEBHOOK_SECRET=change-me-local
EBAY_WEBHOOK_SECRET=change-me-local
WOOCOMMERCE_WEBHOOK_SECRET=change-me-local
Generate app key after creating .env:
php artisan key:generate
Variable Reference
Application
| Variable | What It Is For | What To Configure |
|---|---|---|
APP_NAME | App display name for logs/UI. | Local: Scottsdale Hub or team standard name. |
APP_ENV | Environment behavior flags (local, testing, production). | Local: local. Shared dev: development or team standard. Prod: production. |
APP_KEY | Encryption/signing key used by Laravel. | Required. Generate with php artisan key:generate. Never reuse insecure keys. |
APP_DEBUG | Verbose error pages and stack traces. | Local: true. Deployed: false. |
APP_URL | Base URL used for generated links and callbacks. | Local: http://127.0.0.1:8000 (or your local host). Deployed: environment URL. |
APP_LOCALE | Default locale. | en unless localized content is required. |
APP_FALLBACK_LOCALE | Fallback locale if translation missing. | en. |
APP_FAKER_LOCALE | Faker locale used in seed/test data. | en_US by default. |
APP_VERSION | App version string for diagnostics/logging. | Semantic version, for example 1.0.0. |
Ngrok and Local Webhook Exposure
| Variable | What It Is For | What To Configure |
|---|---|---|
NGROK_DOMAIN | Fixed ngrok domain for local webhook endpoints. | Your reserved ngrok domain or blank if not using reserved domain. |
NGROK_PORT | Local port ngrok forwards to. | Usually 8000. |
NGROK_ENABLED | Toggles ngrok-aware behavior for local workflows. | Local webhook testing: true. Otherwise false. |
NGROK_AUTH_TOKEN | ngrok account auth token. | Set from ngrok dashboard for authenticated tunnels. |
NGROK_REGION | ngrok region routing. | Usually us, unless your account/workflow requires another region. |
Maintenance and Runtime
| Variable | What It Is For | What To Configure |
|---|---|---|
APP_MAINTENANCE_DRIVER | Maintenance mode storage backend. | Default file is fine unless centralized maintenance state is needed. |
APP_MAINTENANCE_STORE | Store used when maintenance driver supports cache/database stores. | Usually leave commented unless using centralized store. |
PHP_CLI_SERVER_WORKERS | Number of PHP built-in server workers. | Optional for local tuning; typically leave unset. |
BCRYPT_ROUNDS | Password hashing cost factor. | Local default 12. Increase carefully only if needed. |
Logging
| Variable | What It Is For | What To Configure |
|---|---|---|
LOG_CHANNEL | Primary Laravel logging channel. | Local: stack or single. Deployed: team standard. |
LOG_STACK | Channels included in stack logger. | Local default single. |
LOG_DEPRECATIONS_CHANNEL | Where PHP/framework deprecations go. | null or dedicated channel depending on observability setup. |
LOG_LEVEL | Minimum severity to record. | Local: debug. Deployed: commonly info or warning. |
BUSINESS_CENTRAL_LOCAL_LOGGING | Enables extra local logging for BC integration flows. | Local troubleshooting: true. Deployed: usually false unless needed. |
BUSINESS_CENTRAL_LOG_LEVEL | BC integration log threshold. | Local: debug. Deployed: info or warning. |
BUSINESS_CENTRAL_LOG_DAILY_DAYS | BC log retention days. | Default 14, adjust per retention policy. |
Queue Logging Controls
| Variable | What It Is For | What To Configure |
|---|---|---|
QUEUE_LOG_ENABLED | Enables queue-specific log channel output. | Local debugging: true. Default: false. |
QUEUE_LOG_LEVEL | Queue log severity threshold. | Local: debug. Deployed: info/warning. |
QUEUE_LOG_DAILY_DAYS | Queue log retention in days. | Default 14 unless policy differs. |
Database
| Variable | What It Is For | What To Configure |
|---|---|---|
DB_CONNECTION | Database driver selection. | Local default in template: sqlite. For MySQL use mysql. |
DB_HOST | MySQL host. | Set when using MySQL (for example 127.0.0.1). |
DB_PORT | MySQL port. | Usually 3306 (or tunnel port like 3307/3308/3309). |
DB_DATABASE | Database name. | Local DB/schema name. |
DB_USERNAME | Database user. | Local DB user. |
DB_PASSWORD | Database password. | Local DB password from secure source. |
Session / Cache / Core Service Connections
| Variable | What It Is For | What To Configure |
|---|---|---|
SESSION_DRIVER | Session backend. | Template uses database; ensure session table migration exists. |
SESSION_LIFETIME | Session duration in minutes. | Default 120 unless policy differs. |
SESSION_ENCRYPT | Encrypts session payloads. | Default false unless requirement says otherwise. |
SESSION_PATH | Session cookie path. | Usually /. |
SESSION_DOMAIN | Session cookie domain. | null for local, set to app domain in deployed envs. |
BROADCAST_CONNECTION | Broadcast driver. | log in local unless real broadcaster is configured. |
FILESYSTEM_DISK | Default filesystem disk. | local for local development. |
QUEUE_CONNECTION | Queue driver. | For this project local flow: sqs. |
CACHE_STORE | Cache backend. | Template uses database; ensure cache tables exist. |
CACHE_PREFIX | Optional shared cache key prefix. | Set when multiple apps share cache backend. |
AWS and SQS
| Variable | What It Is For | What To Configure |
|---|---|---|
AWS_ACCESS_KEY_ID | AWS API access key. | Set if not using profile-based credentials. Keep secret. |
AWS_SECRET_ACCESS_KEY | AWS API secret key. | Set if not using profile-based credentials. Keep secret. |
AWS_DEFAULT_REGION | AWS region for SQS/S3/etc. | us-west-2 for current project defaults. |
SQS_PREFIX | Base queue URL prefix (account + region). | https://sqs.us-west-2.amazonaws.com/<AWS_ACCOUNT_ID>. |
SQS_SUFFIX | Optional queue name suffix. | Usually blank unless naming strategy requires it. |
Notes:
- Local queue naming convention is
hublocal-*after deploying local infra. - You can use AWS profile credentials instead of static key env vars.
Memcached and Redis
| Variable | What It Is For | What To Configure |
|---|---|---|
MEMCACHED_HOST | Memcached host when memcached is used. | Usually 127.0.0.1 or service host. |
REDIS_CLIENT | Redis PHP client driver. | Template uses phpredis. |
REDIS_HOST | Redis host. | Local default 127.0.0.1. |
REDIS_PASSWORD | Redis auth password. | null locally unless auth is enabled. |
REDIS_PORT | Redis port. | Usually 6379. |
Mail
| Variable | What It Is For | What To Configure |
|---|---|---|
MAIL_MAILER | Mail transport driver. | Local often smtp (Mailpit/Mailhog) or log. |
MAIL_SCHEME | SMTP scheme override. | Usually null unless TLS/SSL override needed. |
MAIL_HOST | SMTP host. | Local Mailpit often 127.0.0.1. |
MAIL_PORT | SMTP port. | Local Mailpit commonly 1025. |
MAIL_USERNAME | SMTP username. | null locally, set in deployed env if SMTP auth required. |
MAIL_PASSWORD | SMTP password. | null locally, secure secret in deployed env. |
MAIL_FROM_ADDRESS | Default sender email. | Project default: [email protected]. |
MAIL_FROM_NAME | Default sender name. | Project default: Scottsdale Hub. |
MAILGUN_DOMAIN | Mailgun domain if Mailgun transport used. | Set only when using Mailgun. |
MAILGUN_SECRET | Mailgun API key. | Set securely when using Mailgun. |
MAILGUN_ENDPOINT | Mailgun API endpoint host. | Usually api.mailgun.net. |
S3 / Object Storage
| Variable | What It Is For | What To Configure |
|---|---|---|
AWS_BUCKET | S3 bucket name for storage operations. | Set bucket name if S3 disk used. |
AWS_ROOT | Optional prefix/path root within bucket. | Leave blank or set app-specific folder prefix. |
AWS_USE_PATH_STYLE_ENDPOINT | Path-style addressing for S3-compatible providers. | false for AWS S3; true for some S3-compatible local services. |
Frontend Build
| Variable | What It Is For | What To Configure |
|---|---|---|
VITE_APP_NAME | Frontend-exposed app name. | Usually keep "${APP_NAME}". |
Webhook Signature Secrets
These secrets validate inbound webhook signatures per source.
| Variable | What It Is For | What To Configure |
|---|---|---|
SCOTTSDALE_WEBHOOK_SECRET | Signature validation for Scottsdale webhook source. | Set to secret shared with source system. |
BUSINESS_CENTRAL_WEBHOOK_SECRET | Signature validation for Business Central webhook source. | Set to BC webhook signing secret. |
SDM_RETAIL_WEBHOOK_SECRET | Signature validation for SDM retail webhooks. | Set to channel secret. |
SDM_WHOLESALE_WEBHOOK_SECRET | Signature validation for SDM wholesale webhooks. | Set to channel secret. |
WALMART_WEBHOOK_SECRET | Generic Walmart webhook secret if used by flow. | Set to Walmart-provided value. |
EBAY_WEBHOOK_SECRET | eBay webhook signature secret. | Set to eBay-provided value. |
WOOCOMMERCE_WEBHOOK_SECRET | WooCommerce webhook secret. | Set to WooCommerce webhook secret. |
WOOCOMMERCE_WEBHOOK_SIGNATURE_HEADER | Header key that carries Woo signature. | Default X-WC-Webhook-Signature. |
WOOCOMMERCE_WEBHOOK_SIGNATURE_ALGORITHM | HMAC algorithm for Woo signature verify. | Default sha256. |
Connector/API Shared Secrets
| Variable | What It Is For | What To Configure |
|---|---|---|
BUSINESS_CENTRAL_SECRET | Shared secret/credential for BC connector operations. | Set from BC integration credentials. |
WOOCOMMERCE_SECRET | Shared secret for WooCommerce connector calls. | Set from WooCommerce integration credentials. |
WALMART_SECRET | Shared secret for Walmart connector calls. | Set from Walmart integration credentials. |
EBAY_SECRET | Shared secret for eBay connector calls. | Set from eBay integration credentials. |
Walmart Integration (Sandbox and Production)
| Variable | What It Is For | What To Configure |
|---|---|---|
WALMART_ENV | Selects active Walmart environment. | sandbox for local/dev testing, production for production runs. |
WALMART_SANDBOX_BASE_URL | Walmart sandbox API base URL. | Keep default unless Walmart changes endpoint. |
WALMART_PRODUCTION_BASE_URL | Walmart production API base URL. | Keep default unless Walmart changes endpoint. |
WALMART_SANDBOX_WEBHOOK_SECRET | Sandbox webhook signature secret. | Set to sandbox-specific secret. |
WALMART_PRODUCTION_WEBHOOK_SECRET | Production webhook signature secret. | Set to production-specific secret. |
WALMART_SANDBOX_WEBHOOK_RECEIVER_URL | Public URL Walmart sandbox sends webhooks to. | Local with ngrok/public tunnel URL. |
WALMART_PRODUCTION_WEBHOOK_RECEIVER_URL | Production webhook callback URL. | Production API URL. |
WALMART_SANDBOX_CONSUMER_ID | Sandbox API consumer ID. | Set from Walmart developer portal sandbox credentials. |
WALMART_SANDBOX_PRIVATE_KEY | Sandbox API private key content/value. | Set from secure secret store. |
WALMART_PRODUCTION_CONSUMER_ID | Production API consumer ID. | Set from Walmart production credentials. |
WALMART_PRODUCTION_PRIVATE_KEY | Production API private key content/value. | Set from secure secret store. |
Sync and Worker Tuning
| Variable | What It Is For | What To Configure |
|---|---|---|
SYNC_BATCH_SIZE | Batch size for sync processing units. | Default 500; tune based on memory/throughput. |
SYNC_TIMEOUT_SECONDS | Timeout for sync operations. | Default 90; raise for slower upstream systems. |
QUEUE_NAMES | Comma-separated logical queue taxonomy. | Keep aligned with config/integration_queues.php. |
QUEUE_TRIES | Max retry attempts per failed job. | Default 5. |
QUEUE_BACKOFF_SECONDS | Delay between retries. | Default 60. |
QUEUE_SLEEP_SECONDS | Worker sleep when no job is available. | Default 3. |
QUEUE_WORKER_TIMEOUT_SECONDS | Worker hard timeout per job. | Default 120. |
QUEUE_WORKER_MEMORY_MB | Worker memory cap before restart. | Default 512. |
Required vs Optional Checklist
Required to boot local app reliably:
APP_KEYAPP_URL- Database settings for chosen driver
- SQS settings when
QUEUE_CONNECTION=sqs(AWS_DEFAULT_REGION,SQS_PREFIX, AWS creds/profile) - Webhook secrets for any channel you are actively testing
Optional unless integration is enabled:
- Walmart sandbox/production credential set
- Mailgun values
- S3 bucket values
- ngrok values (only needed for public webhook callbacks)
Security Notes
- Never commit real credentials to git.
- Keep production secrets in a managed secret store.
- Rotate webhook/API secrets when onboarding or offboarding systems.
- Use environment-specific values and do not reuse production secrets in local/dev.