Docker-in-Docker (DinD) Setup
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The Docker-in-Docker (DinD) setup in the spm-middleware project provides a containerized development environment specifically designed for running Molecule tests. This approach encapsulates all necessary dependencies—including Ansible, Python, and the Docker CLI—within a single container, allowing developers to test middleware roles without polluting their local host environment.
Sources: CONTRIBUTING.md:46-52, README.md:38-40
This environment is particularly useful for verifying the installation and configuration of complex middleware components like IBM WebSphere, DB2, and Oracle, which are managed by this collection. By using a privileged container, Molecule can spawn additional guest containers inside the development container to simulate various target operating systems.
Sources: README.md:1-5, CONTRIBUTING.md:73-75
Architecture and Components
The DinD architecture consists of a host machine running Docker, which hosts a "Molecule Container." This container, in turn, manages life cycles of "Test Containers" where the actual Ansible roles are executed.
Core Architecture Flow
The following diagram illustrates the relationship between the Host, the Molecule (DinD) Container, and the spawned Test Containers.
The setup requires the --privileged flag to allow the inner Docker engine to function correctly and mount necessary filesystems like cgroups.
Sources: CONTRIBUTING.md:58-61, molecule/db21145/molecule.yml:15-18
Components Table
| Component | Description | Requirement |
|---|---|---|
| Molecule Image | Custom image molecule:latest containing Python, Ansible, and Docker. | docker build -t molecule:latest . |
| Privileged Mode | Grants the container root access to the host's kernel features. | Required for DinD functionality. |
| Volume Mapping | Links local source code to /opt/spm-middleware in the container. | -v $LOCAL_PATH:/opt/spm-middleware |
| Environment Variables | Configuration for Artifactory and installer locations. | ARTIFACTORY_URL, ARTIFACTORY_TOKEN, etc. |
Sources: CONTRIBUTING.md:54-65, README.md:44-50
Configuration and Deployment
The environment is initialized by building a local image and running it with specific volume mounts. This ensures that changes made to the roles on the host machine are immediately reflected inside the container.
Execution Workflow
Sources: CONTRIBUTING.md:54-75, README.md:53-70
Environment Variables
When using external installers from Artifactory, the container must be started with specific environment variables to authenticate and locate the software binaries.
| Variable | Usage | Source |
|---|---|---|
ARTIFACTORY_URL | Base URL of the Artifactory instance. | CONTRIBUTING.md:71 |
ARTIFACTORY_REPO | Repository name containing software installers. | CONTRIBUTING.md:72 |
ARTIFACTORY_TOKEN | Authentication token for the repository. | CONTRIBUTING.md:73 |
LOCAL_PATH | Path to the spm-middleware git clone on the host. | CONTRIBUTING.md:74 |
Sources: CONTRIBUTING.md:68-75, README.md:46-49
Testing and Verification
Once the DinD container is running, developers interact with it using docker exec. An alias modo is recommended for convenience.
Test Commands
The project supports testing specific scenarios (e.g., db2, websphere, ihs). The molecule test command follows a sequence of actions including dependency resolution, creation, convergence, and verification.
- Standard Test:
molecule test -s <scenario_name> - Keep Container on Failure:
molecule test -s <scenario_name> --destroy never - Check Inner Containers:
modo docker ps(executes docker commands inside the DinD container).
Sources: CONTRIBUTING.md:85-110, README.md:68-70
Role Installation Logic (Example: WebSphere)
Inside the Test Containers, the middleware roles perform complex download and extraction logic. If a download_url (derived from Artifactory variables) is provided, the role fetches installers via get_url; otherwise, it uses local copy tasks.
Summary
The Docker-in-Docker setup provides a standardized, isolated environment for developing and testing the spm_middleware collection. By leveraging --privileged containers and volume mounting, it allows for iterative development of idempotent Ansible roles for Cúram Social Program Management middleware.
Sources: CONTRIBUTING.md:46-52, README.md:1-5