Ansible Section

Three publicly accessible pages providing an interactive template sandbox, playbook documentation, and a deployment guide. All use BaseLayout (not CosmicLayout) and require no authentication -- the middleware pipeline classifies these routes as public and skips the Cloudflare Access check entirely.

Ansible Sandbox (/ansible/sandbox)

Interactive template selection and deployment interface. Users browse visual effect templates, preview them in the browser, and optionally deploy them.

Template Library

Five templates across three difficulty levels:

Template	Difficulty	Description
Fireworks	Basic	Canvas-based particle fireworks with configurable colors and burst patterns
Matrix Rain	Intermediate	Falling green character columns with variable speed and density
Starfield	Basic	3D starfield fly-through with depth-based parallax
Particles	Intermediate	Interactive particle system responding to mouse movement
3D Globe	Advanced	WebGL rotating earth mesh with point plotting and arc connections

Each template renders as a card with name, difficulty badge, and description. Two action buttons per card:

• Preview -- renders the template in an embedded iframe, entirely client-side
• Deploy -- sends the template configuration to the backend, triggering the Ansible playbook execution on a target host

Simulation Mode

A toggle at the top switches between live and simulation mode. In simulation mode, Deploy runs a client-side mock instead of hitting the real backend -- a simulated progress log renders with realistic timing and status messages. Useful for demonstrations and exploring the workflow without provisioning infrastructure.

Ansible Docs (/ansible/docs)

Comprehensive playbook documentation with a sidebar navigation that mirrors the section hierarchy. A back link to the sandbox sits at the top of the sidebar. The sidebar highlights the currently visible section via Intersection Observer scroll tracking.

Documentation Structure

Getting Started -- Prerequisites, inventory configuration, SSH key distribution, ansible.cfg defaults, directory layout conventions, and running a first playbook.

Playbooks -- Detailed docs for each playbook:

Playbook	Purpose
Web Server	Nginx/Apache with TLS, virtual hosts, reverse proxy
Docker Compose	Stack deployment with env templating and volume management
K3s	Lightweight Kubernetes provisioning (single and multi-node)
LAMP	Linux/Apache/MySQL/PHP with DB init and module management
Security Hardening	CIS-inspired hardening: SSH lockdown, firewall, fail2ban, audit logging

Each section covers purpose, required variables, example inventory, and the execution command.

Advanced Topics:

• Custom Roles -- role structure (defaults/, tasks/, handlers/, templates/, meta/), dependencies, variable precedence
• Variables & Inventory -- INI/YAML formats, group/host vars, precedence order, ansible-vault encryption
• Best Practices -- idempotency patterns, handler usage, tag strategies, --check/--diff testing

Reference:

• CLI Commands -- common ansible, ansible-playbook, ansible-vault, ansible-galaxy invocations
• Troubleshooting -- SSH failures, privilege escalation errors, missing modules, undefined variables, unnotified handlers

Ansible Help (/ansible/help)

Step-by-step deployment guide with visual step numbering (large gradient-styled numbered circles with vertical connecting lines) and YAML syntax highlighting examples.

Four Steps

Step 1: Select Playbook -- Browse the sandbox template library, choose a playbook. The guide explains difficulty levels and which templates suit different use cases.

Step 2: Explore Code -- Review the YAML source before executing. The guide walks through task structure with a highlighted example:

- name: Install and configure Nginx
  hosts: webservers
  become: true
  vars:
    nginx_worker_processes: auto
    nginx_worker_connections: 1024
  tasks:
    - name: Install Nginx package
      ansible.builtin.apt:
        name: nginx
        state: present
        update_cache: true

    - name: Deploy Nginx configuration
      ansible.builtin.template:
        src: nginx.conf.j2
        dest: /etc/nginx/nginx.conf
      notify: Restart Nginx

  handlers:
    - name: Restart Nginx
      ansible.builtin.service:
        name: nginx
        state: restarted

Step 3: Configure Parameters -- Set required variables: target host/group, SSH user and key, application-specific values (ports, domains, credentials), environment toggles, and role default overrides. Presented as a checklist for verification.

Step 4: Deploy Environment -- Execute with ansible-playbook, read the play recap (ok/changed/unreachable/failed), verify service status on the target, and roll back if needed via corrected variables or --tags rollback.

Code blocks use YAML syntax highlighting via Shiki, rendered at build time consistent with the rest of the site.

Technical Notes

Script Architecture

The sandbox page uses <script is:inline> because it manipulates the DOM of template cards, deploy buttons, and progress indicators directly. Configuration values (API_BASE_URL, BASE_DOMAIN) are passed from Astro frontmatter to the inline script via a <script type="application/json"> config element, which the script parses at runtime.

Important: Do not use define:vars with is:inline scripts — Astro's compilation injects import.meta references that fail in classic (non-module) scripts. The JSON config element pattern avoids this entirely. See CSP & Security Headers for related security header configuration.