docs: rewrite README with structured overview and quick start guide

Replaces the minimal project description with a comprehensive README
including a component overview table, quick start instructions, common
Ansible operations, and links to detailed documentation. Aligns with
Red Panda Approval™ standards.

ansible/searxng/deploy.yml

@@ -0,0 +1,134 @@
+---
+- name: Deploy SearXNG with Docker Compose
+  hosts: ubuntu
+  become: true
+  tasks:
+  - name: Check if host has searxng service
+    ansible.builtin.set_fact:
+      has_searxng_service: "{{'searxng' in services}}"
+
+  - name: Skip hosts without searxng service
+    ansible.builtin.meta: end_host
+    when: not has_searxng_service
+
+  - name: Create searxng group
+    ansible.builtin.group:
+      name: "{{searxng_group}}"
+
+  - name: Create searxng user
+    ansible.builtin.user:
+      name: "{{searxng_user}}"
+      comment: "{{searxng_user}}"
+      group: "{{searxng_group}}"
+      system: true
+
+  - name: Add group searxng to ansible_user
+    ansible.builtin.user:
+      name: "{{ansible_user}}"
+      groups: "{{searxng_group}}"
+      append: true
+
+  - name: Create searxng directory
+    ansible.builtin.file:
+      path: "{{searxng_directory}}"
+      owner: "{{searxng_user}}"
+      group: "{{searxng_group}}"
+      state: directory
+      mode: '750'
+
+  - name: Template configuration files
+    ansible.builtin.template:
+      src: "{{item.src}}"
+      dest: "{{searxng_directory}}/{{item.dest}}"
+      owner: "{{searxng_user}}"
+      group: "{{searxng_group}}"
+      mode: '550'
+    loop:
+      - src: "docker-compose.yml.j2"
+        dest: "docker-compose.yml"
+      - src: "searxng-settings.yml.j2"
+        dest: "searxng-settings.yml"
+
+  - name: Reset SSH connection to apply group changes
+    meta: reset_connection
+
+  - name: Start SearXNG service
+    community.docker.docker_compose_v2:
+      project_src: "{{searxng_directory}}"
+      state: present
+      pull: always
+
+  # ===========================================================================
+  # OAuth2-Proxy Sidecar
+  # Note: Each host supports at most one OAuth2-Proxy sidecar instance
+  # (binary shared at /usr/local/bin/oauth2-proxy, unique systemd unit per service)
+  # ===========================================================================
+  - name: Create oauth2-proxy directory
+    ansible.builtin.file:
+      path: "{{ searxng_oauth2_proxy_dir }}"
+      owner: root
+      group: root
+      state: directory
+      mode: '0755'
+
+  - name: Download oauth2-proxy binary
+    ansible.builtin.get_url:
+      url: "https://github.com/oauth2-proxy/oauth2-proxy/releases/download/v{{ searxng_oauth2_proxy_version }}/oauth2-proxy-v{{ searxng_oauth2_proxy_version }}.linux-amd64.tar.gz"
+      dest: "/tmp/oauth2-proxy-v{{ searxng_oauth2_proxy_version }}.tar.gz"
+      mode: '0644'
+
+  - name: Extract oauth2-proxy binary
+    ansible.builtin.unarchive:
+      src: "/tmp/oauth2-proxy-v{{ searxng_oauth2_proxy_version }}.tar.gz"
+      dest: /tmp
+      remote_src: true
+      creates: "/tmp/oauth2-proxy-v{{ searxng_oauth2_proxy_version }}.linux-amd64/oauth2-proxy"
+
+  - name: Install oauth2-proxy binary
+    ansible.builtin.copy:
+      src: "/tmp/oauth2-proxy-v{{ searxng_oauth2_proxy_version }}.linux-amd64/oauth2-proxy"
+      dest: /usr/local/bin/oauth2-proxy
+      owner: root
+      group: root
+      mode: '0755'
+      remote_src: true
+
+  - name: Template oauth2-proxy configuration
+    ansible.builtin.template:
+      src: oauth2-proxy-searxng.cfg.j2
+      dest: "{{ searxng_oauth2_proxy_dir }}/oauth2-proxy.cfg"
+      owner: root
+      group: root
+      mode: '0600'
+    notify: restart oauth2-proxy-searxng
+
+  - name: Template oauth2-proxy systemd service
+    ansible.builtin.template:
+      src: oauth2-proxy-searxng.service.j2
+      dest: /etc/systemd/system/oauth2-proxy-searxng.service
+      owner: root
+      group: root
+      mode: '0644'
+    notify:
+      - reload systemd
+      - restart oauth2-proxy-searxng
+
+  # ===========================================================================
+  # Service Management
+  # ===========================================================================
+  - name: Enable and start OAuth2-Proxy service
+    ansible.builtin.systemd:
+      name: oauth2-proxy-searxng
+      enabled: true
+      state: started
+      daemon_reload: true
+
+  handlers:
+  - name: reload systemd
+    ansible.builtin.systemd:
+      daemon_reload: true
+
+  - name: restart oauth2-proxy-searxng
+    ansible.builtin.systemd:
+      name: oauth2-proxy-searxng
+      state: restarted

