Skip to content
Tutorials Center
My learning

Topics

Lesson 3 of 36 ยท Getting Started

Your First Packer Build with the Docker Builder

Write a Packer template for the Docker builder, run init, fmt, validate and build, tag the result with a post-processor, and understand what happens at each step.

The Docker builder is the best way to learn Packer: it needs no cloud account, builds in seconds and leaves a normal Docker image on your machine. You will write a small template, initialize it, validate it and build it. Along the way you will see every moving part you will later use with AWS, Azure or VMware.

Packer and Docker are not available on this site, so the template and commands are read-only. The output shown in this lesson is described in words and never pasted as if it came from a real run; your own output will contain different IDs, timings and versions. Python stand-ins model the ideas.

Before you start

You need Packer installed (Installing Packer) and Docker Engine or Docker Desktop running. Check both:

Terminal
packer version
docker version

Create a folder and a file named docker-ubuntu.pkr.hcl. The .pkr.hcl ending tells Packer and your editor that this is an HCL2 template.

The template

HCL
packer {
  required_plugins {
    docker = {
      version = ">= 1.0.0"
      source  = "github.com/hashicorp/docker"
    }
  }
}

source "docker" "ubuntu" {
  image  = "ubuntu:24.04"
  commit = true
}

build {
  name    = "learn-packer"
  sources = ["source.docker.ubuntu"]

  provisioner "shell" {
    inline = [
      "apt-get update",
      "apt-get install -y --no-install-recommends curl ca-certificates",
      "echo 'Built with Packer' > /etc/built-by",
    ]
  }

  post-processor "docker-tag" {
    repository = "learn-packer"
    tags       = ["ubuntu-curl", "latest"]
  }
}

Read it block by block:

  1. packer { required_plugins { ... } } declares which plugins the template needs. packer init downloads the docker plugin from the given source.
  2. source "docker" "ubuntu" defines a reusable source: use the Docker builder (type docker), name it ubuntu, start a container from ubuntu:24.04. commit = true tells the builder to save the container as an image at the end. (Alternatively export_path writes a tarball, or discard = true throws the result away, useful for tests.)
  3. build { ... } lists what to do with sources. sources refers to the source as source.<type>.<name>.
  4. provisioner "shell" runs commands inside the container, in order.
  5. post-processor "docker-tag" gives the committed image a repository name and tags.

Step 1: initialize

Terminal
packer init .

init reads required_plugins, downloads matching plugin binaries into Packer's plugin folder and records nothing in your project. Run it once per machine (and again after changing plugin requirements). If a plugin is missing, build stops with an error that tells you to run packer init.

Step 2: format

Terminal
packer fmt .

fmt rewrites files in the standard style: two-space indentation and aligned equals signs. Use packer fmt -check . in CI to fail when someone forgot to format.

Step 3: validate

Terminal
packer validate .

validate checks syntax, argument names, types and references without starting any machine. It catches typos such as provisoner or a missing required argument. It prints a success message when the template is valid.

Step 4: build

Terminal
packer build .

The sequence you will see, described in words:

  1. Packer announces the build, using the name learn-packer.docker.ubuntu (build name plus source type and name).
  2. It pulls ubuntu:24.04 if it is not already local and starts a container from it.
  3. It uploads and runs each shell command through the container, streaming the output with a colored prefix.
  4. After the last provisioner it commits the container as an image.
  5. Post-processors run: the image gets the learn-packer:ubuntu-curl and learn-packer:latest tags.
  6. The container is removed and Packer prints a summary of artifacts.

Then check the result with Docker itself:

Terminal
docker images learn-packer
docker run --rm learn-packer:latest cat /etc/built-by
docker run --rm learn-packer:latest curl --version

The second command prints Built with Packer, proving that the file written at build time is in the image.

sequenceDiagram
  participant You
  participant Packer
  participant Docker
  You->>Packer: packer build .
  Packer->>Docker: start container from ubuntu:24.04
  Packer->>Docker: run provisioner commands
  Packer->>Docker: commit container as image
  Packer->>Docker: tag image (post-processor)
  Packer->>Docker: remove container
  Packer-->>You: artifact: learn-packer:latest

What the Docker builder does on your behalf.

A stand-in for the build loop

The Python program below is not Packer; it imitates how the Docker builder turns provisioner steps into an image with tags. It keeps a list of "layers" so you can see why a failing step stops everything and why the committed result contains all earlier changes.

Python Stand-in: container, provisioners, commit, tag

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Common first-run problems

  • "Unknown plugin" or "missing plugins": you skipped packer init.
  • Cannot connect to the Docker daemon: Docker is not running, or your user may not use the socket.
  • apt-get asks questions or finds nothing: always run apt-get update first in a fresh container, and use -y. Set DEBIAN_FRONTEND=noninteractive for packages that prompt (see Shell and file provisioners).
  • Command not found inside the container: minimal base images lack tools such as curl, sudo or python3. Install what your provisioners need first.
  • Image not found afterwards: you forgot commit = true, export_path or a post-processor path; with none of them Packer errors because the build would produce no artifact.

Cleaning up

Terminal
docker rmi learn-packer:latest learn-packer:ubuntu-curl

Packer leaves no state to clean. The image is yours to keep or delete.

Where this goes next

The same four commands (init, fmt, validate, build) work for every builder. Only the source block changes. In later lessons you will replace docker with amazon-ebs, add variables, pull in several sources at once and run builds in CI. The commands are examined in Packer CLI commands, and the anatomy of the file in Template anatomy.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Which command downloads the plugins listed in required_plugins?

    packer init installs the plugin binaries. fmt formats, validate checks, build runs the build.
  2. 2. What does commit = true do in the docker source?

    With commit enabled the Docker builder commits the container as an image after provisioning.
  3. 3. How does a build block refer to a source named ubuntu of type docker?

    Sources are referenced as source.<type>.<name>.
  4. 4. A provisioner command fails in the middle of the list. What happens by default?

    A non-zero exit status aborts the build and cleanup runs, so no half-configured image is saved.
  5. 5. What does packer validate . NOT do?

    Validation is static: it never creates a machine.

Summary

  • A minimal template has a packer block (plugins), a source and a build with provisioners and optional post-processors.
  • The workflow is packer init, packer fmt, packer validate, packer build.
  • The Docker builder starts a container, runs provisioners, commits an image and a post-processor tags it.
  • A failing provisioner stops the build and no image is saved.
  • Plugins must be initialized before the first build.

Next: Packer CLI commands