Ansible Configuration Reference

This page documents all static configuration files used by the Ansible layer of Cyber Sentinel. These files define the runtime environment, target hosts, global variables, and Jinja2 templates that the playbooks depend on.

ansible/
├── ansible.cfg                     # Ansible runtime settings
├── hosts.ini                       # Inventory — target environments
├── group_vars/
│   └── all/
│       ├── all_servers.yml         # Non-sensitive global variables
│       └── vault.yml               # 🔐 Ansible Vault encrypted secrets
└── templates/
    ├── env.j2                      # Docker .env file template
    └── nginx_service.conf.j2       # Per-service Nginx proxy config template

1. ansible.cfg

Path: ansible/ansible.cfg

The Ansible runtime configuration file. Sets default inventory, disables SSH host key verification for internal hosts, and points to the Vault password file for automatic secret decryption.

1
2
3
4
5

[defaults]
inventory = hosts.ini
host_key_checking = False
interpreter_python = auto_silent
vault_password_file = /home/hunter/IdeaProjects/cyber-sentinel/ansible/.vault_pass

The vault_password_file path is absolute and points to the control machine (Linux Mint). If you clone the repository to a different path or user, update this value before running any playbook. The .vault_pass file must exist and must not be committed to version control.

2. hosts.ini

Path: ansible/hosts.ini

The Ansible inventory file. Defines three target environments: production Raspberry Pi 5, a Proxmox development VM, and a local VM accessible via SSH port forwarding. All three environments are collected under the all_servers parent group used by every playbook.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

# --- PROD env ---
[rpi5-prod]
rpi5 ansible_host=192.168.0.2 ansible_user=hunter

# --- DEV env ---
[vm-prox-dev]
dev_vm ansible_host=192.168.0.5 ansible_user=hunter

# --- Local DEV VM env ---
[local-vm]
local_vm ansible_host=127.0.0.1 ansible_port=2222 ansible_user=hunter

# --- Group combining all hosts ---
[all_servers:children]
rpi5-prod
vm-prox-dev
local-vm

Environments

In playbook 05_deploy_proxy.yml, the variable domain_suffix is set to local when the target host is in the vm-prox-dev group, and prod otherwise. This controls which subdomain pattern Nginx uses for SSL virtual hosts.

Targeting a specific environment

You can limit execution to a single environment by passing -l (limit) to ansible-playbook:

# Run only on production RPi 5
ansible-playbook ansible/00_main.yml -i ansible/hosts.ini -l rpi5-prod \
  --vault-password-file ansible/.vault_pass

# Run only on the dev VM
ansible-playbook ansible/00_main.yml -i ansible/hosts.ini -l vm-prox-dev \
  --vault-password-file ansible/.vault_pass

3. group_vars/all/all_servers.yml

Path: ansible/group_vars/all/all_servers.yml

Non-sensitive global variables shared across all hosts and all playbooks. Loaded automatically by Ansible before any playbook runs. Defines paths, usernames, database parameters, and service account names.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

# Local source directory on the controller host (Linux Mint)
main_repo_source_dir: "/home/hunter/IdeaProjects/cyber-sentinel"

# Base directory on the remote host for deployment
remote_deploy_base: "/home/{{ ansible_user }}"

# Owner and group for all copied files and directories
deployment_user: "{{ ansible_user }}"

# MongoDB
mongodb_username: "hunter"

# MySQL
mysql_host: "mysqldb"
mysql_user: "hunter"
mysql_database: "cyber_intelligence"

# Service admin accounts
portainer_admin_user: "admin_sentinel"
n8n_admin_user: "n8n_manager"
n8n_admin_email: "hunter@cyber-sentinel.local"

# Vault-related references
vault_mysql_database: "{{ mysql_database }}"
vault_mysql_app_user: "{{ mysql_user }}"
vault_address: "10.10.10.12"

Variable reference

This path points to the repository on the control machine (the machine running ansible-playbook). If you clone the repository to a different path, update this variable before running any playbook.

4. group_vars/all/vault.yml

Path: ansible/group_vars/all/vault.yml

Ansible Vault encrypted file containing all sensitive secrets. Never stored in plaintext. Loaded automatically alongside all_servers.yml. The actual values are decrypted at runtime using the passphrase from .vault_pass.

