Deploying Your First App

Deploying Your First App

This guide walks you through every step of deploying a Docker application on the Flux decentralized network — from preparing your container image to verifying your running instances. By the end, you will have a live, globally distributed application accessible via a public URL.

Prerequisites

• •Docker image in a public container registry (Docker Hub, GitHub Container Registry, or any publicly accessible registry)
• •FLUX tokens in your wallet to cover deployment and at least one month of hosting fees
• •Zel ID — a Flux identity used to sign transactions and manage your apps (created via the Zelcore wallet app)
• •Zelcore wallet installed on your desktop or mobile device for signing deployment transactions

Step 1: Prepare Your Docker Image

Your application must be packaged as a Docker image and pushed to a public registry. Here is an example using a simple Node.js web server.

FROM node:20-alpine

WORKDIR /app

COPY package*.json ./
RUN npm ci --only=production

COPY . .

EXPOSE 3000

CMD ["node", "server.js"]

Build, tag, and push the image to Docker Hub (or your preferred public registry):

# Build the image
docker build -t myusername/myfluxapp:latest .

# Test locally before deploying
docker run -p 3000:3000 myusername/myfluxapp:latest

# Push to Docker Hub
docker login
docker push myusername/myfluxapp:latest

Step 2: Access the Flux Deployment Interface

Navigate to home.runonflux.io in your web browser. This is the FluxOS marketplace and management dashboard. Click "Connect" in the top-right corner and log in with your Zel ID. You can sign in by scanning a QR code with the Zelcore mobile app or by entering your Zel ID credentials directly.

Once authenticated, navigate to "My Apps" from the sidebar, then click "Register Flux App" to open the deployment form.

Step 3: Define the App Specification

The deployment form requires you to fill in the app specification. Each field controls how your container is launched and managed on the network. Here is a complete example specification:

{
  "name": "my-web-app",
  "description": "A Node.js web application deployed on Flux",
  "owner": "YOUR_ZEL_ID_HERE",
  "compose": [
    {
      "name": "mywebapp",
      "description": "Main web server",
      "repotag": "myusername/myfluxapp:latest",
      "ports": [3000],
      "domains": [""],
      "environmentParameters": [
        "NODE_ENV=production",
        "LOG_LEVEL=info"
      ],
      "commands": [],
      "containerPorts": [3000],
      "containerData": "/app/data",
      "cpu": 0.5,
      "ram": 512,
      "hdd": 2,
      "tipiered": false,
      "secrets": "",
      "repoauth": ""
    }
  ],
  "instances": 3,
  "contacts": [""],
  "geolocation": []
}

Key fields explained:

• •name — Unique app name across the entire Flux network. Must be lowercase alphanumeric with hyphens only. This becomes part of your default URL.
• •repotag — The full Docker image reference, e.g., myusername/myfluxapp:latest.
• •ports — The external port(s) your app will be reachable on. Flux maps these from the container ports.
• •containerPorts — The port(s) your container listens on internally (must match the EXPOSE in your Dockerfile).
• •environmentParameters — Environment variables passed to the container at runtime. Format: KEY=VALUE.
• •containerData — The path inside the container to mount persistent storage. Data in this directory survives container restarts.
• •cpu — CPU cores allocated (e.g., 0.5 for half a core). Must be within the tier limit.
• •ram — RAM in megabytes (e.g., 512 for 512 MB).
• •hdd — Persistent SSD storage in gigabytes.
• •instances — Number of instances to run (minimum 3, typical values: 3, 5, or 7).

Step 4: Choose the Deployment Tier

Based on the resource requirements you specified, the interface will indicate which tier your app falls into. The tier is determined automatically by the highest resource value you request:

If any single resource exceeds the Cumulus limit, your app will be deployed on Nimbus nodes. If any resource exceeds the Nimbus limit, it will require Stratus nodes. Higher tiers cost more but provide access to more powerful hardware.

Step 5: Calculate Cost & Submit

The deployment interface displays an estimated monthly cost in FLUX before you submit. The cost formula accounts for CPU, RAM, HDD, and the number of instances. Review the cost carefully — you are paying for one month upfront. Click "Register Flux App" to proceed.

Step 6: Sign the Transaction

After clicking register, a signing request is sent to your Zelcore wallet. Open Zelcore and approve the transaction. This signs the app specification with your Zel ID and broadcasts it to the Flux blockchain. The transaction is confirmed within a few minutes as it is included in a block.

Step 7: Wait for Deployment

Once the registration transaction is confirmed on-chain, FluxOS nodes begin the deployment process. Eligible nodes detect the new app, pull the Docker image, and start the container. This process typically takes 5-15 minutes depending on the size of your Docker image and current network activity. You can monitor the deployment status from the "My Apps" section of the dashboard.

During deployment, you will see the status progress through several stages: Registered (on-chain but not yet deployed), Spawning (nodes are pulling the image), and Running (all instances are live).

Step 8: Verify Your App Is Running

Once all instances are running, your app is accessible at its default URL. You can also verify each individual instance:

# Access via default Flux hostname
curl https://my-web-app.app.runonflux.io

# Check individual instance IPs (shown in dashboard)
curl http://<node-ip>:<port>

# View running instances via Flux API
curl https://api.runonflux.io/apps/location/my-web-app

The dashboard shows each instance with its hosting node IP address, uptime, and health status. Click on an individual instance to view its container logs, resource utilization, and restart history.

Monitoring Your Deployed App

The FluxOS dashboard provides real-time monitoring for all your deployed apps. Key metrics include container CPU and memory usage, network I/O, and uptime per instance. You can view live logs by selecting an instance and clicking "Logs". If an instance becomes unhealthy, FluxOS automatically migrates it to a new node — this process is called app respawning and happens transparently.

Updating Your App

To update a running app (deploy a new version of your Docker image), push the updated image to your registry with the same tag, then go to "My Apps" in the dashboard and click "Redeploy". This triggers all instances to pull the latest version of the image and restart. Alternatively, you can modify the app specification (e.g., change environment variables, adjust resource limits, or change the image tag) by submitting an app update transaction.

# Build and push the updated image
docker build -t myusername/myfluxapp:latest .
docker push myusername/myfluxapp:latest

# Then click "Redeploy" in the FluxOS dashboard,
# or use the Flux API:
# POST to the app update endpoint via the dashboard UI

Congratulations — you now have a live, decentralized application running on the Flux network. From here, you can configure custom domains, set up SSL, tune resource allocations, and scale your instance count. Refer to the App Specifications & Pricing article for detailed resource limits and the Custom Domains & SSL article for domain configuration.