Docker fundamentals

Learn the basics of Docker, including containers, images, and how to run your first containerized application.

This tutorial introduces you to Docker containerization fundamentals and walks you through installing Docker Desktop and running your first containers. You’ll learn the core concepts that make containers essential for modern application deployment and cloud computing, with specific focus on how they enable Runpod’s BYOC (bring your own container) workflows.

Containers are isolated environments that package applications with all their dependencies, making them portable and consistent across different computing environments. This approach is fundamental to Runpod’s infrastructure, where containers enable fast deployment across Pods, Serverless Workers, and Instant Clusters. Understanding containers is essential for leveraging Runpod’s BYOC capabilities for both persistent infrastructure and auto-scaling workloads.

What you’ll learn

In this tutorial, you’ll learn how to:

• Understand what containers and Docker images are and why they’re essential for Runpod deployments.
• Install Docker Desktop with all necessary tools for local development.
• Run your first container commands and explore container basics.
• Use Docker Hub to access pre-built images and understand registry workflows.
• Understand how containers enable Runpod’s BYOC workflows for both Pods and Serverless.
• Connect containerization concepts to Runpod’s deployment patterns and optimization strategies.

Requirements

Before starting this tutorial, you’ll need:

• A computer running Windows, macOS, or Linux.
• Administrator/root access to install Docker Desktop.
• Basic familiarity with command-line interfaces.
• An internet connection to download Docker and container images.

Step 1: Understand containers and images

Before diving into hands-on work, let’s establish the fundamental concepts you’ll be working with.

What are containers?

A container is an isolated environment for your code that includes everything needed to run an application: the code itself, runtime libraries, system tools, and settings. Containers have no knowledge of your host operating system or files - they run in their own isolated space.

This isolation makes containers perfect for Runpod’s BYOC (bring your own container) approach, where your custom environments run reliably across different GPU hardware and compute types.

Key benefits of containers for Runpod deployments include:

• Consistency: Applications run identically on your local machine and Runpod infrastructure.
• Portability: Move workloads seamlessly between Pods, Serverless Workers, and Instant Clusters.
• Efficiency: Fast startup times essential for Serverless cold starts and Pod initialization.
• Isolation: GPU workloads run independently without interference from other users.
• Reproducibility: Exact environment replication for AI/ML model training and inference.

What are Docker images?

Docker images are read-only templates used to create containers. Think of an image as a blueprint that contains:

• A base operating system (like Ubuntu or Alpine Linux optimized for GPU workloads).
• Your application code and dependencies (like Python packages for AI/ML models).
• Configuration files and environment settings.
• Instructions for how to run the application.

Images are built using a process called “Docker build” which follows instructions in a text file called a Dockerfile. For Runpod deployments, images often contain specialized components like handler functions for Serverless Workers or JupyterLab environments for Pods.

What is Docker Hub?

Docker Hub is a cloud-based registry where Docker images are stored and shared. It contains millions of pre-built images for popular applications, programming languages, and services. You can pull images from Docker Hub to run containers locally or push your own custom images to share with others.

Runpod also provides the Runpod Hub, a curated registry of GPU-optimized container templates designed specifically for AI/ML workloads. These templates include pre-configured environments for popular frameworks like PyTorch, TensorFlow, and specialized inference engines, making it easier to deploy on Runpod’s infrastructure.

Step 2: Install Docker Desktop

Docker Desktop provides everything you need to work with containers, including the Docker engine, command-line tools, and a graphical interface.

Download and install Docker Desktop

1. Visit the official Docker website and download Docker Desktop for your operating system.

2. Run the installer and follow the setup wizard:

   • On Windows: Enable WSL 2 integration if prompted.
   • On macOS: Run the installer and accept the default options to add Docker to your Applications folder.
   • On Linux: Follow the distribution-specific installation instructions.

3. Start Docker Desktop after installation completes.

4. Complete the initial setup process, including creating a Docker Hub account if you don’t have one.

Verify your installation

Open a terminal or command prompt and run the following command to verify Docker is installed correctly:

docker version

You should see output similar to this:

Client:
 Version:           28.0.4
 API version:       1.48
 Go version:        go1.23.7
 Git commit:        b8034c0
 Built:             Tue Mar 25 15:06:09 2025
 OS/Arch:           darwin/arm64
 Context:           desktop-linux

If you see the message:

Cannot connect to the Docker daemon at unix:///Users/moking/.docker/run/docker.sock. Is the docker daemon running?

That means you need to start the Docker Desktop application. Start it and try running the command again.

You should see output similar to this:

Server: Docker Desktop 4.40.0 (187762)
 Engine:
  Version:          28.0.4
  API version:      1.48 (minimum version 1.24)
  Go version:       go1.23.7
  Git commit:       6430e49
  Built:            Tue Mar 25 15:07:18 2025
  OS/Arch:          linux/arm64
  Experimental:     false
 containerd:
  Version:          1.7.26
  GitCommit:        753481ec61c7c8955a23d6ff7bc8e4daed455734
 runc:
  Version:          1.2.5
  GitCommit:        v1.2.5-0-g59923ef
 docker-init:
  Version:          0.19.0
  GitCommit:        de40ad0

