Dockerfile vs Compose File: Understanding the Core Differences

When working with containerized applications, you'll encounter two essential configuration files: Dockerfiles and Compose files. While both are integral to container workflows, they serve fundamentally different purposes and operate at different levels of abstraction. Understanding these differences is crucial for effectively managing containerized applications.

Fundamental Purpose and Scope

Dockerfile: Building Individual Images

A Dockerfile is a text document containing instructions for building a single Docker image. It defines what goes inside a container at the image level, specifying the base operating system, application code, dependencies, and configuration needed to create a reproducible image.

The Dockerfile answers the question: "How do I build this container image?"

Compose File: Orchestrating Multiple Containers

A Compose file (typically named docker-compose.yml) is a YAML configuration file that defines and manages multi-container applications. It describes how multiple services work together, their relationships, and how they should be deployed as a cohesive application.

The Compose file answers the question: "How do I run and connect these containers together?"

File Format and Syntax

Dockerfile Format

Dockerfiles use a custom instruction-based syntax with uppercase commands followed by arguments:

FROM ubuntu:22.04
RUN apt-get update && apt-get install -y python3
COPY . /app
WORKDIR /app
CMD ["python3", "app.py"]

Each instruction creates a layer in the final image, and the order matters significantly for build optimization.

Compose File Format

Compose files use YAML syntax with a hierarchical structure organized into top-level sections:

version: '3.8'

services:
  web:
    image: nginx:latest
    ports:
      - "8080:80"
  
  database:
    image: postgres:14
    environment:
      POSTGRES_PASSWORD: secret

The structure is declarative, describing the desired state of your application stack.

Build-Time vs Runtime Configuration

Dockerfile: Build-Time Instructions

Dockerfiles execute during the image build process. Every instruction runs sequentially when you execute docker build, creating immutable image layers. Once built, the image remains static until you rebuild it.

Key build-time aspects:

• Installing system packages
• Copying source code
• Compiling applications
• Setting default environment variables
• Defining exposed ports (metadata only)
• Specifying default commands

Compose File: Runtime Orchestration

Compose files execute when you start your application. They define how containers should run, interact, and be configured when launched. Changes to the Compose file affect how containers are created and connected, not the underlying images.

Key runtime aspects:

• Container startup configuration
• Port mapping to host
• Volume mounting
• Container naming and labeling
• Resource constraints (CPU, memory)
• Restart policies
• Dependency management between containers

Single vs Multiple Container Management

Dockerfile: One Image at a Time

Each Dockerfile builds exactly one image. If your application requires multiple components (web server, database, cache), you need separate Dockerfiles for each component. The Dockerfile has no concept of multiple services or their interactions.

Example project structure:

project/
├── web/
│   └── Dockerfile
├── api/
│   └── Dockerfile
└── worker/
    └── Dockerfile

Compose File: Multi-Service Orchestration

A single Compose file can define dozens of services, each potentially using different images (built from Dockerfiles or pulled from registries). The Compose file establishes relationships between these services, creating a complete application topology.

Example structure:

services:
  frontend:
    build: ./web
  backend:
    build: ./api
  worker:
    build: ./worker
  database:
    image: postgres:14
  cache:
    image: redis:7

Image Creation vs Image Usage

Dockerfile: Creates Images

The primary output of a Dockerfile is a Docker image—a packaged, portable artifact that can be distributed and run anywhere Docker is available. The Dockerfile contains all instructions needed to reproduce this image from scratch.

Process flow:

1. Write Dockerfile with build instructions
2. Run docker build command
3. Docker executes each instruction sequentially
4. Result: A tagged image stored locally or pushed to a registry

Compose File: Uses Images

Compose files reference existing images (either pre-built from registries or built via referenced Dockerfiles). The Compose file doesn't create images itself; it orchestrates containers created from those images.

Process flow:

1. Define services in Compose file
2. Reference images (or point to Dockerfiles)
3. Run docker compose up
4. Compose pulls/builds images if needed, then creates and starts containers

Layer Caching and Optimization

Dockerfile: Layer-Based Build Cache

Dockerfiles benefit from layer caching during builds. Docker caches each instruction's result as a layer, and subsequent builds reuse cached layers when instructions haven't changed. This makes rebuilds faster.

Optimization strategy:

# Cache-friendly order
FROM node:18
WORKDIR /app

# Dependencies change less frequently - cache these layers
COPY package*.json ./
RUN npm install

