docker

dev_tool.config.docker

log = logging.getLogger(__name__) module-attribute

DockerConfig

A class for managing Docker configuration settings.

This class provides methods for creating default Docker configurations based on environment variables and user settings.

The constructor for the DockerConfig class.

Source code in dev_tool/config/docker.py

def __init__(self) -> None:
    """The constructor for the DockerConfig class."""

    self._notification: NotificationProtocol | None = None
    self._resource_path_getter: Callable[[str], Path] | None = None

create_default_docker_config

A method that creates a default Docker configuration dictionary.

This method combines user-provided configuration with environment variables to create a complete Docker container configuration.

Parameters:

• container_name (str) –

  The name to use for the Docker container.

• docker_config (dict) –

  The user-provided Docker configuration dictionary.

• host_port (int) –

  The host port to publish the database on.

Returns:

• dict –

  A complete Docker configuration dictionary.

Source code in dev_tool/config/docker.py

def create_default_docker_config(self, container_name: str, docker_config: dict, host_port: int) -> dict:
    """
    A method that creates a default Docker configuration dictionary.

    This method combines user-provided configuration with environment variables
    to create a complete Docker container configuration.

    :param container_name: The name to use for the Docker container.
    :param docker_config: The user-provided Docker configuration dictionary.
    :param host_port: The host port to publish the database on.
    :return: A complete Docker configuration dictionary.
    """

    version = docker_config.get('postgres-version', DockerDefault.POSTGRES_VERSION)
    container_port = DockerDefault.CONTAINER_DB_PORT
    postgres_user = os.getenv('DATABASE_USER', DevelopmentDefault.DATABASE_USER)
    postgres_password = os.getenv('DATABASE_PASSWORD', DevelopmentDefault.DATABASE_PASSWORD)
    shm_size = docker_config.get('container-size', DockerDefault.CONTAINER_SIZE)

    return {
        'container_name': container_name,
        'container': f'postgres:{version}',
        'host_port': int(host_port),
        'container_port': int(container_port),
        'environment': {
            'POSTGRES_USER': postgres_user,
            'POSTGRES_PASSWORD': postgres_password,
        },
        'shm_size': shm_size,
        **{
            k: v
            for k, v in docker_config.items()
            if k not in ('postgres-version', 'container-size')
        },
    }

get_app_port

A method that retrieves the host port the project's web server binds to.

The APP_PORT environment variable wins. Otherwise the port is the default, or in multi-project mode it is derived from the project name so every project publishes its server on a port of its own.

Parameters:

• project_name (str) –

  The project name the port is derived from.

• multi_project (bool) –

  Whether this machine runs several projects at once.

Returns:

• int –

  The host port for the web server.

Source code in dev_tool/config/docker.py

def get_app_port(self, project_name: str, *, multi_project: bool) -> int:
    """
    A method that retrieves the host port the project's web server binds to.

    The APP_PORT environment variable wins. Otherwise the port is the default,
    or in multi-project mode it is derived from the project name so every project
    publishes its server on a port of its own.

    :param project_name: The project name the port is derived from.
    :param multi_project: Whether this machine runs several projects at once.
    :return: The host port for the web server.
    """

    override = os.getenv('APP_PORT')

    if override:
        return int(override)

    if not multi_project:
        return DockerDefault.APP_PORT

    return derive_port(project_name, DockerDefault.APP_PORT, DockerDefault.APP_PORT_SPAN)

get_database_port

A method that retrieves the host port the project's database is published on.

Outside multi-project mode the port set in the environment file wins, and the default applies without one. In multi-project mode a configured port still wins, except for the bare 5432 default that every project carries and which is therefore read as no choice at all. Without a choice the port is derived from the project name, so every project publishes its database on a port of its own.

Parameters:

• project_name (str) –

  The project name the port is derived from.

• configured (str | None) –

  The port set in the environment file, if any.

• multi_project (bool) –

  Whether this machine runs several projects at once.

Returns:

