Skip to main content

Getting Started with Terraform (Docker, Mac, IaC)


In this article, I will show you how to get started with Terraform.

Terraform is an Infrastructure-as-Code (IaC) tool. It lets you write and run code to automate the installation and configuration of your localhost or cloud environments.


These instructions were written and tested on a Mac.

Step 1. Install Terraform

You can find Terraform install instructions for Mac, Windows, and Linux here:

I followed the instructions for using brew to install it on my Mac.


If you are on a Mac and don't have brew installed, see the instructions here:

On a Mac, you can install Terraform like this:

brew tap hashicorp/tap
brew install hashicorp/tap/terraform

Check the version

To check the version, run this command:

terraform version 

If you get a warning that your version is out of date, ignore the instructions to download and do this instead:

brew upgrade terraform

Step 2. Run Docker

To run Docker on a Mac, run this command from a terminal window:

open -a Docker

Step 3. Create a project folder

To create a project folder, run these commands:

mkdir ~/projects/terraform/terraform-docker-101
cd ~/projects/terraform/terraform-docker-101

Step 4.  Create a file

Terraform works by reading *.tf files. Those files contain declarative statements defining the cloud infrastructure that you would like to build.  By default, it looks for a file called .

  • Create a file called in the root of your project:
  • Open in an IDE like Visual Studio Code (VS Code)
  • If VS Code prompts you about extensions to support the *.tf file, go ahead and install them

Step 5. Declare a provider

For this example, we're going to be working with Docker.  So we can specify the use of a Docker provider.

In Terraform you can think of a provider as a plugin, that provides extra third-party resource types and data sources. You can use them to define your infrastructure.

To use the recommended Docker provider, add this to the top of and save it:

