Running Playbooks — Fresh Install

This guide covers how to execute the Diskover Ansible playbook for a first-time deployment — running the full playbook, targeting specific hosts, enabling SSL/TLS, using proxy support, and customizing the Ansible configuration.

Upgrading an existing Diskover deployment? See the Running Playbooks — Upgrades guide instead.

Basic Execution

Running the Full Playbook

From the diskover-ansible repository root, run:

time ansible-playbook -i inventory/hosts.yml install_diskover.yml

This deploys Diskover to all hosts defined in your inventory. The time prefix is optional — it displays how long the deployment took when it finishes.

AWS / Cloud Deployments with PEM Key

If your target hosts use SSH key authentication and you prefer to pass the key on the command line (instead of setting ansible_ssh_private_key_file in the inventory):

time ansible-playbook -i inventory/hosts.yml install_diskover.yml --private-key /path/to/your-key.pem

Increasing Verbosity

If you need more detail in the output (for debugging or understanding what the playbook is doing), add -v flags:

# Slightly more verbose
ansible-playbook -i inventory/hosts.yml install_diskover.yml -v

# Very verbose (shows command arguments)
ansible-playbook -i inventory/hosts.yml install_diskover.yml -vv

# Maximum detail (shows SSH connection info, full module args)
ansible-playbook -i inventory/hosts.yml install_diskover.yml -vvv

You can also set a default verbosity level in ansible.cfg:

verbosity = 1   # Range: 0 (minimal) to 5 (maximum detail)

Dry Run (Check Mode)

To see what the playbook would do without actually making any changes:

ansible-playbook -i inventory/hosts.yml install_diskover.yml --check

Note: Check mode doesn't work perfectly with all tasks — some tasks may report errors because they depend on changes that earlier tasks would have made. It's still useful for seeing what would be modified.

Targeting Specific Hosts with --limit

You don't always need to run the playbook against all hosts. The --limit flag lets you target specific host groups or individual machines.

Recommendation: For a fresh install, it's best to let the playbook run against all hosts without --limit. The playbook already installs components in the correct order and handles dependencies between them. Use --limit primarily for re-running against a host that failed, not for controlling installation order.

That said, --limit is still useful during a fresh install for re-running a failed play against only the hosts that failed — rather than re-running the entire playbook.

Limit by Host Group

Target one or more host groups by name:

# Web host only
time ansible-playbook -i inventory/hosts.yml install_diskover.yml --limit web

# Worker hosts only
time ansible-playbook -i inventory/hosts.yml install_diskover.yml --limit worker

# Elasticsearch hosts only
time ansible-playbook -i inventory/hosts.yml install_diskover.yml --limit elasticsearch

# Web and worker hosts
time ansible-playbook -i inventory/hosts.yml install_diskover.yml --limit web,worker

Limit by IP Address

Target specific machines by IP:

# A single host
time ansible-playbook -i inventory/hosts.yml install_diskover.yml --limit 10.0.1.10

# Multiple hosts
time ansible-playbook -i inventory/hosts.yml install_diskover.yml --limit 10.0.1.10,10.0.1.20

Common --limit Scenarios for Fresh Installs

Important: When using --limit, the playbook only runs the plays that target the specified host groups. Plays targeting other groups are skipped. This means dependencies between components (e.g., Elasticsearch must be running before the Admin API configuration) must already be satisfied.

SSL/TLS Configuration for New Deployments

Enabling HTTPS for the Diskover Web UI is done through Ansible variables. The playbook handles all Nginx configuration, certificate deployment, and Python trust store updates.

Enabling SSL

Set these variables in all.yml before running the playbook:

ssl_enabled: true
ssl_domain: "diskover.example.com"
ssl_cert_source: "/root/certs/diskover.crt"
ssl_key_source: "/root/certs/diskover.key"

Then run the playbook normally. Nginx will be configured with TLS, and HTTP traffic on port 8000 will redirect to HTTPS on port 443.

SSL Requirements

• The SSL certificate and key files must exist on the control machine (the machine running Ansible), not on the target host

• Paths must be absolute (e.g., /root/certs/diskover.crt, not ~/certs/diskover.crt)

