imbajin opened a new issue, #495:
URL: https://github.com/apache/hugegraph-doc/issues/495
## Goal
Track the remaining follow-up tasks to enable **Ask AI (Kapa.ai
integration)** for Apache HugeGraph documentation website following the OINK
site integration in #493 and #472.
This issue serves as a sub-issue of #469 to coordinate source-group
configuration, ASF Infra Content Security Policy (CSP) compliance, and privacy
boundary verification before turning on the feature flag in production.
---
## Background & Current State
- The frontend integration, UI layout, search-tail trigger, and same-origin
consent dialog have already been implemented and merged in #493.
- To ensure full compliance with Apache Software Foundation (ASF) privacy
policy and prevent unconsented third-party requests, the feature is currently
disabled by default in `hugo.yaml`:
```yaml
ai_search:
enabled: false
kapa:
website_id: "00000000-0000-0000-0000-000000000000"
source_group_id: ""
```
- Native documentation search operates independently without third-party
dependencies.
---
## Action Items / TODOs
### 1. Kapa AI Source Group Configuration
- [ ] Create and configure independent Kapa.ai Source Groups for English
(`EN`) and Chinese (`CN`) documentation spaces.
- [ ] Update `hugo.yaml` with the official Source Group IDs
(`ai_search.kapa.source_group_id` / `source_group_id_cn`).
- [ ] Verify locale isolation (e.g., Chinese queries retrieve Chinese docs;
English queries retrieve English docs).
- [ ] Validate answer accuracy, citations, and markdown rendering quality.
### 2. ASF Infra CSP & Privacy Compliance
- [ ] Confirm exact Kapa widget and bot-protection domains with ASF Infra
and VP Data Privacy:
- `kapa.ai`, `*.kapa.ai`
- `hcaptcha.com`, `*.hcaptcha.com`
- [ ] Add approved domains to the ASF Infra CSP whitelist
(`CSP_PROJECT_DOMAINS` or `.htaccess` CSP directives).
- [ ] Ensure privacy boundaries are strictly upheld:
- `data-consent-required` mode enabled.
- Zero third-party network requests or cookies before explicit user
consent in the dialog.
- Disabled analytics cookies and fingerprinting.
- Native search fallback if Kapa fails, times out, or user declines
consent.
### 3. Staging Smoke Test & Production Rollout
- [ ] Conduct end-to-end browser smoke test on staging environment
(`hugegraph-oink.staged.apache.org` or `hugegraph.staged.apache.org`).
- [ ] Verify timeout, cancellation (Escape / Cancel), retry behavior, and
mobile responsiveness.
- [ ] Submit a single-line PR flipping `ai_search.enabled: true` in
`hugo.yaml` once staging proof and ASF approval are confirmed.
---
## Related Apache Precedents & References
The following Apache projects provide valuable reference for Kapa
integration, privacy compliance, and CSP configuration:
- **Apache Fluss [PR #3760](https://github.com/apache/fluss/pull/3760)**:
Uses Kapa's `data-consent-required`, disables analytics cookies, and adds
Kapa/reCAPTCHA domains to ASF `.htaccess` CSP.
- **Apache ShenYu [PR
#1131](https://github.com/apache/shenyu-website/pull/1131)**: Documents
locale/dark-mode integration, disabled analytics cookies/fingerprinting, and
CSP entries for widget, proxy, and bot-protection domains.
- **Apache Iceberg [Issue
#13934](https://github.com/apache/iceberg/issues/13934)**: Tracks Kapa's Open
Source Program as a project-level adoption discussion.
- **Apache SkyWalking [Issue
#12407](https://github.com/apache/skywalking/issues/12407)**: Records the
removal of Kapa per ASF Policy team request, highlighting that production
approval must be explicitly verified and cannot be assumed solely from staging
availability.
- **Apache Fluss [Issue
#3206](https://github.com/apache/fluss/issues/3206)**: Reminder that deployed
widgets require real browser smoke tests across desktop and mobile.
---
## Follow-up Questions for ASF Infra / Privacy
1. Is the Kapa/hCaptcha integration allowed for testing on
`hugegraph-oink.staged.apache.org` prior to formal ASF policy approval?
2. If staging is allowed, which exact production domains and CSP directives
must be submitted to ASF Infra before enabling on `hugegraph.apache.org`?
3. Does Kapa require separate project-level approvals for dual English and
Chinese source groups?
---
## Coordination
- Parent Issue: #469 (`[Website] Track post-OINK improvements`)
- Related PR: #493 (`feat: complete OINK site integration`)
- Related PR: #472 (`[Feature] Introduce OINK modern theme with Hugo
multi-version support`)
- Deferred search issue: #471
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
