Building Images

HYPR builds images from Dockerfiles using an isolated build process.

Basic Build

hypr build -t myapp:latest .

This parses the Dockerfile, executes each instruction, and produces a squashfs image.

Build Process

Parse Dockerfile - Validate syntax, extract stages and instructions
Resolve Base Image - Pull base image from registry if not cached
Execute Instructions - Run each instruction in an isolated build VM
Create Layers - Cache each layer for incremental builds
Generate Squashfs - Compress final rootfs to squashfs format
Store Manifest - Save image metadata (entrypoint, env, ports, etc.)

Supported Instructions

FROM

Set base image for the build stage.

FROM alpine:3.19
FROM golang:1.21 AS builder
FROM scratch
FROM --platform=linux/amd64 ubuntu:22.04

RUN

Execute commands during build.

# Shell form
RUN apt-get update && apt-get install -y nginx

# Exec form
RUN ["apt-get", "update"]

COPY

Copy files from build context or previous stage.

# From build context
COPY src/ /app/src/
COPY package.json package-lock.json ./

# From previous stage
COPY --from=builder /app/binary /usr/local/bin/

# With ownership
COPY --chown=nginx:nginx config/ /etc/nginx/

ADD

Copy files with automatic extraction.

ADD archive.tar.gz /app/
ADD https://example.com/file.txt /app/

ENV

Set environment variables.

# Single variable
ENV NODE_ENV production

# Multiple variables
ENV NODE_ENV=production DEBUG=false PORT=3000

ARG

Define build-time variables.

ARG VERSION=1.0
ARG BUILD_DATE

FROM alpine:3.19
RUN echo "Building version $VERSION"

Pass values at build time:

hypr build --build-arg VERSION=2.0 -t myapp .

WORKDIR

Set working directory.

WORKDIR /app
RUN pwd  # outputs /app

USER

Set the user for subsequent instructions and runtime.

USER nginx
USER 1000:1000

EXPOSE

Document exposed ports.

EXPOSE 80
EXPOSE 443/tcp
EXPOSE 53/udp

ENTRYPOINT

Set the executable.

# Exec form (recommended)
ENTRYPOINT ["nginx", "-g", "daemon off;"]

# Shell form
ENTRYPOINT nginx -g "daemon off;"

CMD

Set default arguments.

# Exec form
CMD ["--config", "/etc/nginx/nginx.conf"]

# Combined with ENTRYPOINT
ENTRYPOINT ["nginx"]
CMD ["-g", "daemon off;"]

VOLUME

Declare mount points.

VOLUME /data
VOLUME ["/data", "/logs"]

LABEL

Add metadata.

LABEL version="1.0"
LABEL maintainer="team@example.com"

HEALTHCHECK

Define health check command.

HEALTHCHECK --interval=30s --timeout=3s --retries=3 \
  CMD curl -f http://localhost/ || exit 1

SHELL

Set default shell.

SHELL ["/bin/bash", "-c"]
RUN echo $SHELL

STOPSIGNAL

Set stop signal.

STOPSIGNAL SIGTERM

Multi-Stage Builds

Use multiple FROM instructions to create smaller final images.

# Build stage
FROM golang:1.21 AS builder
WORKDIR /app
COPY . .
RUN go build -o myapp

# Runtime stage
FROM alpine:3.19
COPY --from=builder /app/myapp /usr/local/bin/
CMD ["myapp"]

Build specific stage:

hypr build --target builder -t myapp:builder .

Build Arguments

Define with ARG in Dockerfile:

ARG GO_VERSION=1.21
FROM golang:${GO_VERSION}

Pass at build time:

hypr build --build-arg GO_VERSION=1.22 -t myapp .

Build Cache

HYPR caches layers based on instruction content. Cache is invalidated when:

Dockerfile instruction changes
Files copied by COPY/ADD change
Base image changes
Build argument values change

Disable cache:

hypr build --no-cache -t myapp .

Clear all cached layers:

hypr system prune

Image Storage

Built images are stored in /var/lib/hypr/images/ as squashfs files with accompanying manifest JSON. List images:

hypr images

Example Dockerfiles

Node.js Application

FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM node:20-alpine
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
EXPOSE 3000
CMD ["node", "dist/index.js"]

Go Application

FROM golang:1.22-alpine AS builder
WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 go build -o server

FROM alpine:3.19
RUN apk add --no-cache ca-certificates
COPY --from=builder /app/server /usr/local/bin/
EXPOSE 8080
CMD ["server"]

Python Application

FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
EXPOSE 8000
CMD ["python", "-m", "uvicorn", "main:app", "--host", "0.0.0.0"]

Managing Images

List local images:

hypr images

Remove an image:

hypr rmi myapp:latest

Force remove:

hypr rmi -f myapp:latest

Inspect image:

hypr image inspect myapp:latest

Remove unused images:

hypr image prune        # Dangling only
hypr image prune --all  # All unused

Compose Builds

Build images as part of stack deployment:

services:
  api:
    build:
      context: ./api
      dockerfile: Dockerfile.prod
      args:
        VERSION: "1.0"
      target: production

Deploy with build:

hypr compose up --build

Limitations

No Network During Build

Build VMs have no network access for security. All dependencies must be:

Included in the base image
Added to the build context
Downloaded in a previous multi-stage build

Platform-Specific

Images are built for the current platform (x86_64 or ARM64). Cross-platform builds are not supported.

Not BuildKit

HYPR uses its own build implementation. Some advanced BuildKit features are not supported:

Secret mounts (--mount=type=secret)
SSH mounts (--mount=type=ssh)
Cache mounts (--mount=type=cache)
Git context URLs

Best Practices

Use multi-stage builds to minimize image size
Order instructions by change frequency (stable first)
Combine RUN commands to reduce layers
Use .dockerignore to exclude unnecessary files
Set USER to avoid running as root
Define HEALTHCHECK for container health monitoring
Use specific tags instead of latest for reproducibility

Troubleshooting

Build Fails

Check Dockerfile syntax
View build output for error messages
Verify base image is available
Ensure context files exist

Out of Space

hypr system df
hypr system prune

Cache Not Working

Cache is invalidated when instruction or context files change. Use --no-cache to force rebuild.

​Building Images

​Basic Build

​Build Process

​Supported Instructions

​FROM

​RUN

​COPY

​ADD

​ENV

​ARG

​WORKDIR

​USER

​EXPOSE

​ENTRYPOINT

​CMD

​VOLUME

​LABEL

​HEALTHCHECK

​SHELL

​STOPSIGNAL

​Multi-Stage Builds

​Build Arguments

​Build Cache

​Image Storage

​Example Dockerfiles

​Node.js Application

​Go Application

​Python Application

​Managing Images

​Compose Builds

​Limitations

​No Network During Build

​Platform-Specific

​Not BuildKit

​Best Practices

​Troubleshooting

​Build Fails

​Out of Space

​Cache Not Working