Skip to main content

Environment Variables Reference

This page provides a comprehensive reference for all environment variables supported by Flux-Orbit. Use these variables to customize your deployment behavior.

Required Variables​

These variables must be set for Flux-Orbit to function:

GIT_REPO_URL​

  • Type: String (URL)
  • Required: Yes
  • Description: The Git repository URL to deploy
  • Example: https://github.com/username/repository
-e GIT_REPO_URL=https://github.com/timlrx/tailwind-nextjs-starter-blog

APP_PORT​

  • Type: Integer
  • Required: Yes
  • Description: The port your application listens on inside the container
  • Example: 3000, 5000, 8080
-e APP_PORT=3000

Git Configuration​

GIT_BRANCH​

  • Type: String
  • Default: main
  • Description: Git branch to deploy
  • Example: main, master, develop, production
-e GIT_BRANCH=production

GIT_TOKEN​

  • Type: String
  • Required: For private repositories
  • Description: Personal access token for private repository access
  • Security: Never commit tokens to version control
-e GIT_TOKEN=ghp_YourGitHubPersonalAccessToken
Security Note

Store tokens securely using Docker secrets or environment files. Never expose tokens in logs or commit them to repositories.

GIT_USERNAME​

  • Type: String
  • Default: Extracted from token if provided
  • Description: Git username for authentication
  • Use Case: Some Git providers require explicit username
-e GIT_USERNAME=myusername
-e GIT_TOKEN=mytoken

Project Configuration​

PROJECT_PATH​

  • Type: String (Path)
  • Default: Repository root
  • Description: Subdirectory within the repository to deploy (monorepo support)
  • Example: frontend, apps/web, services/api
# Deploy only the frontend folder from a monorepo
-e PROJECT_PATH=frontend

PROJECT_TYPE​

  • Type: String
  • Default: auto
  • Options: auto, node, python, ruby, go, static
  • Description: Force a specific project type instead of auto-detection
# Force Node.js even if other files exist
-e PROJECT_TYPE=node

# Force Go even if other files exist
-e PROJECT_TYPE=go

Runtime Versions​

NODE_VERSION​

  • Type: String
  • Default: Detected from .nvmrc or package.json, fallback to LTS
  • Description: Specific Node.js version to install
  • Format: 18.19.0, 20.11.0, lts/iron
-e NODE_VERSION=20.11.0

PYTHON_VERSION​

  • Type: String
  • Default: Detected from .python-version or pyproject.toml, fallback to 3.11
  • Description: Specific Python version to install
  • Format: 3.9, 3.10, 3.11, 3.12
-e PYTHON_VERSION=3.11

RUBY_VERSION​

  • Type: String
  • Default: Detected from .ruby-version or Gemfile, fallback to 3.0
  • Description: Specific Ruby version to install
  • Format: 2.7.8, 3.0.6, 3.1.4
-e RUBY_VERSION=3.1.4

GO_VERSION​

  • Type: String
  • Default: Detected from .go-version or go.mod, fallback to 1.22.0
  • Description: Specific Go version to install
  • Format: 1.21.0, 1.22.0, 1.22.5
-e GO_VERSION=1.22.0

CGO_ENABLED​

  • Type: Integer (0 or 1)
  • Default: 0 (disabled)
  • Description: Enable or disable CGO for Go builds
  • Use Cases:
    • 0 (default) - Static binaries, no C dependencies, maximum portability
    • 1 - Enable CGO if your app requires C libraries (SQLite, etc.)
# Default: Static binary (recommended)
-e CGO_ENABLED=0

# Enable CGO for C dependencies
-e CGO_ENABLED=1

NODE_OPTIONS​

  • Type: String
  • Default: Auto-configured to --max-old-space-size=<75% of container RAM>
  • Description: Node.js runtime options, primarily used for memory limits
  • Auto-Configuration:
    • Automatically set to 75% of container memory
    • Minimum: 1024MB (1GB)
    • Maximum: 8192MB (8GB)
    • Example: 4GB container → --max-old-space-size=3072
  • Use Case: Override for custom memory requirements or other Node.js flags