• The ssl_domain must match the Common Name (CN) or Subject Alternative Name (SAN) in your certificate

• DNS must resolve ssl_domain to the web host's IP address

Verifying SSL

After the playbook completes:

1. Navigate to https://<ssl_domain>/login.php in your browser

2. Verify the padlock icon appears and the certificate details are correct

3. Confirm that http://<web-host-ip> redirects to HTTPS

Adding SSL to an existing deployment or renewing certificates? See the Running Playbooks — Upgrades guide for those procedures.

Proxy Support

If your target hosts require an HTTP proxy to reach the internet (for downloading packages from JFrog Artifactory, pip packages, etc.), the Ansible repository includes a proxy-aware inventory and playbook.

Setting Up Proxy Support

1. Use the proxy inventory template:

Copy the proxy inventory to your working inventory:

cp docs/example_docs/hosts.proxy.yml inventory/hosts.yml

2. Replace the main playbook with the proxy-aware version:

The repository includes a proxy-aware variant of the playbook that injects proxy environment variables into every play that needs internet access. Copy it over the main playbook:

cp docs/example_docs/install_diskover.proxy.yml install_diskover.yml

This replaces install_diskover.yml with a version that passes your proxy_env settings to all plays that download packages, install dependencies, or otherwise need outbound internet access. The filename stays the same (install_diskover.yml), so all other commands in this guide work without modification.

3. Configure the proxy settings:

Edit the proxy_env block in inventory/hosts.yml:

all:
    vars:
        ansible_connection: ssh
        ansible_user: diskover
        ansible_ssh_pass: "your-ssh-password"
        become: true
        ansible_become_pass: "your-sudo-password"
        proxy_env:
            http_proxy: "http://proxy.example.com:8080"
            https_proxy: "http://proxy.example.com:8080"
            no_proxy: "localhost,127.0.0.1,10.0.0.0/8,192.168.0.0/16"

4. Run the playbook:

time ansible-playbook -i inventory/hosts.yml install_diskover.yml

Important: Make sure you completed step 2 above before running the playbook. The standard install_diskover.yml does not include proxy environment variables — only the proxy-aware version from docs/example_docs/install_diskover.proxy.yml does.

Proxy Settings Explained

Ansible Configuration (ansible.cfg)

The ansible.cfg file in the repository root controls Ansible's behavior. The defaults work well for most deployments, but here are the settings you might want to adjust.

Key Settings

The Ansible Log

Every playbook run is logged to ./ansible.log in the repository root. This log captures the complete output — including any errors that scrolled past in the terminal. If a run fails, check this file first:

# Find errors
grep -n "fatal:" ansible.log

# See context around failures
grep -B 5 -A 10 "fatal:" ansible.log

The log file is overwritten on each run. If you need to preserve logs from previous runs, copy the file before re-running:

cp ansible.log ansible-$(date +%Y%m%d-%H%M%S).log

Playbook Execution Order

Understanding the execution order helps you know what's happening at each stage. The playbook (install_diskover.yml) runs the following plays in sequence:

Each play only runs against hosts in the specified host group. If you use --limit, only plays targeting the limited groups are executed.

Useful Ansible Commands

Beyond running the playbook, these Ansible commands are helpful during deployment and troubleshooting.

Test Connectivity

ansible all -i inventory/hosts.yml -m ping

View Parsed Inventory

ansible-inventory -i inventory/hosts.yml --list

Run an Ad-Hoc Command on All Hosts

# Check OS version
ansible all -i inventory/hosts.yml -m command -a "cat /etc/os-release" --become

# Check disk space
ansible all -i inventory/hosts.yml -m command -a "df -h" --become

# Check service status
ansible web -i inventory/hosts.yml -m command -a "systemctl status nginx" --become

Run Against a Specific Host

ansible 10.0.1.10 -i inventory/hosts.yml -m command -a "systemctl status diskoverd" --become

Next Steps

• For deploying in air-gapped environments, see the Offline / Air-Gapped Installation guide

• When upgrading an existing deployment, see the Running Playbooks — Upgrades guide

• When things go wrong, consult the Troubleshooting guide