If you see version information for both the client and server, Docker is installed and running correctly.

If you need help with any Docker command, use the --help flag to see documentation:

docker --help
docker run --help

Step 3: Run your first container

Now that Docker is installed, let’s run your first container using a simple, lightweight image.

Run a basic container

Execute this command in your local terminal to run your first container:

docker run busybox echo "Hello from my first container!"

This command does several things:

1. Downloads the busybox image (if not already present locally).
2. Creates a new container from the busybox image.
3. Runs the echo command inside the container.
4. Displays the output and exits.

You should see output like:

Hello from my first container!

Understanding what happened

Let’s break down what occurred when you ran that command:

• docker run: The command to create and start a new container.
• busybox: A lightweight Linux image with basic utilities.
• echo "Hello from my first container!": The command executed inside the container.

The busybox image is popular for learning because it’s small (about 1MB) but includes essential Linux command-line tools.

Run an interactive container

Try running a container interactively to explore its environment:

docker run -it busybox sh

This opens a shell inside the container where you can run commands:

• -i: Keep the container’s standard input open.
• -t: Allocate a pseudo-terminal for interactive use.
• sh: Start a shell session.

Inside the container, try these commands:

# List files in the root directory
ls

# Check the current date and time
date

# Exit the container
exit

When you type exit, the container stops and you return to your host system.

Step 4: Explore the container lifecycle

Understanding how containers start, run, and stop is crucial for effective container management.

Run a container with a specific task

Let’s run a container that performs a specific task and then exits:

docker run busybox sh -c 'echo "The current time is: $(date)"'

This creates a container, runs the command, displays the output, and automatically removes the container when finished.

List running containers

To see what containers are currently running:

docker ps

Since our previous containers have already finished and exited, you’ll likely see an empty list or just column headers.

List all containers (including stopped ones)

To see all containers, including those that have stopped:

docker ps -a

This shows all containers with their status, creation time, and other details.

Clean up stopped containers

Remove stopped containers to keep your system clean:

docker container prune

Confirm when prompted to remove all stopped containers.

Step 5: Working with Docker images

Learn how to manage the images that serve as templates for your containers.

List downloaded images

See what images you have locally:

docker images

You should see the busybox image you downloaded earlier.

Pull a specific image

Download an image without running it immediately:

docker pull hello-world

This downloads the official “hello-world” image, which is designed specifically for testing Docker installations.

Run the hello-world container

docker run hello-world

This container displays information about how Docker works and then exits. It’s a great way to verify your Docker installation is working correctly.

Remove an image

If you want to remove an image you no longer need:

docker rmi hello-world

If the command above fails, you can force removal of the image with the -f flag:

docker rmi -f hello-world

Step 6: Understand Docker’s architecture

Now that you’ve run a few containers, let’s understand how Docker’s components work together.

Key components

• Docker Engine: The core runtime that manages containers and images.
• Docker CLI: The command-line interface you’ve been using.
• Docker Desktop: The graphical application that includes the engine and CLI.
• Docker Hub: The cloud registry for sharing images.

Container lifecycle

1. Image creation: Images are built from Dockerfiles or pulled from registries.
2. Container creation: Containers are created from images but not yet running.
3. Container execution: Containers run the specified command or application.
4. Container termination: Containers stop when their main process exits.
5. Container removal: Stopped containers can be deleted to free up space.

Why containers matter for cloud computing

Containers provide several advantages for cloud platforms like Runpod:

• Fast startup times: Critical for Serverless workers that need to minimize cold start latency.
• Resource efficiency: Optimal GPU utilization across multiple concurrent workloads.
• Scalability: Automatic scaling from zero to hundreds of instances based on demand.
• Consistency: AI/ML models behave identically in development and production environments.

Runpod’s containerization approach

Runpod’s BYOC (bring your own container) approach enables three deployment patterns:

• Pods: Persistent GPU instances with custom container environments for development and training.
• Serverless workers: Auto-scaling container functions for AI inference and batch processing.
• Instant Clusters: Distributed container deployments for multi-GPU training workloads.

Each approach leverages containers differently, but shares the same fundamental principles you’ll learn in this tutorial series.

Next steps

Now that you understand container basics, you’re ready to explore more advanced topics:

• Learn how to build custom Docker images with Dockerfiles, including Runpod-specific patterns like handler functions for Serverless.
• Discover data persistence patterns for managing data across container lifecycles, including network volume integration.
• Reference Docker commands optimized for Runpod deployment workflows.

Next steps with Runpod

Once you’ve mastered container fundamentals, explore how to deploy your containers on Runpod:

• Deploy containers on Pods for persistent GPU workloads and interactive development.
• Create Serverless workers for auto-scaling AI inference and batch processing.
• Browse Runpod Hub for pre-optimized container templates and models.