# Code changes frequently - place last
COPY . .
RUN npm run build

Compose File: No Layer Caching

Compose files don't have layer caching because they don't build anything. However, when a Compose file references a Dockerfile via the build directive, the image building process still benefits from Docker's layer caching.

The Compose file itself is simply parsed and executed—there's no incremental caching mechanism for the Compose configuration.

Portability and Distribution

Dockerfile: Portable Build Instructions

Dockerfiles are highly portable. You can share a Dockerfile with anyone, and they can build an identical image on their system (assuming they have access to the same base images and resources). The Dockerfile serves as both documentation and executable specification.

Distribution pattern:

• Share Dockerfile in source control
• Others build images locally
• Or build once and push image to registry for others to pull

Compose File: Environment-Specific Configuration

Compose files often contain environment-specific configurations (port mappings, volume paths, environment variables) that may differ between development, staging, and production environments. They're less universally portable than Dockerfiles.

Common practice:

# docker-compose.yml (base configuration)
# docker-compose.override.yml (local overrides)
# docker-compose.prod.yml (production overrides)

Command Execution Context

Dockerfile: Build-Time Execution

Commands in a Dockerfile execute during image creation, within the build container's filesystem. These commands can install software, compile code, or modify the filesystem, but they cannot interact with the host system or other containers.

# Executes during build, inside container
RUN apt-get update && apt-get install -y curl
RUN curl -o /app/data.json https://api.example.com/data

Compose File: Container Runtime Configuration

The Compose file configures how commands run when containers start. It can specify the command to execute, working directory, and user, but doesn't execute commands during parsing.

services:
  app:
    image: myapp
    command: python manage.py runserver 0.0.0.0:8000
    working_dir: /app
    user: appuser

Dependency and Build Order

Dockerfile: Sequential Instruction Processing

Dockerfiles execute instructions strictly in order, from top to bottom. Each instruction depends on the completion of previous instructions. There's no parallel execution or dependency declaration—the order defines the dependency chain.

FROM python:3.11
# Must install dependencies before copying code
RUN pip install flask
COPY app.py /app/
# CMD only defines what runs later, doesn't execute during build
CMD ["python", "/app/app.py"]

Compose File: Service Dependency Declaration

Compose files allow explicit dependency declaration between services using depends_on. This controls startup order and can wait for services to be ready before starting dependent services.

services:
  web:
    image: webapp
    depends_on:
      database:
        condition: service_healthy
  
  database:
    image: postgres:14
    healthcheck:
      test: ["CMD", "pg_isready"]
      interval: 5s

Configuration Inheritance and Reusability

Dockerfile: Multi-Stage Builds

Dockerfiles support multi-stage builds, allowing you to use multiple FROM statements and copy artifacts between stages. This enables build optimization and smaller final images without requiring multiple separate Dockerfiles.

# Build stage
FROM node:18 AS builder
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
RUN npm run build

# Production stage
FROM node:18-slim
WORKDIR /app
COPY --from=builder /app/dist ./dist
CMD ["node", "dist/server.js"]

Compose File: Service Extension and Anchors

Compose files support YAML anchors and aliases for reusing configuration blocks, plus extension fields for shared configuration. This reduces duplication across services with similar configurations.

x-common-variables: &common-vars
  ENVIRONMENT: production
  LOG_LEVEL: info

services:
  api:
    image: myapi
    environment:
      <<: *common-vars
      SERVICE_NAME: api
  
  worker:
    image: myworker
    environment:
      <<: *common-vars
      SERVICE_NAME: worker

Platform and Architecture Specifications

Dockerfile: Build-Time Platform Selection

Dockerfiles can specify target platforms during build, creating multi-architecture images. The --platform flag during build determines which architecture-specific base images to use.

# Will use appropriate base image for target platform
FROM --platform=$BUILDPLATFORM golang:1.21 AS builder
ARG TARGETPLATFORM
ARG BUILDPLATFORM
RUN echo "Building on $BUILDPLATFORM for $TARGETPLATFORM"

Compose File: Runtime Platform Specification

Compose files specify which platform architecture containers should run on. This is particularly useful for running containers on systems with different architectures (like ARM Macs).

services:
  app:
    image: myapp
    platform: linux/amd64  # Force AMD64 even on ARM systems

Resource Specification

Dockerfile: No Resource Constraints

Dockerfiles cannot specify runtime resource constraints like CPU or memory limits. These are build-time instruction sets focused solely on image content, not runtime behavior.

