Development Environment Setup
Relevant source files
The following files were used as context for generating this wiki page:
Setting up the development environment for the spm-middleware collection involves configuring tools for Ansible content development, including Python virtual environments, Docker-based testing with Molecule, and VS Code Dev Containers. This setup is designed to facilitate the installation and testing of middleware modules required for Cúram Social Program Management (SPM).
The environment focuses on reproducibility and isolation, ensuring that developers can test roles for WebSphere, WebLogic, DB2, and Oracle in a consistent manner. It relies heavily on Molecule for role verification and Artifactory for managing software installers.
Sources: README.md:1-10, CONTRIBUTING.md:105-112
Prerequisites
Before configuring the development environment, ensure the following software is installed on the host machine:
- Git: For version control and repository management.
- Docker CE: Required for running Molecule test containers and DinD (Docker-in-Docker) environments.
- Python >= 3.6: Necessary for running Ansible, Molecule, and managing virtual environments.
- Ansible: Minimum version 2.9 is generally required for the roles in this collection.
Sources: CONTRIBUTING.md:105-112, roles/websphere/meta/main.yml:18
Development Options
There are three primary ways to set up the development environment: VS Code Dev Containers, local Python Virtual Environments, and Docker-in-Docker (DinD) containers.
1. VS Code Dev Containers
This method uses a pre-configured environment within VS Code to standardize the workspace.
- Setup: Add the Dev Containers extension to VS Code.
- Configuration: Create a
.envfile in the.devcontainerfolder with the following variables:ARTIFACTORY_URL: URL for the software installer repository.ARTIFACTORY_REPO: Specific repository name.ARTIFACTORY_TOKEN: Authentication token.LOCAL_PATH: Path to the workspace (e.g.,/workspaces/spm-middleware).
Sources: README.md:30-45
2. Python Virtual Environment (venv)
Recommended for local role development and running Molecule tests without full containerization of the development tools.
python3 -m venv ~/venv/molecule
. ~/venv/molecule/bin/activate
pip install --upgrade pip
pip install -r requirements.txt
Sources: CONTRIBUTING.md:1-7
3. Docker-in-Docker (DinD) Environment
For a completely isolated containerized development setup, developers can build and run a dedicated molecule image.
The following diagram illustrates the lifecycle of a development container.
Sources: CONTRIBUTING.md:31-65
Molecule Testing Framework
Molecule is the primary tool used for testing Ansible roles. It manages the lifecycle of test instances (usually Docker containers) to verify role idempotency and correctness.
Molecule Workflow
The standard testing sequence includes several stages:
- Dependency: Fetching required roles or collections.
- Create/Prepare: Provisioning the test instance and applying base configurations.
- Converge: Running the actual Ansible role being tested.
- Idempotence: Running the role again to ensure no changes are made on the second pass.
- Verify: Running test playbooks (e.g.,
verify.yml) to assert the state of the system. - Destroy: Cleaning up the test instances.
Sources: CONTRIBUTING.md:14-25, CONTRIBUTING.md:130-136
Common Commands
| Command | Description |
|---|---|
molecule test -s <scenario> | Runs the full test sequence (destroy, create, converge, verify, destroy). |
molecule test -s <scenario> --destroy never | Runs the sequence but keeps the container for debugging. |
molecule verify -s <scenario> | Runs only the verification tasks against an existing instance. |
Sources: CONTRIBUTING.md:16-25, CONTRIBUTING.md:135
Artifactory Integration
The middleware installation roles often require large installers (e.g., WebSphere, Oracle, Java). These are typically retrieved from a central Artifactory repository.
The diagram shows how installers are retrieved during the converge stage of development.
Sources: CONTRIBUTING.md:9-13, roles/websphere/tasks/v90_base_install.yml:25-30
Environment Variables Configuration
The following variables must be configured to ensure roles can access necessary binaries:
| Variable | Usage | Source File |
|---|---|---|
ARTIFACTORY_URL | Base URL of the Artifactory instance. | README.md |
ARTIFACTORY_TOKEN | API token for authentication. | CONTRIBUTING.md |
ARTIFACTORY_REPO | Target repository for installers. | CONTRIBUTING.md |
LOCAL_PATH | Host path to the repository. | README.md |
Sources: README.md:40-44, CONTRIBUTING.md:55-58
Summary
The spm-middleware development environment is built around Ansible, Molecule, and Docker. By using VS Code Dev Containers or local Python virtual environments, developers can ensure their roles meet the project's contribution criteria: inclusion of Molecule scenarios, adherence to idempotency, and passing the Ansible linter. This structured approach allows for reliable testing of complex middleware installations across various Linux distributions like Rocky Linux and Red Hat Enterprise Linux.
Sources: README.md:1-5, CONTRIBUTING.md:100-105