Dockerize for Haloy

Create production-ready Dockerfiles optimized for deployment with haloy.

If the user's request involves docker-compose, multiple containers, or complex orchestration, inform them:

"This skill creates single Dockerfiles for haloy deployment. Haloy works like docker-compose but for production, handling orchestration through its own configuration. If you need multiple services, each should have its own Dockerfile and be defined as separate services in your haloy.yaml. Would you like me to create a Dockerfile for a specific service instead?"

How It Works

1. Detect the project type by examining:

   • package.json with @tanstack/react-start (TanStack Start)
   • package.json with next (Next.js)
   • package.json (Node.js/JavaScript/TypeScript)
   • bun.lockb, pnpm-lock.yaml, package-lock.json, or yarn.lock (Node package manager)
   • requirements.txt, pyproject.toml, Pipfile (Python)
   • uv.lock, poetry.lock, or [tool.poetry] in pyproject.toml (Python package manager)
   • go.mod (Go)
   • Cargo.toml (Rust)
   • Gemfile (Ruby)
   • pom.xml, build.gradle (Java)
   • composer.json (PHP)
   • Other indicators

2. Analyze the application to determine:

   • Build process and dependencies
   • Runtime requirements
   • Entry point / start command
   • Required environment variables
   • Static assets or build outputs

3. Check for health endpoint and ask user about creating one if missing (see Health Check section below)

4. Create an optimized Dockerfile following best practices:

   • Multi-stage builds to reduce image size
   • Appropriate base images (Alpine when possible)
   • Proper layer ordering for cache efficiency
   • Non-root user for security
   • HEALTHCHECK instruction pointing to the health endpoint

5. Provide haloy configuration guidance if no haloy.yaml exists

Health Check Endpoint

A /health endpoint is strongly recommended for all haloy deployments. Before creating the Dockerfile, check if the application has an existing health endpoint.

Why Health Checks Matter

Haloy uses health checks to:

• Zero-downtime deployments: New containers must pass health checks before receiving traffic
• Auto-recovery: Unhealthy containers are automatically restarted
• Deployment validation: Deployments fail fast if the app cannot start properly

Without a health check, haloy cannot verify your application is actually working, which can lead to routing traffic to broken containers.

Check for Existing Health Endpoint

Search for existing health endpoints:

• /health, /healthz, /api/health, /_health
• Look for route definitions returning status 200 or { status: "ok" }

Ask the User

If no health endpoint exists, ask the user:

"Your application doesn't appear to have a health check endpoint. Haloy uses health checks for zero-downtime deployments and auto-recovery. Would you like me to create a /health endpoint?"

If the user agrees, create a minimal health endpoint appropriate for the framework:

TanStack Start (src/routes/health.tsx):

import { createFileRoute } from "@tanstack/react-router";

export const Route = createFileRoute("/health")({
  server: {
    handlers: {
      GET: async () => {
        return Response.json({ status: "ok" });
      },
    },
  },
});

Express/Node.js:

app.get('/health', (req, res) => {
  res.json({ status: 'ok' });
});

Next.js (app/health/route.ts or pages/api/health.ts):

export async function GET() {
  return Response.json({ status: 'ok' });
}

FastAPI:

@app.get("/health")
def health():
    return {"status": "ok"}

Go (net/http):

http.HandleFunc("/health", func(w http.ResponseWriter, r *http.Request) {
    w.Header().Set("Content-Type", "application/json")
    w.Write([]byte(`{"status":"ok"}`))
})

Health Check Best Practices

• Return quickly (avoid database queries in the basic health check)
• Return HTTP 200 for healthy, non-200 for unhealthy
• Keep the response minimal: {"status": "ok"} is sufficient
• Place at a consistent path: /health is the convention

Decision Flow

Use defaults unless a critical value is missing. Only ask the user when needed.

• Health endpoint: Ask only if no existing health route is found.
• Start command: Use existing scripts.start or framework default. Ask if no clear entry point exists.
• Port: Use common defaults (3000 for Node, 8000 for Python) unless a config file or env var specifies a port.
• Package manager: Infer from lockfiles. If none exist, default to npm for Node and pip for Python.

Base Image Versions

IMPORTANT: Always detect the local runtime version to ensure dev/prod consistency. Do not rely on your training data for version numbers.

Version selection priority:

1. Project config files (highest priority) - .nvmrc, .node-version, engines.node, .python-version, go.mod, rust-toolchain.toml, .ruby-version, etc.
2. Local installed version - run the runtime's version command
3. Fallback to references/base-images.md - only if above methods fail

See references/base-images.md for the full version detection guide, config file locations, version-to-tag mappings, and current recommended fallback versions.

Use slim variants by default, alpine for smaller images (some compatibility tradeoffs). Always use specific major.minor tags, never latest.

Dockerfile Best Practices

General Principles

• Use specific version tags, not latest (see Base Image Versions above)
• Minimize layers by combining RUN commands
• Order instructions from least to most frequently changing
• Use .dockerignore to exclude unnecessary files
• Run as non-root user in production
• Include EXPOSE for documentation

Multi-stage Build Pattern

# Build stage (verify current LTS version in references/base-images.md)
FROM node:24-slim AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
ENV NODE_OPTIONS="--max-old-space-size=4096"
RUN npm run build

# Production stage
FROM node:24-slim AS runner
WORKDIR /app
RUN addgroup -g 1001 -S appgroup && adduser -u 1001 -S appuser -G appgroup
COPY --from=builder --chown=appuser:appgroup /app/dist ./dist
COPY --from=builder --chown=appuser:appgroup /app/node_modules ./node_modules
USER appuser
EXPOSE 3000
CMD ["node", "dist/index.js"]

Framework-Specific Considerations

TanStack Start: See references/tanstack-start.md for detailed instructions. Key points:

• Requires "type": "module" in package.json
• Requires vite.config.ts with tanstackStart() and nitro() plugins
• Build output goes to .output/server/index.mjs
• Use Node 24 slim with pnpm via corepack
• Include a /health route for health checks

Next.js: Use standalone output mode, copy .next/standalone and .next/static

Vite/React: Build static files, serve with nginx or a Node server

Python/FastAPI: Use slim images, install with --no-cache-dir

Go: Build static binary, use scratch or distroless for minimal image

Output Format

After creating the Dockerfile, provide output in this order:

1. The complete Dockerfile
2. A .dockerignore file if one doesn't exist
3. Instructions to build and test locally:

   docker build -t myapp .
   docker run -p 3000:3000 myapp
   

4. If no haloy.yaml exists, advise the user:

   "To complete your haloy setup, you'll need a haloy.yaml configuration file. You can either run the /haloy-config skill to generate one, or check the haloy documentation for configuration options."

Reference Files

Read the appropriate reference file for detailed instructions:

• Base Images: references/base-images.md - Current recommended versions for all runtimes (check this first!)
• TanStack Start: references/tanstack-start.md - Complete guide including health checks, database setup, and haloy.yaml examples

When to Create .dockerignore

Always check for an existing .dockerignore. If missing, create one appropriate for the project type. Common exclusions:

node_modules
.git
.env
.env.*
*.log
dist
.next
.output
.vinxi
__pycache__
*.pyc
.venv
target
haloy.yaml

Important: Always include haloy.yaml in .dockerignore. This file is used by haloy for deployment configuration but is not needed inside the container. Excluding it improves Docker layer caching since changes to haloy.yaml (like updating domains or environment variables) won't invalidate the build cache.