You can document recommended resource requirements in comments, but enforcement happens at runtime, not build time.

Compose File: Runtime Resource Management

Compose files directly specify resource constraints that Docker enforces when containers run. This includes CPU shares, memory limits, and other runtime resource policies.

services:
  database:
    image: postgres:14
    deploy:
      resources:
        limits:
          cpus: '2'
          memory: 2G
        reservations:
          cpus: '1'
          memory: 1G

Metadata and Labeling

Dockerfile: Image-Level Metadata

Dockerfiles use the LABEL instruction to add metadata to images. This metadata persists with the image and appears in image inspection. Labels typically describe the image contents, version, maintainer, and other image-specific information.

FROM ubuntu:22.04
LABEL maintainer="dev@example.com"
LABEL version="1.0"
LABEL description="Application server image"
LABEL org.opencontainers.image.source="https://github.com/example/app"

Compose File: Container-Level Metadata

Compose files add labels to running containers, not images. These labels help organize and manage containers at runtime, useful for filtering, grouping, and monitoring purposes.

services:
  web:
    image: nginx
    labels:
      com.example.department: "engineering"
      com.example.team: "platform"
      com.example.environment: "production"

Exposed Ports vs Port Mapping

Dockerfile: Port Documentation

The EXPOSE instruction in Dockerfiles documents which ports the container listens on. This is purely informational metadata—it doesn't actually publish or map ports. EXPOSE serves as documentation for users and other tools about the container's network interface.

FROM node:18
COPY . /app
WORKDIR /app
EXPOSE 3000 8080  # Documents that app listens on these ports
CMD ["node", "server.js"]

Compose File: Actual Port Mapping

Compose files perform real port mapping, binding container ports to host system ports. This creates accessible network endpoints. The mapping is functional, not just documentation.

services:
  web:
    image: webapp
    ports:
      - "80:3000"      # Host:Container
      - "443:8443"
      - "8080-8085:8080-8085"  # Range mapping

Variable Substitution and Templating

Dockerfile: Build Arguments

Dockerfiles support build-time variables through ARG instructions. These variables exist only during build and can be passed via docker build --build-arg. They don't persist in the final image unless explicitly set as environment variables.

FROM ubuntu:22.04
ARG APP_VERSION=1.0.0
ARG BUILD_DATE
LABEL version="${APP_VERSION}"
LABEL build_date="${BUILD_DATE}"
RUN echo "Building version ${APP_VERSION}"

Compose File: Environment Variable Interpolation

Compose files support variable substitution using shell-style syntax. Variables come from the environment, shell exports, or .env files. This enables dynamic configuration at runtime.

services:
  web:
    image: webapp:${VERSION:-latest}
    environment:
      DATABASE_HOST: ${DB_HOST}
      API_KEY: ${API_KEY:-default_key}
    ports:
      - "${WEB_PORT:-8080}:80"

Default Behavior and Overrides

Dockerfile: Default Container Behavior

Dockerfiles define default behavior using CMD and ENTRYPOINT instructions. CMD provides default arguments that can be overridden when running the container. ENTRYPOINT sets the executable that runs, which is harder to override.

FROM python:3.11
COPY app.py /app/
WORKDIR /app

# Default executable
ENTRYPOINT ["python"]

# Default arguments (can be overridden)
CMD ["app.py"]

When running: docker run myimage test.py overrides CMD but keeps ENTRYPOINT.

Compose File: Service-Level Overrides

Compose files can override image defaults at the service level. The command key replaces CMD, and entrypoint replaces ENTRYPOINT. This provides deployment-specific behavior without rebuilding images.

services:
  app:
    image: myapp
    entrypoint: /usr/local/bin/custom-entry.sh
    command: ["--mode", "production", "--workers", "4"]

Security Contexts

Dockerfile: Build-Time Security Configuration

Dockerfiles can set the user context for subsequent instructions and for the default container runtime using the USER instruction. This determines under which user account processes run inside the container.

FROM node:18

# Create non-root user
RUN groupadd -r appuser && useradd -r -g appuser appuser

WORKDIR /app
COPY --chown=appuser:appuser . .

# Switch to non-root user
USER appuser

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

Compose File: Runtime Security Options

Compose files specify security options that apply when containers start, including user overrides, capabilities, security labels, and privileged mode. These runtime settings take precedence over Dockerfile USER instructions.

