Skip to main content

Installation

This page describes installing Flux-Orbit itself (the engine behind Deploy with Git) on your own machine, for development or self-hosting. To deploy an application on FluxCloud you do not need any of this - use Register New App → Deploy with Git and see First Deployment.

Learn how to install Flux-Orbit and prepare your environment for deploying applications to the Flux Network.

Prerequisites​

Before installing Flux-Orbit, ensure you have the following:

Required Software​

  • Docker Desktop (Windows/Mac) or Docker Engine (Linux)

  • Git (for managing your application code)

System Requirements​

  • Memory: Minimum 2GB RAM (4GB recommended)
  • Storage: At least 10GB free disk space
  • Network: Internet connection for pulling images and cloning repositories

Installing Flux-Orbit​

Pull the official Flux-Orbit image from Docker Hub:

docker pull runonflux/orbit:latest

Verify the installation:

docker images | grep runonflux/orbit

Method 2: Building from Source​

Clone the repository and build locally:

# Clone the repository
git clone https://github.com/runonflux/orbit.git
cd orbit

# Build the Docker image
docker build -t flux-orbit:latest .

Verify Installation​

Run a test deployment to verify everything works:

docker run --rm \
  -e GIT_REPO_URL=https://github.com/timlrx/tailwind-nextjs-starter-blog \
  -e APP_PORT=3000 \
  -p 3000:3000 \
  runonflux/orbit:latest

After a few minutes, visit http://localhost:3000 to see the deployed application.

Docker Compose Setup​

For easier management, create a docker-compose.yml:

version: '3.8'

services:
  flux-orbit:
    image: runonflux/orbit:latest
    ports:
      - "3000:3000"
      - "9001:9001"
    environment:
      - GIT_REPO_URL=https://github.com/your/repository
      - APP_PORT=3000
      - NODE_ENV=production
    volumes:
      - app-data:/app
    restart: unless-stopped

volumes:
  app-data:

Start with Docker Compose:

docker-compose up -d

Flux Network Setup​

Deploying on the Flux Network​

You do not need to run a FluxNode to deploy an application. Deploy with Git is built into FluxCloud:

  1. Open FluxCloud, sign in with your Flux ID and choose Register New App.
  2. Pick Deploy with Git, point it at your repository and follow the First Deployment guide.

The rest of this page is only for running your own Flux-Orbit instance locally, for development or self-hosting.

Flux Deployment Configuration​

Example Flux deployment specification:

{
  "name": "my-app",
  "description": "My Application on Flux",
  "image": "runonflux/orbit:latest",
  "port": 3000,
  "environmentParameters": [
    "GIT_REPO_URL=https://github.com/user/repo",
    "APP_PORT=3000",
    "NODE_ENV=production"
  ],
  "resources": {
    "cpu": 1,
    "ram": 2048,
    "storage": 10
  }
}

Updating Flux-Orbit​

To update to the latest version:

# Pull the latest image
docker pull runonflux/orbit:latest

# Stop current container
docker stop my-app

# Remove old container
docker rm my-app

# Start with new image
docker run -d \
  --name my-app \
  -e GIT_REPO_URL=https://github.com/user/repo \
  -e APP_PORT=3000 \
  -p 3000:3000 \
  runonflux/orbit:latest

Uninstalling​

To completely remove Flux-Orbit:

# Stop all Flux-Orbit containers
docker stop $(docker ps -a -q --filter ancestor=runonflux/orbit)

# Remove containers
docker rm $(docker ps -a -q --filter ancestor=runonflux/orbit)

# Remove the image
docker rmi runonflux/orbit:latest

# Remove volumes (optional - this deletes data)
docker volume prune

Troubleshooting Installation​

Docker Not Found​

If you get "docker: command not found":

  • Ensure Docker is installed and running
  • On Linux, you may need to add your user to the docker group: 
    sudo usermod -aG docker $USER
    Then log out and back in

Permission Denied​

If you get permission errors:

  • On Linux/Mac: Use sudo or fix Docker permissions
  • On Windows: Run as Administrator

Port Already in Use​

If port 3000 is already taken:

# Use a different port
docker run -d \
  -e GIT_REPO_URL=https://github.com/user/repo \
  -e APP_PORT=3000 \
  -p 8080:3000 \  # Map to port 8080 instead
  runonflux/orbit:latest

Next Steps​