Deploy BloodHound CE with the Ludus Ansible Role on Debian

The BloodHound CE Ludus Ansible role automates the deployment of BloodHound Community Edition on Debian-based systems. It uses Docker Compose to install the application and stores the deployment configuration and administrator credentials in a configurable directory.

This role is useful for building controlled security labs and identity assessment environments with BloodHound Community Edition. It checks whether a Docker Compose configuration already exists in the installation directory before creating a new deployment.

How the BloodHound CE Ludus Role Works

The role checks for docker-compose.yml inside the configured installation path. If the file does not exist, it installs the standard BloodHound CE deployment using Docker Compose and writes the administrator credentials to the installation directory.

The default installation path in this guide is /opt/bloodhound. If you need to rebuild the environment, you must stop the existing containers and remove the installation directory before running the role again.

Requirements and Dependencies

The role requires a Debian-based Linux system and depends on the geerlingguy.docker Ansible role to manage Docker installation.

Docker-based lab environments can also benefit from careful network isolation. See our guide to the Docker Security Playground for another example of container-based security testing infrastructure.

BloodHound CE Role Variables

You can customize the installation path, listening port, administrator account, and network exposure through the role variables defined in defaults/main.yml.

Variable	Default in the supplied configuration	Purpose
ludus_bloodhound_ce_install_path	/opt/bloodhound	Stores Docker Compose files and administrator credentials.
ludus_bloodhound_listen_only_localhost	true	Restricts the web interface to localhost when enabled.
ludus_bloodhound_port	8080	Sets the port used by the BloodHound CE web interface.
ludus_bloodhound_admin_password	Not explicitly set	Allows a custom administrator password or uses the role’s password-generation behavior.
ludus_bloodhound_admin_principal_name	admin	Sets the administrator principal name.
ludus_bloodhound_admin_email_address	email@bloodhound.ludus	Sets the administrator email address.
ludus_bloodhound_admin_first_name	Bloodhound	Sets the administrator’s first name.
ludus_bloodhound_admin_last_name	Admin	Sets the administrator’s last name.

Network exposure: Setting ludus_bloodhound_listen_only_localhost to false allows the interface to listen on all network interfaces according to the supplied configuration. Expose the service only to trusted lab networks, and review your firewall rules. Our UFW firewall guide explains how to manage incoming network access on Linux.

Example Ludus Range Configuration

The following configuration defines a Debian 12 virtual machine for hosting Docker-based services and assigns the BloodHound CE role to it.

ludus:
  - vm_name: "{{ range_id }}-docker-services"
    hostname: "{{ range_id }}-services"
    template: debian-12-x64-server-template
    vlan: 99
    ip_last_octet: 2
    ram_gb: 8
    cpus: 2
    linux: true
    testing:
      snapshot: false
      block_internet: false
    roles:
      - badsectorlabs.ludus_bloodhound_ce
    role_vars:
      ludus_bloodhound_listen_only_localhost: false

This example disables the localhost-only setting. Use that configuration only when the web interface must be accessible from other permitted systems on the lab network.

Install and Deploy the Ansible Role

First, add the role to your Ludus environment and export the current range configuration.

ludus ansible roles add badsectorlabs.ludus_bloodhound_ce
ludus range config get > config.yml

Edit config.yml to assign the role to the required virtual machines and configure the variables. Save the file, then upload the updated configuration and deploy the user-defined roles.

ludus range config set -f config.yml
ludus range deploy -t user-defined-roles

After deployment, locate the administrator credentials in the configured installation directory. Store these credentials securely and change any default password before allowing other users to access the environment.

Force a Fresh BloodHound CE Installation

The supplied role checks for an existing Docker Compose file before installing the application. To force a fresh deployment, stop the containers and remove the installation directory.

cd /opt/bloodhound
docker compose down
cd ..
rm -rf /opt/bloodhound

Warning: The final command permanently removes files under /opt/bloodhound. Verify the path carefully and back up any required configuration or credentials before running it. Confirm that the relevant containers have stopped and review the current role’s troubleshooting instructions before redeploying.

For the role’s current defaults, supported variables, and deployment instructions, consult the official Ludus BloodHound CE role repository.