# Auto-configured (recommended):
# Just set Docker memory limit, NODE_OPTIONS auto-configured
--memory="4g"

# Manual override:
-e NODE_OPTIONS="--max-old-space-size=5120"

# Multiple flags:
-e NODE_OPTIONS="--max-old-space-size=4096 --experimental-worker"
Memory Auto-Configuration

For most applications, you don't need to set NODE_OPTIONS. Simply allocate adequate memory to the Docker container:

  • Small apps (2-4GB container): Auto-configures 1.5-3GB Node.js heap
  • Large apps (6-8GB container): Auto-configures 4.5-6GB Node.js heap
  • Very large builds (Aave, Uniswap): Use 6-8GB container for auto-config

The system automatically logs the configured memory: Auto-configured Node.js heap: 3072MB (container: 4096MB)

Build Configuration​

BUILD_COMMAND​

  • Type: String
  • Default: Auto-detected based on project type
  • Description: Override the build command
  • Examples:
    • Node.js: npm run build, yarn build, npm run build:production
    • Python: python manage.py collectstatic, mkdocs build
    • Ruby: bundle exec rake assets:precompile
-e BUILD_COMMAND="npm run build:production && npm run optimize"

INSTALL_COMMAND​

  • Type: String
  • Default: Auto-detected based on project type
  • Description: Override the dependency installation command
  • Examples:
    • Node.js: npm ci, yarn install --frozen-lockfile, pnpm install
    • Python: pip install -r requirements.txt, poetry install
    • Ruby: bundle install, bundle install --deployment
-e INSTALL_COMMAND="npm ci --production"

RUN_COMMAND​

  • Type: String
  • Default: Auto-detected from package.json, requirements.txt, etc.
  • Description: Override the command to start your application
  • Examples:
    • Node.js: npm start, node server.js, npm run serve
    • Python: python app.py, gunicorn app:application, python manage.py runserver
    • Ruby: bundle exec rails server, ruby app.rb
-e RUN_COMMAND="npm run start:production"

PRE_BUILD_COMMAND​

  • Type: String
  • Description: Command to run before the build process
  • Use Cases: Database migrations, asset preparation, environment setup
-e PRE_BUILD_COMMAND="npm run migrate && npm run seed"

POST_BUILD_COMMAND​

  • Type: String
  • Description: Command to run after successful build
  • Use Cases: Cache warming, notifications, cleanup
-e POST_BUILD_COMMAND="npm run cache:warm && npm run notify:deploy"

CI/CD Configuration​

WEBHOOK_SECRET​

  • Type: String
  • Description: Secret for validating webhook requests
  • Security: Use a strong, random string
  • Providers: GitHub, GitLab, Bitbucket
-e WEBHOOK_SECRET=your_strong_webhook_secret_here

WEBHOOK_PORT​

  • Type: Integer
  • Default: 9001
  • Description: Port for the webhook listener
  • Note: Usually kept as default
-e WEBHOOK_PORT=9001

API_KEY​

  • Type: String
  • Default: Empty (no authentication)
  • Description: API key for securing /status and /health endpoints
  • Security: Use a strong, random string; independent from WEBHOOK_SECRET
# Protect API endpoints with authentication
-e API_KEY=your_secure_api_key_here

# Access protected endpoints
curl -H "Authorization: Bearer your_secure_api_key_here" http://localhost:9001/status
API Authentication

When API_KEY is set, the /status and /health endpoints require authentication via the Authorization: Bearer <token> header. If API_KEY is not set, these endpoints remain publicly accessible (backward compatible).