terraform {
required_providers {
docker = {
source = "kreuzwerker/docker"
version = "2.23.1"

provider "docker" {
host = var.docker_endpoint

I've provided a link to the documentation for that provider in the reference section at the end of this article.

Adding variables

In the declaration above, the host is set to a variable name (var.docker_endpoint).  

To add that variable do the following:

  • Create a new file in the project called
  • Paste this into that new file and save it:
variable "docker_endpoint" {
default = "unix:///var/run/docker.sock"

When you run the plan, that variable will be used to set the docker host provider host value.  Don't worry if it doesn't look correct.  I will show you in the next step how to override the default value.

Step 6. Determine the docker context

The default docker endpoint value passed to the provider host may or may not be correct. Run this command to determine the correct one:

docker context ls

Look for the NAME that has a star (*) next to it.  That's the current context.  

Copy the current context DOCKER ENDPOINT from its column.

If you are using Docker Desktop it would be something like this (substituting my username for yours):


That's not very generic. You would need to do something like this, to work on other users' machines:

export TF_VAR_docker_endpoint=unix://$HOME/.docker/run/docker.sock

echo $TF_VAR_docker_endpoint

By starting the name with TF_VAR_ it will be seen by Terraform as an override for var.docker_endoint.

That is as long as you are working in the same terminal window.  If you wanted to make the setting permanent you could add it to your shell profile or write a bash script.  But that's beyond the scope of this article.  

Just beware that for this simple test, if you close the terminal window, or open a different one, the exported value (TF_VAR_docker_endpoint) may not be set.

Step 7. Pull an image with Terraform

To pull a Docker image using Terraform, append this declarative block to and save it:

# Create a docker image resource
# -> docker pull mitchallen/random-server:latest
resource "docker_image" "random" {
name = "mitchallen/random-server:latest"
keep_locally = false

The docker_image resource is provided by the docker provider declared in the previous step.

You can use any docker image that you would like.  For this example, I just used one of mine (you can find a link to the details in the references section).

The keep_locally flag tells Terraform whether or not to keep the image locally when done.  I set it to false to remove it and free up resources when it's not in use.  It simply means that if you want to use it again, somewhere behind the scenes it will need to be pulled down to your local system by docker again.

I put in the comment above the resource declaration the equivalent docker command-line call.

Step 8. Create a container from the image

To create a Docker container from the image, append this block to and save it:

# Create a docker container resource
# -> same as 'docker run --name random -p1220:3100 mitchallen/random-server:latest'
resource "docker_container" "random" {
image = docker_image.random.image_id
name = "random"
ports {
internal = 3100
external = 1220
  • Notice how the block references the previous block with:
  • image = docker_image.random.image_id

I put in the comment above the call the equivalent docker command.

  • The declaration shows how to use the docker_container resource (from the docker provider) to map the internal port (3100) to an external port (1220)

Save the file and move on to the next step.

Step 9. Terraform init

The first thing you should always do with a new Terraform project is run this command (once):

terraform init

The command does several things to initialize the current directory to work with Terraform.  For more information on the command, see the references section.

Step 10. Format the *.tf file

To format the file, do the following:

  • Save all files in your project
  • Run this command:
terraform fmt

It's an optional step that can keep your code clean and consistent.

Step 11. Run the plan

Once you've saved all the files, it's time to make a Terraform plan.  Think of it as a dry run.  Terraform parses your *.tf file(s) to determine how to build the infrastructure that you've defined.  Or it may fail with an error - like if your docker host is incorrect.

Run this command to see if a plan can be generated successfully.

terraform plan

If you get an error regarding docker: either docker isn't running, or you need to try a different docker endpoint passed to the provider.

You may see a warning like this:

Note: You didn't use the -out option to save this plan, so Terraform can't guarantee to take exactly these actions if you run "terraform apply" now.

You can get by for this demo without creating an out file.  But eventually, you should learn how to use them.

Step 12. Apply the plan

To actually make the changes, run this command:

terraform apply

When prompted, type Yes to agree to apply the plan.

Step 13. Check the results

To check the results you can do the following:

  • Verify that the image was downloaded for docker with this command:
 docker images | grep mitchallen
  • Verify that the container was created with this command:
docker ps
  • Verify that you see a container named random, which was created just a few minutes ago.
  • Verify that the server works, by running this command:
curl localhost:1220

Step 14. Generate a graph

Terraform has a graph command that can be used to create a visual representation of the plan. It does this by generating DOT code.

Run this command to see an example of the generated DOT code:

terraform graph -type=plan

Install dot

To turn the output of the graphic command into a picture, you need to install the special dot cli tool. For a Mac, you would do it like this:

brew install graphviz

For other operating systems, use this link to find install instructions:

Generate a plan picture

Once the dot utility is installed, you can pipe the instructions through it to turn the plan into a picture.

Run this command to:

  • Turn the plan into dot code
  • Pipe it through the dot utility and  
  • Open and view the result
terraform graph -type=plan | dot -Tpng > plan.png

open plan.png

Step 15. Cleanup

When you are done experimenting, Terraform makes it very easy to clean up.

You can remove the container and image by running this command:

terraform destory
  • Type yes when asked to confirm

Verify cleanup

Run this command to verify the container was removed:

docker ps

Run this command to verify the image was removed too:

docker image ls

Step 16. Add .gitignore

The makers of Terraform have posted an example .gitignore file, which you can copy from here:

To use it:

  • Create a new file called .gitignore in the root of your project
  • Copy the contents from the file in the link to your .gitignore file and save it

Example repo

You can find the example repo here:


In this article, you learned how to:

  • Install Terraform on a Mac
  • Define an Infrastructure as Code (IaC)
  • Use Terraform to manage docker instances
  • Initiate, plan, and apply a Terraform project
  • Pass and use environment variables in Terraform
  • Create a visual representation of a Terraform plan
  • Clean up using a simple command


  • - [1]
  • - [2]
  • -[3]
  • - [4]
  • - [5]
  • ../providers/kreuzwerker/docker/latest/docs/resources/image - [6]
  • - [7]
  • ../providers/kreuzwerker/docker/latest/docs/resources/container - [8]
  • - [9]
  • - [10]
  • - [11]
  • - [12]
  • - [13]
  • - [14]
  • - [[15](see:\]
  • - [16] - an alternate way to visualize a plan