• int –

  The host port for the database.

Source code in dev_tool/config/docker.py

def get_database_port(self, project_name: str, configured: str | None, *, multi_project: bool) -> int:
    """
    A method that retrieves the host port the project's database is published on.

    Outside multi-project mode the port set in the environment file wins, and the
    default applies without one. In multi-project mode a configured port still
    wins, except for the bare 5432 default that every project carries and which is
    therefore read as no choice at all. Without a choice the port is derived from
    the project name, so every project publishes its database on a port of its own.

    :param project_name: The project name the port is derived from.
    :param configured: The port set in the environment file, if any.
    :param multi_project: Whether this machine runs several projects at once.
    :return: The host port for the database.
    """

    if not multi_project:
        return int(configured or DockerDefault.DATABASE_PORT)

    if configured and int(configured) != DockerDefault.DATABASE_PORT:
        return int(configured)

    return derive_port(project_name, DockerDefault.DATABASE_PORT, DockerDefault.DATABASE_PORT_SPAN)

get_dockerfile_path

Get the Dockerfile path - project Dockerfile takes precedence over default.

Returns:

• Path | None –

  Path to Dockerfile to use, or None if using standard postgres image

Source code in dev_tool/config/docker.py

def get_dockerfile_path(self) -> Path | None:
    """
    Get the Dockerfile path - project Dockerfile takes precedence over default.

    :return: Path to Dockerfile to use, or None if using standard postgres image
    """

    project = BASE / DockerFileDefault.DB

    if project.exists():
        return project

    if self._resource_path_getter is not None:
        default = self._resource_path_getter(f'templates/docker/{DockerFileDefault.DB}')

        if default.exists():
            return default

    return None

get_ssh_port

A method that retrieves the host port the project's app container exposes SSH on.

The SSH_PORT environment variable wins. Otherwise the port is the default, or in multi-project mode it is derived from the project name so every project publishes SSH on a port of its own.

Parameters:

• project_name (str) –

  The project name the port is derived from.

• multi_project (bool) –

  Whether this machine runs several projects at once.

Returns:

• int –

  The host port for SSH.

Source code in dev_tool/config/docker.py

def get_ssh_port(self, project_name: str, *, multi_project: bool) -> int:
    """
    A method that retrieves the host port the project's app container exposes SSH on.

    The SSH_PORT environment variable wins. Otherwise the port is the default,
    or in multi-project mode it is derived from the project name so every project
    publishes SSH on a port of its own.

    :param project_name: The project name the port is derived from.
    :param multi_project: Whether this machine runs several projects at once.
    :return: The host port for SSH.
    """

    override = os.getenv('SSH_PORT')

    if override:
        return int(override)

    if not multi_project:
        return DockerDefault.SSH_PORT

    return derive_port(project_name, DockerDefault.SSH_PORT, DockerDefault.SSH_PORT_SPAN)

set_notification

A method that sets the notification service.

Parameters:

• notification (NotificationProtocol) –

  The notification service to use.

Source code in dev_tool/config/docker.py

def set_notification(self, notification: NotificationProtocol) -> None:
    """
    A method that sets the notification service.

    :param notification: The notification service to use.
    """

    self._notification = notification

set_resource_path_getter

A method that sets the resource path getter function.

Parameters:

• getter (Callable[[str], Path]) –

  A callable that takes a path string and returns an absolute Path.

Source code in dev_tool/config/docker.py

def set_resource_path_getter(self, getter: Callable[[str], Path]) -> None:
    """
    A method that sets the resource path getter function.

    :param getter: A callable that takes a path string and returns an absolute Path.
    """

    self._resource_path_getter = getter

should_build_custom_image

Determine if we should build a custom image.

Returns:

• bool –

  True if we should build custom image

Source code in dev_tool/config/docker.py

def should_build_custom_image(self) -> bool:
    """
    Determine if we should build a custom image.

    :return: True if we should build custom image
    """

    return self.get_dockerfile_path() is not None