Deployment Guide

This guide covers the complete deployment of Cyber Sentinel from a fresh Linux server to a fully operational stack. The entire process is automated through Ansible — a single master playbook (00_main.yml) orchestrates all steps in the correct order.

Prerequisites

Before running any playbook, make sure your control machine (your laptop or workstation) meets the following requirements:

# Install Ansible
pip3 install ansible

# Install required Python libraries for Vault and Docker modules
pip3 install hvac docker

# Verify
ansible --version

Supported Architectures

Ansible automatically detects the target architecture and adjusts the Docker installation accordingly.

If you are running on a Raspberry Pi 5 with an Argon NEO 5 case, playbook 03 automatically installs and configures the fan controller with thresholds optimised for AI workloads (55°C → 100%, 65°C → 100%).

Inventory Setup

Edit ansible/hosts.ini to point to your target server. The repository ships with three pre-configured environments:

# --- 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

[all_servers:children]
rpi5-prod
vm-prox-dev
local-vm

Use -l to target a specific environment: ansible-playbook ... -l rpi5-prod

For the full configuration reference (all_servers.yml, vault.yml, templates) see → Config Reference.

Vault — Bootstrap Secrets

Cyber Sentinel uses Ansible Vault to protect bootstrap secrets (passwords injected into .env before containers start). Before your first run you must provide values for the following variables in ansible/group_vars/all/vault.yml:

vault_grafana_password: "your_grafana_password"
vault_mongodb_password: "your_mongodb_password"
vault_mysql_root_password: "your_mysql_root_password"

Encrypt the file:

ansible-vault encrypt ansible/group_vars/all/vault.yml

Store the vault password in ansible/.vault_pass (this file is in .gitignore):

echo "your_vault_passphrase" > ansible/.vault_pass
chmod 600 ansible/.vault_pass

Running the Full Deployment

Execute the master playbook to run all steps end-to-end:

ansible-playbook ansible/00_main.yml \
  -i ansible/hosts.ini \
  --vault-password-file ansible/.vault_pass

This single command runs all playbooks in sequence:

- import_playbook: 01_setup_secrets.yml
- import_playbook: 02_setup_security.yml
- import_playbook: 03_setup_system.yml
- import_playbook: 04_1_prepare_stack.yml
- import_playbook: 04_2_deploy_containers.yml
- import_playbook: 04_3_db_create.yml
- import_playbook: 04_4_post_config.yml
- import_playbook: 05_deploy_proxy.yml
- import_playbook: 06_1_initialize_vault.yml

Deployment Pipeline

The full deployment consists of 9 playbooks executed in order. Each playbook is self-contained and can also be run individually for partial re-deployments.

Running Individual Playbooks

You can re-run any single playbook without going through the full pipeline:

# Example: re-deploy only the Docker stack
ansible-playbook ansible/04_2_deploy_containers.yml \
  -i ansible/hosts.ini \
  --vault-password-file ansible/.vault_pass

# Example: re-apply firewall rules only
ansible-playbook ansible/02_setup_security.yml \
  -i ansible/hosts.ini \
  --vault-password-file ansible/.vault_pass

Firewall — Open Ports After Deployment

After playbook 02 completes, the following ports are open on the target server:

All other incoming traffic is denied by default (UFW default policy: deny).

Post-Deployment Access

Once the full pipeline completes, services are accessible via the Nginx reverse proxy using subdomains of your configured domain_suffix: