41c676a78e
Enterprise Features: - Hosted mode with remote sync for team pattern aggregation - Community sharing with privacy-preserving anonymization - LLM-based semantic claim extraction with Gemini integration - Pattern learning with promotion to declarative extractors - High-entropy secrets extractor with configurable thresholds - Auth bypass and insecure cookies extractors Module Refactoring: - Split oversized files to comply with 500-line limit - Config split: types/core.rs, types/extractors.rs, types/hosted.rs, etc. - Handlers split: scan.rs, policy.rs, report.rs modules - Extractors split: declarative/, high_entropy_secrets/, insecure_cookies/ - Learning split: store modules with metrics and persistence SDK & Ontology: - stemedb-ontology SDK with fluent builders and StemeDB client - Pharma domain extractors for FDA Orange Book data - Consumer health UAT test infrastructure Code Quality: - Fixed clippy warnings (needless_borrows_for_generic_args) - Added KVStore trait imports where needed - Fixed utoipa path re-exports for OpenAPI docs Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
173 lines
4.6 KiB
Markdown
173 lines
4.6 KiB
Markdown
# Configure Aphoria Hosted Mode
|
|
|
|
**When to use:** Setting up Aphoria for team-wide observation aggregation via a central StemeDB server.
|
|
|
|
## Prerequisites
|
|
|
|
- Aphoria installed (`cargo install --path applications/aphoria`)
|
|
- A running StemeDB server (for the team)
|
|
- Network access to the server
|
|
|
|
## Quick Start
|
|
|
|
```toml
|
|
# aphoria.toml
|
|
[hosted]
|
|
url = "https://episteme.acme.corp"
|
|
```
|
|
|
|
That's it. Observations now sync automatically on every scan.
|
|
|
|
## Architecture
|
|
|
|
```
|
|
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
|
|
│ Developer A │ │ Developer B │ │ Developer C │
|
|
│ aphoria scan │ │ aphoria scan │ │ aphoria scan │
|
|
└──────┬───────┘ └──────┬───────┘ └──────┬───────┘
|
|
│ │ │
|
|
└─────────────────┼─────────────────┘
|
|
▼
|
|
┌─────────────────────┐
|
|
│ Team StemeDB Server │
|
|
│ POST /v1/aphoria/ │
|
|
│ observations │
|
|
└─────────────────────┘
|
|
```
|
|
|
|
## Configuration Options
|
|
|
|
### Minimal (recommended for most teams)
|
|
|
|
```toml
|
|
[project]
|
|
name = "billing-service"
|
|
|
|
[hosted]
|
|
url = "https://episteme.acme.corp"
|
|
```
|
|
|
|
### Full Configuration
|
|
|
|
```toml
|
|
[project]
|
|
name = "billing-service"
|
|
|
|
[hosted]
|
|
url = "https://episteme.acme.corp" # Required: enables hosted mode
|
|
project_id = "billing-api" # Optional: defaults to [project.name]
|
|
team_id = "platform-team" # Optional: for multi-team servers
|
|
sync_mode = "remote-only" # "remote-only" | "local-and-remote"
|
|
offline_fallback = "skip" # "skip" | "fail" | "queue"
|
|
api_key_env = "APHORIA_API_KEY" # Env var containing auth token
|
|
max_retries = 3 # Retry attempts on failure
|
|
retry_delay_ms = 1000 # Delay between retries
|
|
```
|
|
|
|
## Sync Modes
|
|
|
|
| Mode | Description | When to Use |
|
|
|------|-------------|-------------|
|
|
| `remote-only` | Only push to server, no local storage | Single source of truth (default) |
|
|
| `local-and-remote` | Store locally AND push to server | Need local history for debugging |
|
|
|
|
## Offline Handling
|
|
|
|
| Mode | Behavior | When to Use |
|
|
|------|----------|-------------|
|
|
| `skip` | Warn and continue scan | Don't block developers (default) |
|
|
| `fail` | Abort scan with error | CI/CD where sync is mandatory |
|
|
| `queue` | Queue for later (not implemented) | Future offline support |
|
|
|
|
## Authentication
|
|
|
|
If your server requires authentication:
|
|
|
|
```bash
|
|
# Set the API key
|
|
export APHORIA_API_KEY="your-secret-token"
|
|
```
|
|
|
|
```toml
|
|
[hosted]
|
|
url = "https://episteme.acme.corp"
|
|
api_key_env = "APHORIA_API_KEY" # Reads from this env var
|
|
```
|
|
|
|
The client sends `Authorization: Bearer <token>` header.
|
|
|
|
## CI/CD Integration
|
|
|
|
### GitHub Actions
|
|
|
|
```yaml
|
|
- name: Aphoria Scan
|
|
env:
|
|
APHORIA_API_KEY: ${{ secrets.APHORIA_API_KEY }}
|
|
run: aphoria scan --staged --exit-code
|
|
```
|
|
|
|
### Pre-commit Hook
|
|
|
|
```bash
|
|
#!/bin/sh
|
|
# .git/hooks/pre-commit
|
|
aphoria scan --staged --exit-code
|
|
```
|
|
|
|
With hosted mode configured, observations sync automatically.
|
|
|
|
## Verifying Setup
|
|
|
|
```bash
|
|
# Check config is loaded
|
|
aphoria status
|
|
|
|
# Test with verbose output
|
|
RUST_LOG=aphoria=debug aphoria scan --persist --sync
|
|
|
|
# Expected log: "Pushed N observations to hosted server"
|
|
```
|
|
|
|
## Server Setup
|
|
|
|
Start a StemeDB server:
|
|
|
|
```bash
|
|
# Local testing
|
|
cargo run -p stemedb-api -- --bind 127.0.0.1:18180
|
|
|
|
# Production (with persistence)
|
|
stemedb-api --bind 0.0.0.0:18180 --data-dir /var/lib/stemedb
|
|
```
|
|
|
|
The server exposes `POST /v1/aphoria/observations` for receiving observations.
|
|
|
|
## Troubleshooting
|
|
|
|
### "Hosted sync failed, continuing"
|
|
|
|
Server is unreachable. Check:
|
|
- URL is correct
|
|
- Server is running
|
|
- Network/firewall allows connection
|
|
|
|
### "Failed to sync to hosted server" (error)
|
|
|
|
You have `offline_fallback = "fail"`. Either:
|
|
- Fix the connection issue
|
|
- Change to `offline_fallback = "skip"` temporarily
|
|
|
|
### Observations not appearing on server
|
|
|
|
Check:
|
|
1. `url` is set in `[hosted]` section
|
|
2. Scan finds novel claims (no authority conflicts)
|
|
3. Server logs show incoming requests
|
|
|
|
## Related
|
|
|
|
- [Aphoria Roadmap](../../../applications/aphoria/roadmap.md) - Phase 4E details
|
|
- [ai-lookup: Aphoria Config](../../../ai-lookup/features/aphoria-config.md) - Config reference
|
|
- [API Endpoints Guide](../backend/api-endpoints.md) - Adding new endpoints
|