Docker Prerequisites & Best Practices for Flux

Docker Prerequisites & Best Practices for Flux

Before deploying any application on FluxCloud, you need a working Docker environment, a Docker Hub account, and a Zelcore wallet with FLUX tokens. This guide covers everything you need to set up from scratch — plus the Docker best practices that make or break a successful Flux deployment.

Installing Docker

# Update packages and install prerequisites
sudo apt update && sudo apt install -y ca-certificates curl gnupg

# Add Docker GPG key and repository
sudo install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Install Docker
sudo apt update && sudo apt install -y docker-ce docker-ce-cli containerd.io

# Add your user to the docker group (avoids needing sudo)
sudo usermod -aG docker $USER

# Verify installation
docker --version

On macOS and Windows, download and install Docker Desktop from docker.com. It includes Docker Engine, CLI, and Docker Compose in a single installer.

Docker Hub Account Setup

1. 1

   Create a Docker Hub account

   Sign up at hub.docker.com. Choose a username carefully — it becomes your image namespace (e.g., yourusername/my-app).

2. 2

   Log in via CLI

   Run docker login and enter your credentials. This stores an auth token for pushing images.

3. 3

   Keep images public

   By default, Flux nodes need to pull your Docker image from a public repository. Private images require Enterprise deployment mode (additional fees).

docker login
# Enter your Docker Hub username and password/token

Writing an Optimized Dockerfile for Flux

Docker images deployed on Flux are pulled by every node that runs your app. Smaller images mean faster deployment, less bandwidth usage, and quicker scaling. Follow these best practices:

• •Use alpine base images: node:20-alpine (50MB) instead of node:20 (350MB). Same for python:3.12-alpine, golang:1.22-alpine, etc.
• •Multi-stage builds: Build in one stage, copy only the compiled output to a minimal runtime stage. Dramatically reduces final image size.
• •Minimize layers: Combine RUN commands with && to reduce the number of Docker layers.
• •Use .dockerignore: Exclude node_modules, .git, .env, test files — anything not needed at runtime.
• •Set proper EXPOSE: Declare the port your app listens on. This must match your Flux spec containerPorts.
• •Use CMD, not ENTRYPOINT: CMD is easier to override and debug. Use exec form: CMD ["node", "server.js"].
• •Add health checks: HEALTHCHECK instructions help Flux monitor your container health.

# Build stage
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci --production
COPY . .

# Runtime stage
FROM node:20-alpine
WORKDIR /app
COPY --from=builder /app .
EXPOSE 3000
HEALTHCHECK --interval=30s --timeout=3s \
  CMD wget -qO- http://localhost:3000/health || exit 1
CMD ["node", "server.js"]

FROM python:3.12-alpine
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
EXPOSE 5000
CMD ["python", "app.py"]

Building, Tagging & Pushing

# Build the image
docker build -t yourusername/my-flux-app:latest .

# Test locally
docker run -p 3000:3000 yourusername/my-flux-app:latest

# Push to Docker Hub
docker push yourusername/my-flux-app:latest

Persistent Data with containerData

Flux apps can persist data using the containerData field in the app specification. This mounts a volume at the specified path inside the container. Data stored here survives container restarts on the same node but does not automatically sync between instances unless you use a database with built-in replication.

{
  "containerData": "/appdata"
}

Common Docker Mistakes on Flux

1. 1

   Image is private

   Flux nodes can't pull private images unless you use Enterprise mode. Make sure your Docker Hub repository is set to public.

2. 2

   Wrong port exposed

   The EXPOSE port in your Dockerfile must match the containerPorts in your Flux spec. Mismatches cause the app to appear unreachable.

3. 3

   Image too large

   Images over 1GB take too long to pull and may fail on nodes with slower connections. Use alpine bases and multi-stage builds to stay under 200MB.

4. 4

   No health endpoint

   Without a health check, Flux can't distinguish a crashed app from a slow-starting one. Always add a /health endpoint.

5. 5

   Hardcoded configuration

   Use environment variables for configuration (database URLs, API keys, ports) rather than hardcoding. Flux supports environmentParameters in the spec.