ansible/searxng/docker-compose.yml.j2

@@ -0,0 +1,18 @@
+services:
+  searxng:
+    image: searxng/searxng:latest
+    pull_policy: always
+    container_name: searxng
+    ports:
+      - "{{ searxng_port }}:8080"
+    volumes:
+      - ./searxng-settings.yml:/etc/searxng/settings.yml:ro
+    restart: unless-stopped
+    logging:
+      driver: syslog
+      options:
+        syslog-address: "tcp://127.0.0.1:{{searxng_syslog_port}}"
+        syslog-format: "{{syslog_format}}"
+        tag: "searxng"
+
+# Red Panda Approved SearXNG Configuration

ansible/searxng/oauth2-proxy-searxng.cfg.j2

@@ -0,0 +1,70 @@
+# OAuth2-Proxy Configuration for SearXNG
+# Authenticates users via Casdoor OIDC before proxying to SearXNG
+# Red Panda Approved
+
+# Provider Configuration (Casdoor OIDC)
+provider = "oidc"
+provider_display_name = "Casdoor"
+oidc_issuer_url = "{{ searxng_oauth2_oidc_issuer_url }}"
+client_id = "{{ searxng_oauth2_client_id }}"
+client_secret = "{{ searxng_oauth2_client_secret }}"
+
+# Redirect URL after authentication
+redirect_url = "{{ searxng_oauth2_redirect_url }}"
+
+# Upstream service (SearXNG on localhost)
+upstreams = [
+    "http://127.0.0.1:{{ searxng_port }}"
+]
+
+# Session/Cookie Configuration
+cookie_secret = "{{ searxng_oauth2_cookie_secret }}"
+cookie_name = "_oauth2_proxy_searxng"
+cookie_secure = true
+cookie_httponly = true
+cookie_samesite = "lax"
+cookie_domains = [
+    ".{{ searxng_domain }}"
+]
+
+# Authentication settings
+email_domains = ["*"]
+oidc_email_claim = "email"
+oidc_groups_claim = "groups"
+
+# Session settings
+session_store_type = "cookie"
+cookie_expire = "168h"
+cookie_refresh = "1h"
+
+# Request settings - pass user info to SearXNG
+pass_access_token = false
+pass_authorization_header = false
+set_authorization_header = false
+set_xauthrequest = true
+
+# Logging
+request_logging = true
+auth_logging = true
+standard_logging = true
+
+# Network settings
+http_address = "0.0.0.0:{{ searxng_proxy_port }}"
+reverse_proxy = true
+real_client_ip_header = "X-Forwarded-For"
+
+# Skip authentication for health check endpoints
+skip_auth_routes = [
+    "^/healthz$",
+    "^/ping$"
+]
+
+# OIDC specific settings
+skip_provider_button = true
+oidc_extra_audiences = []
+insecure_oidc_allow_unverified_email = true
+cookie_csrf_per_request = true
+cookie_csrf_expire = "5m"
+
+# SSL verification (internal Casdoor uses valid certs)
+ssl_insecure_skip_verify = false

ansible/searxng/oauth2-proxy-searxng.service.j2

@@ -0,0 +1,23 @@
+[Unit]
+Description=OAuth2-Proxy for SearXNG
+After=network.target docker.service
+Wants=docker.service
+
+[Service]
+Type=simple
+ExecStart=/usr/local/bin/oauth2-proxy --config={{ searxng_oauth2_proxy_dir }}/oauth2-proxy.cfg
+
+Restart=on-failure
+RestartSec=5
+
+# Security hardening
+NoNewPrivileges=true
+PrivateTmp=true
+
+# Logging
+StandardOutput=journal
+StandardError=journal
+SyslogIdentifier=oauth2-proxy-searxng
+
+[Install]
+WantedBy=multi-user.target

ansible/searxng/searxng-settings.yml.j2

@@ -0,0 +1,42 @@
+use_default_settings: true
+
+general:
+  instance_name: "{{ searxng_instance_name }}"
+  contact_url: false
+  enable_metrics: false
+
+search:
+  safe_search: 0
+  autocomplete: "google"
+  default_lang: "en"
+  formats:
+    - html
+    - json
+
+server:
+  port: 8080
+  bind_address: "0.0.0.0"
+  secret_key: "{{ searxng_secret_key }}"
+  base_url: "{{ searxng_base_url }}"
+  limiter: true
+  public_instance: false
+  method: "GET"
+  image_proxy: true
+
+ui:
+  static_use_hash: true
+  default_theme: simple
+  default_locale: ""
+  theme_args:
+    simple_style: auto
+
+# Red Panda Approved Search Configuration
+engines:
+  - name: google
+    disabled: false
+  - name: duckduckgo
+    disabled: false
+  - name: bing
+    disabled: false
+  - name: startpage
+    disabled: false