The API_KEY is independent from WEBHOOK_SECRET:

  • WEBHOOK_SECRET - Used for webhook signature verification (GitHub/GitLab/Bitbucket)
  • API_KEY - Used for API endpoint authentication (/status, /health)

This separation allows you to:

  • Share webhook secrets with GitHub without exposing API access
  • Rotate API keys independently from webhook configurations
  • Use different keys for different security purposes

POLLING_INTERVAL​

  • Type: Integer (seconds)
  • Default: 0 (disabled)
  • Description: Interval for polling Git repository for changes
  • Range: 0 (disabled) or 60-86400 (1 minute to 24 hours)
# Check for updates every 5 minutes
-e POLLING_INTERVAL=300

DEPLOY_ON_START​

  • Type: Boolean (true/false)
  • Default: true
  • Description: Whether to deploy immediately on container start
  • Use Case: Set to false for manual deployment control
-e DEPLOY_ON_START=false

DEPLOYMENT_TIMEOUT​

  • Type: Integer (seconds)
  • Default: 1800 (30 minutes)
  • Description: Maximum time allowed for a deployment to complete
  • Range: 300-7200 (5 minutes to 2 hours)
  • Safety: If deployment exceeds this time, automatic rollback is triggered

Blue/Green Deployment Configuration​

Flux-Orbit supports coordinated blue/green deployments across multiple instances in Flux Network.

FLUX_APP_NAME​

  • Type: String
  • Default: Empty (blue/green disabled)
  • Description: Your Flux application name for peer discovery and coordination
  • Required for: Multi-instance blue/green deployments
# Enable blue/green deployment coordination
-e FLUX_APP_NAME=wordpress1754431692809
How Blue/Green Works

When FLUX_APP_NAME is configured:

  1. The instance receiving a webhook deploys first (PRIMARY)
  2. After successful deployment, it triggers peer instances via Flux API
  3. Peer instances deploy sequentially or in parallel (based on strategy)
  4. Always maintains at least 2 healthy instances during deployment
  5. If PRIMARY fails, peer deployments are NOT triggered

FLUX_EXTERNAL_API_PORT​

  • Type: Integer
  • Default: Same as WEBHOOK_PORT (9001)
  • Description: Port used for peer-to-peer communication and status checks
  • Note: Must match the external port mapped to your container
# Use custom port for peer communication
-e FLUX_EXTERNAL_API_PORT=9001

BLUE_GREEN_STRATEGY​

  • Type: String (sequential | parallel)
  • Default: sequential
  • Description: Deployment strategy for peer instances

Sequential Strategy:

  • Deploys to peer instances one at a time
  • Waits for each peer to complete before starting next
  • Safest option - ensures rollout control
  • Slower but more predictable

Parallel Strategy:

  • Triggers all peer instances simultaneously
  • Faster deployment across cluster
  • Higher risk - multiple instances deploying at once
# Sequential deployment (recommended)
-e BLUE_GREEN_STRATEGY=sequential

# Parallel deployment (faster but riskier)
-e BLUE_GREEN_STRATEGY=parallel
Blue/Green Example
# Complete blue/green setup for Flux Network
docker run -d \
  -e GIT_REPO_URL=https://github.com/user/app \
  -e APP_PORT=3000 \
  -e FLUX_APP_NAME=myapp1234567890 \
  -e FLUX_EXTERNAL_API_PORT=9001 \
  -e BLUE_GREEN_STRATEGY=sequential \
  -e WEBHOOK_SECRET=my-webhook-secret \
  -p 3000:3000 \
  -p 9001:9001 \
  runonflux/orbit:latest

This configuration enables:

  • ✅ Zero-downtime deployments across all Flux instances
  • ✅ Automatic peer discovery via Flux API
  • ✅ Coordinated rollout with rollback protection
  • ✅ Always maintains minimum 2 healthy instances
# Allow longer deployments (1 hour)
-e DEPLOYMENT_TIMEOUT=3600