# Encrypt the file (first time)
ansible-vault encrypt ansible/group_vars/all/vault.yml

# Edit secrets interactively
ansible-vault edit ansible/group_vars/all/vault.yml

# View decrypted content
ansible-vault view ansible/group_vars/all/vault.yml

Required variables

All variables prefixed with vault_ must be defined in this file:

These two variables are only available after running playbook 06_1_initialize_vault.yml for the first time. Save the vault operator init output immediately, then add these values to vault.yml before running 06_2_provision_vault.yml.

5. templates/env.j2

Path: ansible/templates/env.j2

Jinja2 template rendered by playbook 01_setup_secrets.yml (Task 1.1) into .env at the deployment root. This file is consumed by Docker Compose to inject environment variables into all containers at startup.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

# MongoDB
MONGODB_PASSWORD={{ vault_mongodb_password }}
MONGODB_USERNAME={{ mongodb_username }}

# MySQL
MYSQL_HOST={{ mysql_host }}
MYSQL_USER={{ mysql_user }}
MYSQL_PASSWORD={{ vault_mysql_password }}
MYSQL_DATABASE={{ mysql_database }}
MYSQL_ROOT_PASSWORD={{ vault_mysql_root_password }}

# Grafana
GRAFANA_PASSWORD={{ vault_grafana_password }}

# HashiCorp Vault
VAULT_ROOT_TOKEN={{ vault_root_token }}
VAULT_ADDR=http://0.0.0.0:8200

Variable mapping

The rendered .env file is written with mode: '0600' by playbook 01. The same restriction is enforced again in playbook 04_1 via lineinfile. Never commit the rendered .env to version control — it is listed in .gitignore.

6. templates/nginx_service.conf.j2

Path: ansible/templates/nginx_service.conf.j2

Jinja2 template rendered once per proxied service by playbook 05_deploy_proxy.yml (Task 5.3). Produces a dedicated Nginx server block file (<service_name>.conf) in config/nginx/conf.d/ for each entry in the services list variable.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

server {
    listen 80;
    server_name {{ item.name }}.{{ domain_suffix }};
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl;
    server_name {{ item.name }}.{{ domain_suffix }};

    ssl_certificate     /etc/nginx/certs/{{ item.name }}.crt;
    ssl_certificate_key /etc/nginx/certs/{{ item.name }}.key;

    resolver 127.0.0.11 valid=30s;

    location / {
        resolver 127.0.0.11 valid=30s;
        set $upstream_host {{ item.internal_host }};
        proxy_pass http://$upstream_host:{{ item.port }};

        proxy_set_header Host              $host;
        proxy_set_header X-Real-IP         $remote_addr;
        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # WebSocket support (required for n8n and Portainer)
        proxy_http_version 1.1;
        proxy_set_header Upgrade    $http_upgrade;
        proxy_set_header Connection "Upgrade";
    }
}

Template variable mapping

Generated output example

For service n8n in a dev environment (domain_suffix=local), the template produces config/nginx/conf.d/n8n.conf:

server {
    listen 80;
    server_name n8n.local;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl;
    server_name n8n.local;

    ssl_certificate     /etc/nginx/certs/n8n.crt;
    ssl_certificate_key /etc/nginx/certs/n8n.key;

    resolver 127.0.0.11 valid=30s;

    location / {
        resolver 127.0.0.11 valid=30s;
        set $upstream_host n8n-server;
        proxy_pass http://n8n-server:5678;

        proxy_set_header Host              n8n.local;
        proxy_set_header X-Real-IP         $remote_addr;
        proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto https;

        proxy_http_version 1.1;
        proxy_set_header Upgrade    $http_upgrade;
        proxy_set_header Connection "Upgrade";
    }
}

The resolver 127.0.0.11 directive points to Docker's internal DNS resolver. Using set $upstream_host with a variable (instead of a hardcoded proxy_pass) forces Nginx to re-resolve the hostname at request time rather than at startup — this prevents Nginx from failing to start if the upstream container is not yet running.

The Upgrade and Connection headers are required for services that use WebSockets. In this stack, both n8n (real-time workflow execution UI) and Portainer (live container log streaming) depend on WebSocket connections.