Common Issues

This guide covers the most common issues users encounter with Flux-Orbit and how to solve them.

Application Won't Start

Symptoms

• Container starts but application doesn't run
• Supervisor shows application as "FATAL" or "BACKOFF"
• Can't access application on expected port

Check the Logs

# View all logs
docker logs my-app

# View application-specific logs
docker exec my-app tail -100 /app/logs/app.log

# View setup logs
docker exec my-app cat /app/logs/setup.log

Common Causes and Solutions

Wrong PORT Configuration

Problem: Application listening on different port than configured

Solution:

# Ensure APP_PORT matches your application's actual port
docker run -d \
  -e APP_PORT=3000 \  # Must match what your app uses
  -p 3000:3000 \
  runonflux/orbit:latest

Missing Start Script

Problem: No start script in package.json or incorrect command

Solution:

# Specify the start command explicitly
-e RUN_COMMAND="node server.js"
# or
-e RUN_COMMAND="npm run start:production"

Missing Dependencies

Problem: Dependencies not installed correctly

Solution:

# Force reinstall
docker exec my-app bash -c "cd /app/src && npm ci"

# Or restart container with clean install
-e INSTALL_COMMAND="npm ci --production"

Build Failures

Symptoms

• Build command fails
• "Build failed" in logs
• Application uses old code

Common Solutions

Insufficient Memory

Problem: Build process runs out of memory

Symptoms:

FATAL ERROR: Ineffective mark-compacts near heap limit
Allocation failed - JavaScript heap out of memory

Solution:

Since v0.2.1, Flux-Orbit automatically configures Node.js memory based on container RAM:

# Automatic configuration (recommended)
# Just increase Docker memory, NODE_OPTIONS auto-configured
docker run -d \
  --memory="6g" \  # Auto-configures 4.5GB Node.js heap
  -e GIT_REPO_URL=https://github.com/your/repo \
  runonflux/orbit:latest

The system will log: Auto-configured Node.js heap: 4608MB (container: 6144MB)

Manual override (if needed):

# Explicitly set Node.js memory limit
docker run -d \
  --memory="4g" \
  -e NODE_OPTIONS="--max-old-space-size=3584" \
  -e GIT_REPO_URL=https://github.com/your/repo \
  runonflux/orbit:latest

Memory Guidelines:

• Small apps (simple React/Vue): 2-3GB container
• Medium apps (Next.js, dashboards): 3-4GB container
• Large apps (DeFi, Web3, Aave, Uniswap): 6-8GB container
• Very large (complex monorepos): 8-10GB container

On Flux Cloud: Increase RAM allocation in app settings, memory auto-configures.

Missing Build Tools

Problem: Native dependencies need compilation

Solution:

# The image includes build-essential, but some packages need more
docker exec my-app apt-get update && apt-get install -y python3-dev

Custom Build Command

Problem: Non-standard build process

Solution:

-e BUILD_COMMAND="npm run build:custom && npm run post-build"

Git Clone/Pull Failures

Symptoms

• "Failed to clone repository"
• "Authentication failed"
• "Repository not found"

Private Repository Issues

Problem: Can't access private repository

Solution:

# Use personal access token
docker run -d \
  -e GIT_REPO_URL=https://github.com/user/private-repo \
  -e GIT_TOKEN=ghp_YourGitHubToken \
  runonflux/orbit:latest

Invalid Repository URL

Problem: Typo or wrong URL format

Solution:

# Ensure URL is correct and accessible
-e GIT_REPO_URL=https://github.com/username/repository

# Not: github.com/username/repository (missing https://)
# Not: https://github.com/username/repository.git (optional .git)

Network Issues

Problem: Can't reach GitHub/GitLab

Solution:

# Check DNS resolution
docker exec my-app nslookup github.com

# Check network connectivity
docker exec my-app ping -c 3 github.com

Port Conflicts

Symptoms

• "Port already in use"
• Can't access application
• Multiple containers conflicting

Solutions

Change Host Port