services:
  app:
    image: myapp
    user: "1000:1000"
    cap_drop:
      - ALL
    cap_add:
      - NET_BIND_SERVICE
    security_opt:
      - no-new-privileges:true
    read_only: true

Handling Secrets and Sensitive Data

Dockerfile: Build-Time Secrets Challenge

Traditional Dockerfiles have security challenges with secrets since anything added during build becomes part of image layers. Even deleted secrets remain in image history. Docker BuildKit introduces secret mounting for secure build-time secret access.

# syntax=docker/dockerfile:1
FROM python:3.11

# Modern approach: mount secrets without storing in layers
RUN --mount=type=secret,id=pip_config \
    pip config set global.index-url $(cat /run/secrets/pip_config)

RUN --mount=type=secret,id=ssh_key \
    mkdir -p ~/.ssh && \
    cp /run/secrets/ssh_key ~/.ssh/id_rsa

Compose File: Runtime Secret Management

Compose files declare secrets that get injected into containers at runtime without being stored in environment variables or container layers. Secrets are mounted as files in the container filesystem.

services:
  app:
    image: myapp
    secrets:
      - db_password
      - api_key

secrets:
  db_password:
    file: ./secrets/db_password.txt
  api_key:
    external: true

Testing and Validation

Dockerfile: Build Validation

Dockerfile correctness is validated during build. Syntax errors, invalid base images, or failed RUN commands cause build failures. You can test Dockerfiles by building them and running resulting containers.

FROM python:3.11

# Validation happens during build
RUN python --version

# This line will cause build failure if file doesn't exist
COPY requirements.txt .
RUN pip install -r requirements.txt

# Test command runs during build
RUN python -c "import flask; print('Dependencies OK')"

Compose File: Syntax Validation

Compose files are validated when parsed. The docker compose config command validates syntax and shows the resolved configuration with variables substituted. This doesn't validate image availability or runtime behavior.

# Validate Compose file syntax
docker compose config

# Validate specific compose file
docker compose -f docker-compose.prod.yml config

# Check for syntax errors and variable interpolation
docker compose config --quiet

Build Context and File Access

Dockerfile: Build Context Scope

Dockerfiles can only access files within the build context (the directory specified during docker build). The .dockerignore file excludes files from the build context, improving build performance and security.

FROM node:18
WORKDIR /app

# Can only COPY from build context
COPY package*.json ./
COPY src/ ./src/

# Cannot access files outside build context
# COPY /etc/passwd /tmp/  # Would fail
# COPY ../other-project/lib /app/lib  # Would fail

Compose File: Volume Mount Flexibility

Compose files can mount any host directory into containers, regardless of where the Compose file is located. This provides flexible file access patterns for development and deployment.

services:
  app:
    image: myapp
    volumes:
      # Relative to Compose file location
      - ./src:/app/src
      # Absolute paths
      - /var/log/myapp:/app/logs
      # User home directory
      - ~/configs:/app/configs

Image Registry Interaction

Dockerfile: No Registry Operations

Dockerfiles don't interact with container registries. They define how to build images but don't specify where images should be pushed or pulled from. Registry operations happen through separate docker push/pull commands.

# Dockerfile doesn't specify registry
FROM ubuntu:22.04
# Build produces local image
# Push to registry is separate operation

Compose File: Image References and Pull Behavior

Compose files explicitly reference images including registry paths. Compose automatically pulls missing images from registries when services start, and the build directive can specify where to push built images.

services:
  app:
    image: registry.example.com/myorg/myapp:v1.2.3
    # Compose pulls from registry if not local
  
  custom:
    build:
      context: ./app
      tags:
        - registry.example.com/myorg/custom:latest
        - registry.example.com/myorg/custom:v1.0

Conditional Logic and Flow Control

Dockerfile: Limited Conditional Support

Dockerfiles have minimal conditional logic. Multi-stage builds provide some branching capability, and shell commands within RUN can use shell conditionals, but there's no native Dockerfile syntax for if/else logic.

FROM node:18 AS base

FROM base AS development
RUN npm install --include=dev

FROM base AS production
RUN npm install --omit=dev

# Choose final stage based on build argument
ARG BUILD_TYPE=production
FROM ${BUILD_TYPE} AS final

Compose File: Profile-Based Conditionals

Compose files use profiles to conditionally include or exclude services. Services tagged with profiles only start when those profiles are activated, enabling environment-specific configurations.

