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.
2026-03-03 12:49:06 +00:00
parent c7be03a743
commit b4d60f2f38
219 changed files with 34586 additions and 2 deletions
--- a/ansible/oauth2_proxy/deploy.yml
+++ b/ansible/oauth2_proxy/deploy.yml
@@ -0,0 +1,75 @@
+---
+# OAuth2-Proxy Deployment for SearXNG Authentication
+# Provides OIDC authentication layer using Casdoor as identity provider
+# Red Panda Approved
+
+- name: Deploy OAuth2-Proxy for SearXNG
+  hosts: ubuntu
+  become: true
+  tasks:
+    - name: Check if host has oauth2_proxy service
+      ansible.builtin.set_fact:
+        has_oauth2_proxy_service: "{{'oauth2_proxy' in services}}"
+
+    - name: Skip hosts without oauth2_proxy service
+      ansible.builtin.meta: end_host
+      when: not has_oauth2_proxy_service
+
+    - name: Create oauth2-proxy group
+      ansible.builtin.group:
+        name: "{{ oauth2_proxy_group }}"
+        gid: "{{ oauth2_proxy_gid }}"
+        system: true
+
+    - name: Create oauth2-proxy user
+      ansible.builtin.user:
+        name: "{{ oauth2_proxy_user }}"
+        uid: "{{ oauth2_proxy_uid }}"
+        comment: "OAuth2 Proxy Service"
+        group: "{{ oauth2_proxy_group }}"
+        system: true
+        create_home: false
+        shell: /usr/sbin/nologin
+
+    - name: Add oauth2-proxy group to ansible user
+      ansible.builtin.user:
+        name: "{{ ansible_user }}"
+        groups: "{{ oauth2_proxy_group }}"
+        append: true
+
+    - name: Create oauth2-proxy directory
+      ansible.builtin.file:
+        path: "{{ oauth2_proxy_directory }}"
+        owner: "{{ oauth2_proxy_user }}"
+        group: "{{ oauth2_proxy_group }}"
+        state: directory
+        mode: '0750'
+
+    - name: Template configuration files
+      ansible.builtin.template:
+        src: "{{ item.src }}"
+        dest: "{{ oauth2_proxy_directory }}/{{ item.dest }}"
+        owner: "{{ oauth2_proxy_user }}"
+        group: "{{ oauth2_proxy_group }}"
+        mode: "{{ item.mode | default('0640') }}"
+      loop:
+        - src: "docker-compose.yml.j2"
+          dest: "docker-compose.yml"
+        - src: "oauth2-proxy.cfg.j2"
+          dest: "oauth2-proxy.cfg"
+          mode: "0600"
+      notify: Restart oauth2-proxy
+
+    - name: Reset SSH connection to apply group changes
+      meta: reset_connection
+
+    - name: Start OAuth2-Proxy service
+      community.docker.docker_compose_v2:
+        project_src: "{{ oauth2_proxy_directory }}"
+        state: present
+
+  handlers:
+    - name: Restart oauth2-proxy
+      community.docker.docker_compose_v2:
+        project_src: "{{ oauth2_proxy_directory }}"
+        state: restarted
--- a/ansible/oauth2_proxy/docker-compose.yml.j2
+++ b/ansible/oauth2_proxy/docker-compose.yml.j2
@@ -0,0 +1,29 @@
+---
+# OAuth2-Proxy Docker Compose Configuration
+# Provides OIDC authentication for protected services
+# Red Panda Approved
+
+services:
+  oauth2-proxy:
+    image: quay.io/oauth2-proxy/oauth2-proxy:v7.6.0
+    container_name: oauth2-proxy
+    user: "{{ oauth2_proxy_uid }}:{{ oauth2_proxy_gid }}"
+    ports:
+      - "{{ oauth2_proxy_port }}:4180"
+    volumes:
+      - ./oauth2-proxy.cfg:/etc/oauth2-proxy/oauth2-proxy.cfg:ro
+    command:
+      - --config=/etc/oauth2-proxy/oauth2-proxy.cfg
+    restart: unless-stopped
+    logging:
+      driver: syslog
+      options:
+        syslog-address: "tcp://127.0.0.1:{{ oauth2_proxy_syslog_port }}"
+        syslog-format: "{{ syslog_format }}"
+        tag: "oauth2-proxy"
+    healthcheck:
+      test: ["CMD", "wget", "--quiet", "--tries=1", "--spider", "http://localhost:4180/ping"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 10s
--- a/ansible/oauth2_proxy/oauth2-proxy.cfg.j2
+++ b/ansible/oauth2_proxy/oauth2-proxy.cfg.j2
@@ -0,0 +1,67 @@
+# OAuth2-Proxy Configuration
+# Authenticates users via Casdoor OIDC before proxying to upstream services
+# Red Panda Approved
+
+# Provider Configuration (Casdoor OIDC)
+provider = "oidc"
+provider_display_name = "Casdoor"
+oidc_issuer_url = "{{ oauth2_proxy_oidc_issuer_url }}"
+client_id = "{{ oauth2_proxy_client_id }}"
+client_secret = "{{ oauth2_proxy_client_secret }}"
+
+# Redirect URL after authentication
+redirect_url = "{{ oauth2_proxy_redirect_url }}"
+
+# Upstream service
+upstreams = [
+    "{{ oauth2_proxy_upstream_url }}"
+]
+
+# Session/Cookie Configuration
+cookie_secret = "{{ oauth2_proxy_cookie_secret }}"
+cookie_name = "{{ oauth2_proxy_cookie_name | default('_oauth2_proxy') }}"
+cookie_secure = true
+cookie_httponly = true
+cookie_expire = "{{ oauth2_proxy_cookie_expire | default('168h') }}"
+cookie_refresh = "{{ oauth2_proxy_cookie_refresh | default('1h') }}"
+cookie_domains = ".{{ oauth2_proxy_cookie_domain }}"
+session_store_type = "cookie"
+
+# Authentication settings
+email_domains = {{ oauth2_proxy_email_domains | to_json }}
+oidc_email_claim = "email"
+oidc_groups_claim = "groups"
+
+# Allow specific groups (if configured in Casdoor)
+{% if oauth2_proxy_allowed_groups is defined and oauth2_proxy_allowed_groups | length > 0 %}
+allowed_groups = {{ oauth2_proxy_allowed_groups | to_json }}
+{% endif %}
+
+# Request settings
+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:4180"
+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 = []
+
+# SSL verification
+ssl_insecure_skip_verify = {{ oauth2_proxy_skip_ssl_verify | default(false) | lower }}
--- a/ansible/oauth2_proxy/stage.yml
+++ b/ansible/oauth2_proxy/stage.yml
@@ -0,0 +1,93 @@
+---
+# OAuth2-Proxy Staging Playbook
+# Use this to validate configuration before deployment
+# Red Panda Approved
+
+- name: Stage OAuth2-Proxy Configuration (Dry Run)
+  hosts: ubuntu
+  become: true
+  tasks:
+    - name: Check if host has oauth2_proxy service
+      ansible.builtin.set_fact:
+        has_oauth2_proxy_service: "{{'oauth2_proxy' in services}}"
+
+    - name: Skip hosts without oauth2_proxy service
+      ansible.builtin.meta: end_host
+      when: not has_oauth2_proxy_service
+
+    - name: Validate required OAuth2-Proxy variables are defined
+      ansible.builtin.assert:
+        that:
+          - oauth2_proxy_client_id is defined
+          - oauth2_proxy_client_secret is defined
+          - oauth2_proxy_cookie_secret is defined
+        fail_msg: |
+          Missing required OAuth2-Proxy variables. Ensure service-specific vault variables
+          are mapped to oauth2_proxy_client_id, oauth2_proxy_client_secret, and
+          oauth2_proxy_cookie_secret in the host_vars file.
+          
+          Generate cookie secret with: python3 -c 'import secrets; print(secrets.token_urlsafe(32))'
+
+    - name: Validate OIDC issuer URL is accessible
+      ansible.builtin.uri:
+        url: "{{ oauth2_proxy_oidc_issuer_url }}/.well-known/openid-configuration"
+        method: GET
+        return_content: true
+        status_code: 200
+      register: oidc_discovery
+      failed_when: false
+
+    - name: Report OIDC discovery status
+      ansible.builtin.debug:
+        msg: "{{ 'OIDC Discovery: OK' if oidc_discovery.status == 200 else 'OIDC Discovery: FAILED - Casdoor may not be running or accessible' }}"
+
+    - name: Validate upstream URL is accessible
+      ansible.builtin.uri:
+        url: "{{ oauth2_proxy_upstream_url }}"
+        method: GET
+        return_content: false
+        status_code: [200, 301, 302]
+      register: upstream_check
+      failed_when: false
+
+    - name: Report upstream status
+      ansible.builtin.debug:
+        msg: "{{ 'Upstream SearXNG: OK' if upstream_check.status in [200, 301, 302] else 'Upstream SearXNG: FAILED - SearXNG may not be running' }}"
+
+    - name: Generate configuration preview
+      ansible.builtin.template:
+        src: "oauth2-proxy.cfg.j2"
+        dest: "/tmp/oauth2-proxy.cfg.preview"
+        mode: "0600"
+
+    - name: Display configuration preview
+      ansible.builtin.command: cat /tmp/oauth2-proxy.cfg.preview
+      register: config_preview
+      changed_when: false
+
+    - name: Show configuration
+      ansible.builtin.debug:
+        msg: "{{ config_preview.stdout_lines }}"
+
+    - name: Clean up preview file
+      ansible.builtin.file:
+        path: /tmp/oauth2-proxy.cfg.preview
+        state: absent
+
+    - name: Configuration Summary
+      ansible.builtin.debug:
+        msg: |
+          OAuth2-Proxy Staging Summary
+          ============================
+          Host: {{ inventory_hostname }}
+          Port: {{ oauth2_proxy_port }}
+          OIDC Issuer: {{ oauth2_proxy_oidc_issuer_url }}
+          Redirect URL: {{ oauth2_proxy_redirect_url }}
+          Upstream: {{ oauth2_proxy_upstream_url }}
+          Cookie Domain: {{ oauth2_proxy_cookie_domain }}
+          Email Domains: {{ oauth2_proxy_email_domains | join(', ') }}
+          
+          OIDC Discovery: {{ 'OK' if oidc_discovery.status == 200 else 'FAILED' }}
+          Upstream Check: {{ 'OK' if upstream_check.status in [200, 301, 302] else 'FAILED' }}
+          
+          To deploy: ansible-playbook oauth2_proxy/deploy.yml