# Design: Add SearxNG service to homelab network

## Phase Contract

Allowed reads:
- `tickets/active/2026-06-06-add-searxng-service.md`
- `tickets/artifacts/2026-06-06-add-searxng-service/00-context.md`

Will write:
- `tickets/artifacts/2026-06-06-add-searxng-service/03-design.md`

## User Judgment Questions

1. Where should SearxNG run: dedicated VM, existing Docker host, or another target?
2. What internal hostname should it use?
3. Who should be allowed to access it: Pi only, LAN users, VPN users, or selected devices?

## Current State

Pi has no dedicated web search/browsing tool. A broader safe browsing ticket exists, but it should not integrate arbitrary web content until a prescan/guard pipeline is implemented.

## Desired End State

A private SearxNG service is available on the homelab network as a general search endpoint for the user and internal webapps. Pi can later query this service for search result metadata, while page fetching remains handled by a separate safe fetch/prescan pipeline.

## Patterns / Constraints to Follow

- LAN/VPN-only access by default.
- No public exposure without separate review.
- Prefer dedicated VM/container isolation.
- Use least privilege.
- Document service ownership, ports, restart/update procedures, and rollback.
- Log operational changes.

## Design Decisions

1. **Decision**: Use SearxNG as a general private search service for the user and internal webapps.
2. **Decision**: For Pi/assistant integration, start with SearxNG as search metadata provider only — reduces prompt-injection exposure because result snippets are lower-risk than full pages and can still be treated as untrusted.
3. **Decision**: Keep page fetch separate from search — allows prescan/quarantine controls before LLM exposure.
4. **Decision**: Default to internal-only access — avoids exposing a public metasearch instance that could be abused or fingerprinted.
5. **Decision**: Prefer Docker Compose or a small dedicated VM/container — makes rollback and updates simpler.

## Not Doing

- No authenticated browsing.
- No browser cookies or saved profiles.
- No JavaScript/headless browser execution.
- No automatic action based on web content.

## Risks

- Public exposure could attract abuse or rate-limiting from upstream search engines.
- Misconfiguration could leak queries or expose service externally.
- Search snippets can still contain prompt-injection attempts and should be labeled untrusted.
- Upstream engines may block or rate-limit requests depending on configuration.

## Acceptance Criteria

- Target and access policy are approved.
- Service is deployed and reachable at the internal URL.
- Search is verified.
- Runbook and rollback notes exist.
- Change log is updated after deployment.