Back to Engineering Notes
DockerEngineering Note

5. Pull Docker Image

Pull the busybox:musl Docker image on App Server 1 and create a new tag for the same image:

# Day 5: Pull and Re-Tag a Docker Image

🎯 Objective

Pull the busybox:musl Docker image on App Server 1 and create a new tag for the same image:

plain text
busybox:media

This task covers two fundamental Docker image operations:

Pulling an image from a container registry
Creating another tag for an existing local image

🧠 Concept

Docker Image

A Docker image is a read-only template used to create containers.

Images are commonly identified using:

plain text
<repository>:<tag>

For example:

plain text
busybox:musl

Here:

plain text
Repository → busybox
Tag        → musl

The tag usually identifies a particular version or variant of the image.

📥 Docker Pull

The docker pull command downloads an image from a container registry.

Syntax:

bash
docker pull <image>:<tag>

For this task:

bash
docker pull busybox:musl

Docker will download the musl variant of the BusyBox image from the configured registry.

🏷️ Docker Tag

The docker tag command creates another tag that references an existing Docker image.

Syntax:

bash
docker tag <source-image>:<tag> <target-image>:<tag>

For this task:

bash
docker tag busybox:musl busybox:media

This does not create a completely new copy of the image.

Instead, both tags reference the same underlying local image:

plain text
Docker Image
                  │
          ┌───────┴───────┐
          ▼               ▼
   busybox:musl      busybox:media

🚀 Step 1: Connect to App Server 1

SSH into App Server 1:

bash
ssh <username>@<app-server-1>

Make sure Docker is installed and running:

bash
sudo systemctl status docker

📥 Step 2: Pull the BusyBox Image

Pull the required image:

bash
docker pull busybox:musl

If Docker requires root privileges:

bash
sudo docker pull busybox:musl

After completion, Docker should report that the image was downloaded successfully or is already up to date.

🔍 Step 3: Verify the Image

List the local Docker images:

bash
docker images

Or:

bash
docker image ls

You should see something similar to:

plain text
REPOSITORY   TAG       IMAGE ID       CREATED       SIZE
busybox      musl      abc123def456   ...           ...

You can filter specifically for BusyBox:

bash
docker image ls busybox

🏷️ Step 4: Create the New Tag

Create the media tag from busybox:musl:

bash
docker tag busybox:musl busybox:media

The structure is:

plain text
docker tag
    │
    ├── Source      → busybox:musl
    │
    └── New Tag     → busybox:media

🔍 Step 5: Verify the New Tag

Check the images again:

bash
docker image ls busybox

You should now see both tags:

plain text
REPOSITORY   TAG       IMAGE ID       CREATED       SIZE
busybox      musl      abc123def456   ...           ...
busybox      media     abc123def456   ...           ...

Notice that both entries have the same IMAGE ID.

This confirms that:

plain text
busybox:musl
      │
      ├── IMAGE ID: abc123def456
      │
busybox:media
      │
      └── IMAGE ID: abc123def456

Both tags point to the same underlying Docker image.

⚙️ Complete Commands

The entire task can be completed with:

bash
docker pull busybox:musl

docker tag busybox:musl busybox:media

docker image ls busybox

If sudo is required:

bash
sudo docker pull busybox:musl

sudo docker tag busybox:musl busybox:media

sudo docker image ls busybox

🧠 Image vs Tag

It is important to understand that a tag is not the image itself.

Consider:

plain text
busybox:musl
busybox:media

After tagging:

plain text
busybox:musl ─────┐
                  ├──→ Same Docker Image
busybox:media ────┘

Creating a new tag is therefore very lightweight because Docker does not duplicate all of the image layers.

🗑️ Optional: Remove a Tag

If the new tag is no longer needed:

bash
docker rmi busybox:media

This removes the media reference.

If busybox:musl still references the image, the underlying image data remains available.

⚠️ Important Notes

docker pull downloads an image from a registry.
Docker uses the format <repository>:<tag> to identify tagged images.
docker tag creates another reference to an existing image.
Re-tagging does not normally duplicate the image layers.
Both busybox:musl and busybox:media should have the same image ID after tagging.
Creating a local tag does not automatically push that tag to Docker Hub or another registry.
Use docker image ls to verify local images and tags.

🧪 Validation Checklist

[ ] Connected to App Server 1
[ ] Docker service running
[ ] busybox:musl pulled successfully
[ ] busybox:musl visible in local images
[ ] busybox:media tag created
[ ] busybox:media visible in local images
[ ] Both tags reference the same image ID

📌 Summary

The task requires two main Docker commands:

1. Pull the image

bash
docker pull busybox:musl

2. Create the new tag

bash
docker tag busybox:musl busybox:media

Then verify:

bash
docker image ls busybox

The final state should be:

plain text
Docker Registry
      │
      │ docker pull
      ▼
busybox:musl
      │
      │ docker tag
      ▼
┌─────────────────────────┐
│   Local Docker Image    │
│                         │
│  busybox:musl           │
│  busybox:media          │
│         │               │
│         └─ Same Image   │
└─────────────────────────┘

The key takeaway is:

> docker pull retrieves an image, while docker tag creates another name/reference for that same image.