services:
  web:
    image: webapp
    # Always runs
  
  debug:
    image: debugger
    profiles:
      - debugging
    # Only runs with: docker compose --profile debugging up
  
  test-db:
    image: postgres:14
    profiles:
      - testing
    # Only runs with: docker compose --profile testing up

Configuration Complexity and Readability

Dockerfile: Linear Instruction Flow

Dockerfiles follow a linear, imperative style. Each instruction performs an action, and complexity comes from the number of instructions and shell commands within RUN statements. The format is relatively simple to understand.

FROM python:3.11-slim

# Simple, sequential instructions
RUN apt-get update && \
    apt-get install -y --no-install-recommends \
        build-essential \
        libpq-dev && \
    apt-get clean && \
    rm -rf /var/lib/apt/lists/*

WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .

EXPOSE 8000
CMD ["gunicorn", "app:app"]

Compose File: Nested Hierarchical Structure

Compose files use nested YAML structures with multiple levels of configuration. Complexity grows with the number of services and configuration options. The declarative format describes desired state rather than steps.

version: '3.8'

services:
  web:
    image: webapp:latest
    deploy:
      replicas: 3
      resources:
        limits:
          cpus: '0.5'
          memory: 512M
      restart_policy:
        condition: on-failure
        delay: 5s
        max_attempts: 3
    ports:
      - "80:8000"
    environment:
      DATABASE_URL: postgresql://db:5432/appdb
    depends_on:
      database:
        condition: service_healthy
  
  database:
    image: postgres:14
    environment:
      POSTGRES_DB: appdb
      POSTGRES_USER: appuser
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U appuser"]
      interval: 10s
      timeout: 5s
      retries: 5

Versioning and Updates

Dockerfile: Image Version Control

Dockerfiles should be version-controlled alongside application code. Changes to the Dockerfile require rebuilding images and potentially retagging. Version control tracks how image construction evolves over time.

FROM node:18.17.1  # Specific version for reproducibility

LABEL version="2.1.0"  # Image version
LABEL git.commit="${GIT_COMMIT}"  # Can be set via build arg

# Dependencies with versions
RUN npm install -g pm2@5.3.0

Compose File: Configuration Version Control

Compose files are version-controlled to track infrastructure changes. Compose file version (specified at the top) determines available features. Updating the Compose file changes how existing images run, without rebuilding images.

version: '3.8'  # Compose file format version

services:
  app:
    image: myapp:2.1.0  # Reference specific image version
    # Configuration changes don't require rebuilding image
    environment:
      CONFIG_VERSION: "2024.12"

Health Monitoring and Checks

Dockerfile: Basic Health Definition

Dockerfiles can define a basic HEALTHCHECK instruction that runs a command to verify container health. This check becomes part of the image specification and runs automatically in containers created from the image.

FROM nginx:latest

COPY healthcheck.sh /usr/local/bin/
RUN chmod +x /usr/local/bin/healthcheck.sh

# Simple health check definition
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
    CMD /usr/local/bin/healthcheck.sh

Compose File: Advanced Health Configuration

Compose files provide more sophisticated health check configuration with additional options and override capabilities. Health checks can be defined or overridden per service, and other services can wait for health status before starting.

services:
  database:
    image: postgres:14
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U $$POSTGRES_USER"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 10s
  
  app:
    image: myapp
    depends_on:
      database:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8000/health"]
      interval: 15s
      timeout: 10s
      retries: 3
      start_period: 30s

Build Arguments vs Environment Variables

Dockerfile: Build-Time ARG vs Runtime ENV

Dockerfiles distinguish between ARG (build-time only) and ENV (runtime) variables. ARG values don't persist in the final image unless explicitly copied to ENV. This separation maintains security and flexibility.

FROM ubuntu:22.04

# Build-time only - not in final image
ARG BUILD_VERSION=1.0.0
ARG DEBIAN_FRONTEND=noninteractive

# Runtime variables - available in container
ENV APP_VERSION=${BUILD_VERSION}
ENV APP_HOME=/opt/app
ENV PATH="${APP_HOME}/bin:${PATH}"

RUN echo "Building version ${BUILD_VERSION}"

Compose File: Runtime Environment Variables

Compose files exclusively deal with runtime environment variables. These variables are set when containers start and can come from multiple sources: inline definitions, environment files, or shell environment.

services:
  app:
    image: myapp
    environment:
      # Direct definition
      APP_ENV: production
      DATABASE_HOST: db
      # Reference from shell
      API_KEY: ${API_KEY}
    env_file:
      # Load from file
      - ./config/common.env
      - ./config/prod.env

Signal Handling and Shutdown

Dockerfile: Default Signal Behavior

Dockerfiles can influence signal handling through ENTRYPOINT and CMD choices. Using shell form wraps commands in /bin/sh -c, which may not properly forward signals. Exec form provides direct process execution with proper signal handling.

FROM python:3.11

# Shell form - signals go to shell, not python
# CMD python app.py

# Exec form - signals go directly to python
CMD ["python", "app.py"]

# Custom entrypoint for signal handling
COPY entrypoint.sh /
ENTRYPOINT ["/entrypoint.sh"]
CMD ["python", "app.py"]

Compose File: Shutdown Configuration

Compose files configure container stop behavior including stop signals and grace periods. This ensures clean shutdowns with proper signal delivery and timeout handling.

services:
  app:
    image: myapp
    stop_signal: SIGTERM
    stop_grace_period: 30s
    # Container gets SIGTERM, waits 30s, then SIGKILL
  
  worker:
    image: worker
    stop_signal: SIGINT
    stop_grace_period: 1m
    # Longer grace period for job completion

Filesystem Ownership and Permissions

Dockerfile: Build-Time Ownership

Dockerfiles set file ownership and permissions during image construction using RUN commands with chown/chmod or COPY's --chown flag. These settings become part of the image's filesystem layers.

FROM node:18

# Create user during build
RUN groupadd -r appuser && \
    useradd -r -g appuser -d /home/appuser -s /bin/bash appuser && \
    mkdir -p /home/appuser && \
    chown -R appuser:appuser /home/appuser

WORKDIR /app

# Set ownership during copy
COPY --chown=appuser:appuser package*.json ./
COPY --chown=appuser:appuser . .

# Set specific permissions
RUN chmod +x /app/scripts/*.sh && \
    chmod 600 /app/configs/*.key

USER appuser

Compose File: Runtime Mount Permissions

Compose files handle permissions for volume mounts at runtime. Host directory permissions affect mounted volumes, and Compose can specify user context for running containers, but it doesn't modify filesystem permissions within images.

services:
  app:
    image: myapp
    user: "1000:1000"  # Run as specific UID:GID
    volumes:
      - ./app:/app  # Host permissions apply
      - uploads:/app/uploads  # Named volume
    tmpfs:
      - /app/temp:mode=1777  # Writable temp directory

Documentation and Self-Description

Dockerfile: Build Process Documentation

Dockerfiles serve as executable documentation for image creation. Comments explain build steps, and the instruction sequence itself documents the build process. LABELs add structured metadata.

FROM python:3.11-slim

# Document base image choice
# Using slim variant to reduce image size

# Install system dependencies for PostgreSQL driver
RUN apt-get update && \
    apt-get install -y --no-install-recommends \
        libpq-dev \
        gcc && \
    rm -rf /var/lib/apt/lists/*

# Add application metadata
LABEL org.opencontainers.image.title="MyApp API Server"
LABEL org.opencontainers.image.description="REST API for MyApp platform"
LABEL org.opencontainers.image.vendor="Example Corp"

# Document why we need specific ownership
COPY --chown=appuser:appuser . /app

Compose File: Application Topology Documentation

Compose files document the application architecture, service relationships, and deployment configuration. The structure itself shows how services interconnect, making it valuable architectural documentation.

# Application stack for MyApp platform
# Requires Docker Compose 3.8+

services:
  # Frontend web application
  frontend:
    image: myapp/frontend:latest
    ports:
      - "80:3000"
    depends_on:
      - api
    # Connects to backend API service

  # Backend REST API
  api:
    image: myapp/api:latest
    depends_on:
      database:
        condition: service_healthy
    # Requires healthy database before starting

  # PostgreSQL database
  database:
    image: postgres:14
    # Primary data store for application

Final Summary

Dockerfiles and Compose files operate at different abstraction levels within containerized application workflows. Dockerfiles focus on building individual container images with instructions for assembling filesystem layers, installing dependencies, and defining default container behavior. They are build-time specifications that produce immutable images.

Compose files orchestrate multiple containers into cohesive applications, defining how services connect, where they run, and how they're configured at runtime. They are deployment-time specifications that create and manage running container ecosystems.

Understanding these fundamental differences enables you to effectively use both tools in complementary ways: Dockerfiles to create consistent, portable images, and Compose files to deploy and manage multi-container applications with proper service relationships and runtime configurations.