How to Create and Manage Docker Images: A Step-by-Step Guide

Docker images allow you to package an application and all its dependencies into a single file that runs anywhere in less than 60 seconds. You create these images using a text file called a Dockerfile, which acts as a blueprint for your software environment. By managing your own images, you ensure your app works exactly the same on your laptop, a teammate’s computer, or a cloud server.

Why should you use Docker images for development?

Docker images solve the "it works on my machine" problem by creating a consistent environment. Instead of installing Python, Node.js, or databases directly on your computer, you wrap them inside a container (a lightweight, isolated process that runs your code).

This isolation prevents different projects from conflicting with each other. For example, one project can use Python 3.15 while another uses an older version without any issues. We've found that this setup saves hours of troubleshooting when onboarding new developers to a project.

Since images are portable, you can share them via a registry (a storage service for Docker images). This means anyone with Docker installed can run your exact setup with a single command.

What is a Docker image vs. a container?

A Docker image is a read-only template that contains the instructions for creating a container. Think of an image as a cake recipe and the container as the actual cake you bake.

The image includes everything your app needs: the operating system, code, libraries, and environment variables. Because images are read-only, they never change once they are built.

A container is a running instance of that image. You can start, stop, move, or delete a container without affecting the original image.

What do you need to get started?

Before building your first image, you need to set up your environment. Most modern AI and web tools require specific versions of runtimes to function correctly.

• Docker Desktop: Download and install the latest version for your operating system.
• A Code Editor: VS Code is highly recommended for beginners.
• Terminal Access: You will use the command line to run Docker commands.
• Python 3.15 or Node.js 26: These are the current stable versions you might want to package inside your images.

How do you write your first Dockerfile?

A Dockerfile is a simple text document containing all the commands a user could call on the command line to assemble an image. You start by choosing a "base image," which is a pre-made environment provided by others.

For AI developers, you might use an NVIDIA-docker base image to access GPU (Graphics Processing Unit) power. If you are building a standard app, you might start with a slim version of Python or Node.js.

Create a new file named Dockerfile (no file extension) in your project folder. Add the following lines to it:

# Step 1: Use an official Python 3.15 base image
FROM python:3.15-slim

# Step 2: Set the working directory inside the container
WORKDIR /app

# Step 3: Copy your requirements file into the container
COPY requirements.txt .

# Step 4: Install dependencies
RUN pip install --no-cache-dir -r requirements.txt

# Step 5: Copy the rest of your application code
COPY . .

# Step 6: Define the command to run your app
CMD ["python", "app.py"]

Each line in this file creates a "layer" in your image. Layers are cached, so if you only change your code but not your dependencies, Docker will build the image much faster next time.

How do you build and run your image?

Once your Dockerfile is ready, you need to turn it into an actual image. You do this using the docker build command in your terminal.

Step 1: Build the image Open your terminal in the folder where your Dockerfile is located. Type the following command:

docker build -t my-first-app:1.0 .

• docker build: The command to create an image.
• -t my-first-app:1.0: The "tag" or name you are giving your image.
• .: Tells Docker to look for the Dockerfile in the current folder.

Step 2: Verify the image exists Run this command to see a list of all images on your machine:

docker images

You should see my-first-app listed with the tag 1.0.

Step 3: Run the container Now, turn that image into a running process:

docker run -p 8080:8080 my-first-app:1.0

• -p 8080:8080: Maps your computer's port 8080 to the container's port 8080.
• my-first-app:1.0: The name of the image you want to run.

How do you optimize images for AI applications?

AI applications often require heavy libraries like PyTorch or TensorFlow. If you use a standard base image, your final file size might be several gigabytes, which is slow to move and deploy.

To fix this, use specialized AI base images. For example, pytorch/pytorch:latest comes pre-configured with the necessary environment for machine learning.

We suggest using "multi-stage builds" to keep your final image small. This involves using one large image to compile your code and then copying only the finished product into a much smaller, "slim" image for the final version.

What are common Docker mistakes to avoid?

It is normal to run into errors when you first start. Most mistakes happen because of small syntax errors or missing files.

• Forgetting the .dockerignore file: Without this file, Docker copies everything in your folder—including large, unnecessary files like .git or node_modules. Create a .dockerignore file to list things Docker should ignore.
• Hardcoding secrets: Never put passwords or API (Application Programming Interface) keys directly in your Dockerfile. Use environment variables instead so your secrets stay private.
• Using "latest" tags in production: While convenient, the latest tag changes over time. Always use specific version numbers like python:3.15 to ensure your app doesn't break when a new version is released.

How do you manage and delete old images?

As you build new versions of your app, old images will start taking up space on your hard drive. Managing these is a key part of keeping your development environment fast.

To remove a specific image you no longer need, use:

docker rmi my-first-app:1.0

If you want to clean up all unused images, containers, and networks at once, run:

docker system prune

Be careful with this command, as it will delete everything that isn't currently being used by a running container. It is a great way to reclaim several gigabytes of disk space.

Next Steps

Now that you can build and run images, try creating a Dockerfile for a project you've already written. Experiment with changing the base image to see how it affects the final size of your build.

Once you feel comfortable, look into Docker Compose, which allows you to run multiple containers (like an app and a database) at the same time.

For more detailed guides, visit the official Docker documentation.