Docker

Docker is a platform for packaging and running applications together with the environments they require in isolated units called containers.

Because runtime environments such as the operating system, Python version, and libraries can be defined as code, projects can be run in a consistent environment across different computers.

This tutorial does not cover everything about Docker. Instead, it focuses on the features needed to build and run the BlueBase project.

For a broader understanding of Docker, refer to the following resources:

Key Features

  • Environment isolation: Keeps Python and library environments independent between projects.

  • Reproducible environments: Creates development and runtime environments using the same procedure defined in a Dockerfile.

  • Portability: Runs the same image as a container on any operating system that supports Docker.

  • Deployment automation: Repeatedly uses the same runtime environment for build, test, and deployment processes.

Core Concepts

  • image: A read-only template containing the files and configuration required to run an application.

  • container: A runnable instance created from an image. Multiple containers can be created from a single image.

  • Dockerfile: A file containing, in order, the instructions used to build an image.

  • registry: A remote repository for storing and sharing images. Docker Hub is a common example.

  • volume: Storage managed by Docker for preserving data even after a container is deleted.

  • bind mount: A mechanism that directly maps a file or directory on the host to a path inside a container.

In short, an image defines a program and its runtime environment, while a container is a running instance of that image, similar to a process.

Installation and Verification

Install from Get Docker for your operating system.

After installation, verify that Docker is working correctly with the following commands:

# Check the version
docker --version

# Run a container
docker run --rm hello-world

The second command runs a container from the hello-world image.

The docker run command downloads the required image from a registry if it is not available locally, then creates and runs a new container. The --rm option automatically removes the container after it exits.

Usage Examples

1. Write a Dockerfile

Create a Dockerfile in the project directory:

FROM python:3.13-slim

# Copy the uv executables
COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/

# Copy the project files
WORKDIR /workdir
COPY . .

# Install package dependencies
RUN uv sync --frozen --no-dev

ENTRYPOINT ["uv", "run", "--no-sync"]

The instructions have the following meanings:

  • FROM: Specifies the base image.

  • COPY: Copies files from the host into the image.

  • WORKDIR: Specifies the default directory for subsequent instructions.

  • RUN: Executes a command as part of building the image.

  • ENTRYPOINT: Specifies the default command to run when a container starts.

2. Build an image

Build an image named bluebase using the Dockerfile in the current project:

docker build -t bluebase .

Here, -t bluebase assigns the name bluebase to the generated image. The final . specifies the current directory as the build context.

You can inspect the generated image with:

docker image ls

3. Run a container

Run a new container from the built image:

docker run --rm bluebase bluebase --help

This runs the additional command bluebase --help after the ENTRYPOINT defined in the bluebase image.

4. Mount a local directory

Use a bind mount to connect a data directory or other local files to a container.

Example: mount ./data/ in the current directory to /data/ inside the container:

docker run --rm -i -t -v ./data:/data bluebase bluebase /data/test.db

The host ./data/ directory and the container /data/ directory refer to the same files. Therefore, the data remains in the host ./data/ directory even after the container exits.

The options used here have the following meanings and are commonly used for interactive execution:

  • -i: Keeps standard input open.

  • -t: Allocates an interactive terminal.

5. Remove an image

Remove an image that is no longer needed with:

docker image rm bluebase

If any containers using the image still exist, stop and remove them first.

List all containers:

docker container ls -a

Example: if the container is named bluebase-container:

docker container stop bluebase-container
docker container rm bluebase-container

6. Summary

# Verify Docker
docker run --rm hello-world

# Build the bluebase image
docker build -t bluebase .

# Run a container from the bluebase image
docker run --rm bluebase bluebase --help

# Run interactively with a mounted local data directory
docker run --rm -i -t -v ./data:/data bluebase bluebase /data/test.db

# List images
docker image ls

# Remove the image
docker image rm bluebase