# Shorter timeout for fast builds (10 minutes)
-e DEPLOYMENT_TIMEOUT=600
Deployment Safety

Flux-Orbit includes a deployment watchdog that monitors deployment duration. If a deployment gets stuck (network issues, infinite loops, etc.), the system will automatically:

  1. Detect the timeout
  2. Stop the deployment
  3. Rollback to the last working commit
  4. Restart the application

This prevents deployments from hanging indefinitely and ensures your application remains available.

Deployment Hooks Configuration​

Deployment hooks allow you to run custom scripts at specific points in the deployment lifecycle. See the Deployment Hooks Guide for detailed usage.

SKIP_HOOKS​

  • Type: Boolean (true/false)
  • Default: false
  • Description: Disable all deployment hooks for this deployment
  • Use Cases: Emergency deployments, debugging, skipping migrations
# Disable hooks for this deployment
-e SKIP_HOOKS=true
When to Skip Hooks

Use SKIP_HOOKS=true when:

  • You need to deploy without running migrations
  • Debugging hook failures
  • Emergency hotfix that must deploy immediately
  • Testing deployment without side effects

HOOK_TIMEOUT​

  • Type: Integer (seconds)
  • Default: 300 (5 minutes)
  • Description: Maximum time allowed for a hook to execute
  • Range: 60-3600 (1 minute to 1 hour)
  • Applies to: Both pre-deploy.sh and post-deploy.sh
# Increase timeout for slow migrations (15 minutes)
-e HOOK_TIMEOUT=900

# Short timeout for fast hooks (2 minutes)
-e HOOK_TIMEOUT=120
Hook Timeouts

If a hook exceeds HOOK_TIMEOUT:

  • Hook is killed automatically
  • Pre-deploy timeout triggers deployment rollback
  • Post-deploy timeout is logged as warning (non-fatal)
  • Check /app/logs/hooks.log for timeout messages

Hook Example​

# Complete deployment with database migrations
docker run -d \
  -e GIT_REPO_URL=https://github.com/user/app \
  -e APP_PORT=3000 \
  -e DATABASE_URL=postgresql://user:pass@host:5432/db \
  -e HOOK_TIMEOUT=600 \
  -p 3000:3000 \
  runonflux/orbit:latest

# Your repository should have:
# - pre-deploy.sh (runs migrations)
# - post-deploy.sh (optional, runs after app starts)

See Deployment Hooks Guide for:

  • Creating hook scripts
  • Real-world examples (Prisma, Django, Rails)
  • Error handling and troubleshooting
  • Security best practices

Health Check Configuration​

HEALTH_CHECK_PATH​

  • Type: String (URL path)
  • Default: /
  • Description: HTTP path to check for application health
  • Examples: /, /health, /api/health, /status
-e HEALTH_CHECK_PATH=/api/health

HEALTH_CHECK_INTERVAL​

  • Type: Integer (seconds)
  • Default: 30
  • Description: Interval between health checks
  • Range: 10-300
-e HEALTH_CHECK_INTERVAL=60

HEALTH_CHECK_TIMEOUT​

  • Type: Integer (seconds)
  • Default: 10
  • Description: Timeout for each health check
  • Range: 5-60
-e HEALTH_CHECK_TIMEOUT=20

HEALTH_CHECK_RETRIES​

  • Type: Integer
  • Default: 3
  • Description: Number of failed checks before marking unhealthy
  • Range: 1-10
-e HEALTH_CHECK_RETRIES=5

Supervisor Configuration​

SUPERVISOR_USER​

  • Type: String
  • Default: appuser
  • Description: User to run the application as
  • Security: Avoid running as root
-e SUPERVISOR_USER=appuser

SUPERVISOR_PASSWORD​

  • Type: String
  • Default: admin
  • Description: Password for supervisor web interface
  • Security: Change in production
-e SUPERVISOR_PASSWORD=strong_password_here

