Container Lifecycle Management

Running a Docker image as a container is a fundamental operation. A container is a live, runnable instance created from an image. Managing the lifecycle of these containers—including running, stopping, inspecting, and removing them—is fundamental to using Docker effectively, especially for machine learning tasks like executing training scripts or deploying inference endpoints.

Creating and Running Containers: docker run

The primary command for creating and starting a new container is docker run. At its simplest, you provide the image name:

docker run <image_name>

However, for practical ML workflows, you'll typically use several options (flags) to control the container's behavior:

• Running in the Background (-d or --detach): Most ML training jobs or inference servers need to run independently of your terminal session. The -d flag starts the container in detached mode, printing the container ID and returning control to your terminal.

  # Example: Run a container based on a custom 'my-ml-app' image in the background
  docker run -d my-ml-app
  

• Interactive Sessions (-it): Sometimes you need to interact directly with the container's shell, perhaps to debug a script, explore data, or run commands manually. Combining -i (interactive) and -t (pseudo-TTY) allows this. You typically specify a shell like /bin/bash as the command to run.

  # Example: Start an interactive bash shell in a python container
  docker run -it python:3.9-slim /bin/bash
  

  Inside the container, you'll get a prompt (e.g., root@<container_id>:/#) where you can execute commands. Type exit to leave and stop the container.

• Automatic Removal (--rm): For short-lived tasks like running a training script once, it's convenient to have the container automatically removed when it finishes. The --rm flag handles this cleanup.

  # Example: Run a training script and remove the container afterwards
  docker run --rm my-training-image python train.py --epochs 10
  

• Assigning Names (--name): Docker assigns random names to containers (like pensive_mcnulty). Assigning a specific name makes containers easier to identify and manage.

  # Example: Run an inference server container with a specific name
  docker run -d --name inference_api my-inference-image
  

• Port Mapping (-p): To access an application running inside a container (like a web API for inference) from your host machine, you need to map a port on the host to a port inside the container. (Format: host_port:container_port)

  # Example: Map port 8080 on the host to port 80 in the container
  docker run -d -p 8080:80 --name web_server nginx
  

• Volumes and Environment Variables (-v, -e): You'll frequently need to mount directories from your host into the container (using -v for data or code) and pass configuration parameters (using -e for environment variables like hyperparameters or API keys). These are covered in more detail in Chapters 2 and 3.

Listing Containers: docker ps

To see which containers are currently running, use the docker ps command:

docker ps

This outputs a table showing the container ID, image used, command being run, creation time, status, exposed ports, and assigned name.

To see all containers, including those that have stopped (e.g., a completed training job or a crashed process), add the -a flag:

docker ps -a

This is particularly useful for checking the exit status of completed tasks or finding containers you need to remove.

Stopping and Starting Containers: docker stop and docker start

You can stop a running container using its name or ID with the docker stop command. This sends a signal (SIGTERM) to the main process inside the container, allowing it to shut down gracefully (within a default timeout, after which it's forcibly killed with SIGKILL).

# Stop the container named 'inference_api'
docker stop inference_api

A stopped container still exists and can be restarted with its previous state preserved using docker start:

# Restart the 'inference_api' container
docker start inference_api

While docker start is less common for ephemeral training tasks (which are often run with --rm), it can be useful for restarting development servers or long-running services managed manually.

Removing Containers: docker rm

Stopped containers consume disk space. Once you're finished with a container (e.g., after a training run or when debugging is complete), you should remove it using docker rm followed by the container name or ID. You can only remove stopped containers unless you use the force flag (-f).

# Remove the stopped container named 'old_experiment'
docker rm old_experiment

# Force remove a running container (use with caution)
# docker rm -f some_running_container

To remove multiple stopped containers at once, you can list their IDs or names:

docker rm container_id1 container_name2

A convenient command to remove all stopped containers is:

docker container prune

Docker will ask for confirmation before proceeding. This is helpful for routine cleanup.

Inspecting Logs: docker logs

Understanding what's happening inside a container, especially one running in detached mode, relies heavily on inspecting its logs (the standard output and standard error streams of its main process). The docker logs command retrieves these logs.

# Show logs for the 'inference_api' container
docker logs inference_api

This is essential for:

• Monitoring the progress of ML training jobs (e.g., epoch numbers, loss values).
• Debugging errors or crashes in scripts running inside the container.
• Viewing the output of inference servers (e.g., request logs).

To follow the logs in real-time (similar to tail -f on Linux), use the -f flag:

# Follow the logs of the 'training_job_1' container
docker logs -f training_job_1

Press Ctrl+C to stop following.

Container Lifecycle Diagram

The following diagram illustrates the typical states of a container and the commands used to transition between them:

Basic Docker container states and the commands triggering transitions between them.

Mastering these lifecycle commands (run, ps, stop, start, logs, rm) is necessary for effectively using Docker in your machine learning projects. They allow you to execute tasks, monitor progress, manage resources, and debug issues within your containerized environments. As we proceed, these commands will become second nature as you build, run, and manage your own ML containers.