# Map to different port
docker run -d \
  -e APP_PORT=3000 \      # Internal port (don't change)
  -p 8080:3000 \          # External port 8080 -> Internal 3000
  runonflux/orbit:latest

Find What's Using the Port

# On Linux/Mac
lsof -i :3000

# On Windows
netstat -ano | findstr :3000

# Kill the process if needed
kill -9 <PID>

Webhook Not Working

Symptoms

• GitHub webhook shows red X
• Push doesn't trigger deployment
• No webhook logs

Check Webhook Listener

# Verify webhook listener is running
docker logs my-app | grep "Webhook listener"

# Check if port is open
netstat -an | grep 9001

# Test webhook manually
curl -X POST http://localhost:9001/webhook \
  -H "Content-Type: application/json" \
  -d '{"ref":"refs/heads/main"}'

Common Fixes

1. Expose webhook port:

   -p 9001:9001  # Don't forget this!

2. Check webhook secret:

   -e WEBHOOK_SECRET=same_as_github_config

3. Verify URL is accessible:

   • Use public IP, not localhost
   • Check firewall rules
   • Verify port forwarding

Container Keeps Restarting

Symptoms

• Container restarts every few seconds
• Status shows "Restarting"
• Logs show crash loop

Check Exit Codes

docker ps -a
# Look at STATUS column for exit code

docker logs my-app --tail 50
# Check for error messages

Common Causes

Application Crashes Immediately

Solution: Fix application errors or specify correct start command:

-e RUN_COMMAND="node server.js"

Health Check Failing

Solution: Disable or fix health checks:

-e HEALTH_CHECK_INTERVAL=0  # Disable
# Or fix the health endpoint in your app

Out of Memory

Solution: Increase memory limit:

docker run -d --memory="2g" runonflux/orbit:latest

Slow Performance

Symptoms

• Application responds slowly
• High CPU/memory usage
• Timeouts

Optimize Resources

# Allocate more resources
docker run -d \
  --cpus="2" \
  --memory="4g" \
  -e WEB_CONCURRENCY=4 \
  -e NODE_OPTIONS="--max-old-space-size=3072" \
  runonflux/orbit:latest

Check Resource Usage

# Monitor container resources
docker stats my-app

# Check processes inside container
docker exec my-app ps aux

# Check disk usage
docker exec my-app df -h

Deployment Not Updating

Symptoms

• Push to GitHub doesn't deploy new code
• Application shows old version
• Git pull seems to work but code doesn't update

Force Update

# Manually trigger update
docker exec my-app /usr/local/bin/flux-entrypoint.sh update

# Or restart container
docker restart my-app

Clear Cache

# Remove node_modules and reinstall
docker exec my-app rm -rf /app/src/node_modules
docker exec my-app bash -c "cd /app/src && npm ci"

Database Connection Issues

Symptoms

• "Connection refused" errors
• "Host not found"
• Timeout connecting to database

Solutions

Use Host Network (Linux)

docker run -d \
  --network="host" \
  -e DATABASE_URL=postgresql://localhost:5432/mydb \
  runonflux/orbit:latest

Use host.docker.internal (Mac/Windows)

-e DATABASE_URL=postgresql://host.docker.internal:5432/mydb

Use Docker Network

# Create network
docker network create my-network

# Run database
docker run -d --name postgres --network my-network postgres

# Run Flux-Orbit
docker run -d \
  --network my-network \
  -e DATABASE_URL=postgresql://postgres:5432/mydb \
  runonflux/orbit:latest

Getting Help

If you're still stuck:

1. Check logs thoroughly:

   docker logs my-app > full-logs.txt
   docker exec my-app cat /app/logs/setup.log
   docker exec my-app cat /app/logs/app.log

2. Get container details:

   docker inspect my-app
   docker exec my-app env

3. Ask for help:

   • GitHub Issues
   • Flux Discord
   • Include logs and configuration

Debug Mode

Enable debug mode for more information:

docker run -d \
  -e LOG_LEVEL=debug \
  -e DEBUG=* \
  --name debug-app \
  runonflux/orbit:latest

Then check the detailed logs:

docker logs debug-app 2>&1 | tee debug.log