SUPERVISOR_PORT​

  • Type: Integer
  • Default: 9001
  • Description: Port for supervisor web interface
-e SUPERVISOR_PORT=9001

Logging Configuration​

LOG_LEVEL​

  • Type: String
  • Default: info
  • Options: debug, info, warning, error
  • Description: Logging verbosity level
-e LOG_LEVEL=debug

LOG_MAX_SIZE​

  • Type: String
  • Default: 100M
  • Description: Maximum size of log files before rotation
  • Format: 10M, 100M, 1G
-e LOG_MAX_SIZE=50M

LOG_MAX_FILES​

  • Type: Integer
  • Default: 10
  • Description: Number of rotated log files to keep
-e LOG_MAX_FILES=5

Performance Configuration​

MAX_OLD_SPACE_SIZE​

  • Type: Integer (MB)
  • Default: Container memory limit
  • Description: Node.js heap memory limit
  • Applies to: Node.js applications only
-e MAX_OLD_SPACE_SIZE=2048

WEB_CONCURRENCY​

  • Type: Integer
  • Default: Number of CPU cores
  • Description: Number of worker processes
  • Applies to: Applications that support clustering
-e WEB_CONCURRENCY=4

PYTHON_WORKERS​

  • Type: Integer
  • Default: (CPU cores * 2) + 1
  • Description: Number of Gunicorn/Uvicorn workers
  • Applies to: Python applications
-e PYTHON_WORKERS=8

Environment Files​

Using .env Files​

Instead of passing multiple -e flags, use an environment file:

# Create .env file
cat > flux-pod.env << EOF
GIT_REPO_URL=https://github.com/username/repo
APP_PORT=3000
GIT_BRANCH=production
BUILD_COMMAND=npm run build:prod
NODE_VERSION=20.11.0
WEBHOOK_SECRET=my_secret
EOF

# Use with Docker
docker run -d \
  --env-file flux-pod.env \
  -p 3000:3000 \
  runonflux/orbit:latest

Complete Example​

Here's a comprehensive example using multiple environment variables:

docker run -d \
  --name production-app \
  -e GIT_REPO_URL=https://github.com/company/main-app \
  -e GIT_BRANCH=production \
  -e GIT_TOKEN=ghp_YourToken \
  -e PROJECT_PATH=apps/web \
  -e APP_PORT=3000 \
  -e NODE_VERSION=20.11.0 \
  -e BUILD_COMMAND="npm ci && npm run build:production" \
  -e RUN_COMMAND="npm run start:production" \
  -e DATABASE_URL=postgresql://user:pass@db:5432/prod \
  -e HOOK_TIMEOUT=600 \
  -e WEBHOOK_SECRET=webhook_secret_123 \
  -e POLLING_INTERVAL=300 \
  -e HEALTH_CHECK_PATH=/api/health \
  -e HEALTH_CHECK_INTERVAL=60 \
  -e LOG_LEVEL=info \
  -e MAX_OLD_SPACE_SIZE=2048 \
  -e WEB_CONCURRENCY=4 \
  -p 3000:3000 \
  -p 9001:9001 \
  runonflux/orbit:latest

Best Practices​

  1. Security First

    • Never commit secrets to version control
    • Use Docker secrets for sensitive data
    • Rotate tokens regularly

  2. Performance Optimization

    • Set memory limits appropriately
    • Configure worker counts based on available resources
    • Use production build commands

  3. Monitoring

    • Always configure health checks
    • Set appropriate log levels
    • Monitor supervisor dashboard

  4. Version Control

    • Pin runtime versions for consistency
    • Document environment variables in your README
    • Use environment files for complex configurations

Troubleshooting​

If environment variables aren't working as expected:

  1. Check variable names - They are case-sensitive
  2. Verify quotes - Use quotes for values with spaces
  3. Check logs - docker logs container-name
  4. Validate JSON - For complex values, ensure proper escaping

Next Steps​