How badgeteam/badgehub-infra works
Project Type & Purpose
• This project is an infrastructure-as-code repository using Ansible to provision and configure Debian servers for hosting BadgeHub services. It focuses on configuring system essentials (users, firewall, filesystem, SSH, Docker) and deploying service containers for the BadgeHub API and Keycloak (an authentication service).
• The README clarifies that the infrastructure is built with modular roles for reproducible server configuration suitable for both testing and production environments.
Analyzing the File Structure
• Top-Level Files & Directories:
– There are configuration files such as .editorconfig, .gitignore, LICENSE, and README.md.
– Directories like "badgehub" and "keycloak" include Docker Compose files and environment examples, indicating containerized components for the BadgeHub API and authentication via Keycloak.
– The "group_vars" directory holds environment-specific variables for different host groups.
– Ansible playbooks (playbook_dev.yaml, playbook_prod.yaml) are included alongside "roles".
• The “roles” directory contains modular Ansible roles for various infrastructure configurations:
– System: Base package installations, time, and logging settings.
– User: User creation and SSH key configuration.
– UFW: Firewall configuration via UFW.
– Docker: Installation and configuration of Docker along with prune services.
– Filesystem: Creating directories for Docker Compose apps.
– SSH: Configuring SSH daemon settings.
– BadgeHub API: Deployment logic that creates necessary directories and clones the repository.
• Additionally, there are roles that handle Docker configurations and custom templates, indicating a focus on automated, repeatable infrastructure setups.
To accurately capture the architecture:
a. Main components:
– Ansible Controller: Represents the automation engine from where playbooks are executed.
– Target Infrastructure Servers: Debian-based VMs that will be configured.
– Key Infrastructure Components on the target servers:
• System Configuration: Handles base OS setup (system, user, SSH, filesystem, journald).
• Network & Security: UFW configuration (firewall) ensures secure network access.
• Container Management: Docker setup including Docker Compose applications.
• Application Services: Two primary containerized services represented by:
▪ BadgeHub API (in the “badgehub” directory with its Docker Compose file)
▪ Keycloak (in the “keycloak” directory for authentication)
– External Artifacts:
• Preseed scripts and host inventory files that facilitate initial system provisioning and variable injection.
b. Relationships & Interactions:
– The Ansible Controller (via playbooks) connects and pushes configurations to the target Debian servers.
– Each modular role (e.g., system, user, UFW, docker) configures different aspects of the system.
– Docker plays a central role – it manages containerized components. Two key containers (BadgeHub API and Keycloak) are managed via Docker Compose.
– There is a dependency flow: before application deployment, system-level configurations (user, SSH, UFW, system) must be performed to create a secure and stable host environment.
– The Docker role, along with the filesystem role (which creates the necessary directory for Docker Compose), supports the launch of service containers.
c. Architectural Patterns & Design Principles:
– Modular Design: Roles are self-contained and independent, promoting clear separation of concerns.
– Infrastructure as Code: The repository uses Ansible for reproducible, automated configurations.
– Containerization: Docker and Docker Compose are used to encapsulate the BadgeHub API and authentication services.
– Environment-Specific Configuration: Group variable files in “group_vars” enable tailoring the deployment for different environments (development, testing, production).
d. Relevant Technologies & Frameworks:
– Ansible (for orchestration and configuration management)
– Docker & Docker Compose (for container management)
– Debian (target operating system)
– UFW (for firewalling)
– Keycloak (for authentication)
– Various YAML and Jinja2 templates for role configurations