docs: add AI stack documentation to CLAUDE.md
Updated CLAUDE.md with comprehensive AI stack documentation: **Compose Include Pattern**: - Added ai stack to service list **Service Documentation (ai/compose.yaml)**: - ai_postgres: PostgreSQL 16 with pgvector extension - webui: Open WebUI at ai.pivoine.art with Claude integration - crawl4ai: Internal web scraping API for LLM content **Configuration Details**: - Claude API integration via Anthropic OpenAI-compatible endpoint - RAG support with pgvector for semantic search - Web search capability enabled - IONOS SMTP email configuration - Database: dedicated PostgreSQL instance (ai/openwebui) **Usage Instructions**: - Account creation and API key setup - Document upload for RAG conversations - n8n workflow automation integration - Mattermost notification capabilities **Integration Points**: - n8n for AI task automation - Mattermost for notifications - Crawl4AI for advanced scraping - Claude API as primary LLM **Future Enhancements**: - GPU server integration (IONOS A10 planned) - Additional AI models (Whisper, Stable Diffusion) - Enhanced RAG pipelines - Custom AI agents **Backup Plans**: - Updated count to 16 automated daily backups - Added ai-backup: 3 AM daily (postgres, webui, crawl4ai data) - Added netdata-backup: 10 AM daily (config data) - Retention: 7 daily, 4 weekly, 6 monthly, 2 yearly **Volume Management**: - Added ai_postgres_data, ai_webui_data, ai_crawl4ai_data - Added netdata_config **Environment Variables**: - AI_DB_PASSWORD: AI PostgreSQL password - AI_WEBUI_SECRET_KEY: Open WebUI session encryption - ANTHROPIC_API_KEY: Claude API key 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
74
CLAUDE.md
74
CLAUDE.md
@@ -25,6 +25,7 @@ Root `compose.yaml` uses Docker Compose's `include` directive to orchestrate mul
|
||||
- **kit**: Unified toolkit with Vert file converter and miniPaint image editor (path-routed)
|
||||
- **jelly**: Jellyfin media server with hardware transcoding
|
||||
- **drop**: PairDrop peer-to-peer file sharing
|
||||
- **ai**: AI infrastructure with Open WebUI, Crawl4AI, and pgvector (PostgreSQL)
|
||||
- **restic**: Backrest backup system with restic backend
|
||||
- **netdata**: Real-time infrastructure monitoring
|
||||
- **sablier**: Dynamic scaling plugin for Traefik
|
||||
@@ -429,6 +430,64 @@ PairDrop peer-to-peer file sharing service:
|
||||
|
||||
**Note**: PairDrop is stateless and doesn't require backups as no data is persisted. All transfers happen directly between devices.
|
||||
|
||||
### AI Stack (ai/compose.yaml)
|
||||
AI infrastructure with Open WebUI, Crawl4AI, and dedicated PostgreSQL with pgvector:
|
||||
- **ai_postgres**: PostgreSQL 16 with pgvector extension exposed internally
|
||||
- Dedicated database instance for AI/RAG workloads
|
||||
- pgvector extension for vector similarity search
|
||||
- scram-sha-256 authentication
|
||||
- Health check monitoring
|
||||
- Data persisted in `ai_postgres_data` volume
|
||||
|
||||
- **webui**: Open WebUI exposed at `ai.pivoine.art:8080`
|
||||
- ChatGPT-like interface for AI models
|
||||
- Claude API integration via Anthropic API (OpenAI-compatible endpoint)
|
||||
- PostgreSQL backend with vector storage (pgvector)
|
||||
- RAG (Retrieval-Augmented Generation) support with document upload
|
||||
- Web search capability for enhanced responses
|
||||
- SMTP email configuration via IONOS
|
||||
- User signup enabled
|
||||
- Data persisted in `ai_webui_data` volume
|
||||
|
||||
- **crawl4ai**: Crawl4AI web scraping service (internal API, no public access)
|
||||
- Optimized web scraper for LLM content preparation
|
||||
- Internal API on port 11235 (not exposed via Traefik)
|
||||
- Designed for integration with Open WebUI and n8n workflows
|
||||
- Data persisted in `ai_crawl4ai_data` volume
|
||||
|
||||
**Configuration**:
|
||||
- **Claude Integration**: Uses Anthropic API with OpenAI-compatible endpoint
|
||||
- **API Base URL**: `https://api.anthropic.com/v1`
|
||||
- **RAG Embedding**: OpenAI `text-embedding-3-small` model
|
||||
- **Vector Database**: pgvector for semantic search
|
||||
- **Web UI Name**: Pivoine AI
|
||||
|
||||
**Database Configuration**:
|
||||
- **User**: `ai`
|
||||
- **Database**: `openwebui`
|
||||
- **Connection**: `postgresql://ai:password@ai_postgres:5432/openwebui`
|
||||
|
||||
**Usage**:
|
||||
1. Access https://ai.pivoine.art to create an account
|
||||
2. Configure Claude API key in settings (already configured server-side)
|
||||
3. Upload documents for RAG-enhanced conversations
|
||||
4. Use web search feature for current information
|
||||
5. Integrate with n8n workflows for automation
|
||||
|
||||
**Integration Points**:
|
||||
- **n8n**: Workflow automation with AI tasks (scraping, RAG ingestion, webhooks)
|
||||
- **Mattermost**: Can send AI-generated notifications via webhooks
|
||||
- **Crawl4AI**: Internal API for advanced web scraping
|
||||
- **Claude API**: Primary LLM provider via Anthropic
|
||||
|
||||
**Future Enhancements**:
|
||||
- GPU server integration (IONOS A10 planned)
|
||||
- Additional AI models (Whisper, Stable Diffusion)
|
||||
- Enhanced RAG pipelines with specialized embeddings
|
||||
- Custom AI agents for specific tasks
|
||||
|
||||
**Note**: All AI volumes are backed up daily at 3 AM via Restic with 7 daily, 4 weekly, 6 monthly, and 2 yearly retention.
|
||||
|
||||
### Netdata (netdata/compose.yaml)
|
||||
Real-time infrastructure monitoring and alerting:
|
||||
- **netdata**: Netdata monitoring agent exposed at `netdata.pivoine.art:19999`
|
||||
@@ -471,7 +530,7 @@ Backrest backup system with restic backend:
|
||||
- Prune: Weekly (Sundays at 2 AM) - removes old snapshots per retention policy
|
||||
- Check: Weekly (Sundays at 3 AM) - verifies repository integrity
|
||||
|
||||
**Backup Plans** (11 automated daily backups):
|
||||
**Backup Plans** (16 automated daily backups):
|
||||
1. **postgres-backup** (2 AM daily)
|
||||
- Path: `/volumes/core_postgres_data`
|
||||
- Retention: 7 daily, 4 weekly, 6 monthly, 2 yearly
|
||||
@@ -528,6 +587,14 @@ Backrest backup system with restic backend:
|
||||
- Path: `/volumes/jelly_config`
|
||||
- Retention: 7 daily, 4 weekly, 6 monthly, 2 yearly
|
||||
|
||||
15. **netdata-backup** (10 AM daily)
|
||||
- Path: `/volumes/netdata_config`
|
||||
- Retention: 7 daily, 4 weekly, 3 monthly
|
||||
|
||||
16. **ai-backup** (3 AM daily)
|
||||
- Paths: `/volumes/ai_postgres_data`, `/volumes/ai_webui_data`, `/volumes/ai_crawl4ai_data`
|
||||
- Retention: 7 daily, 4 weekly, 6 monthly, 2 yearly
|
||||
|
||||
**Volume Mounting**:
|
||||
All Docker volumes are mounted read-only to `/volumes/` with prefixed names (e.g., `backup_core_postgres_data`) to avoid naming conflicts with other compose stacks.
|
||||
|
||||
@@ -553,6 +620,9 @@ Key variables defined in `arty.yml` and overridden in `.env`:
|
||||
- `TRACK_APP_SECRET`: Umami analytics secret
|
||||
- `MATTERMOST_WEBHOOK_URL`: Incoming webhook URL for infrastructure notifications (stored in `.env` only)
|
||||
- `WATCHTOWER_NOTIFICATION_URL`: Shoutrrr format URL for container update notifications
|
||||
- `AI_DB_PASSWORD`: AI PostgreSQL database password
|
||||
- `AI_WEBUI_SECRET_KEY`: Open WebUI secret key for session encryption
|
||||
- `ANTHROPIC_API_KEY`: Claude API key for AI functionality
|
||||
|
||||
## Volume Management
|
||||
|
||||
@@ -568,6 +638,8 @@ Each service uses named volumes prefixed with project name:
|
||||
- `vault_data`: Vaultwarden password vault (SQLite database)
|
||||
- `joplin_data`: Joplin note-taking data
|
||||
- `jelly_config`: Jellyfin media server configuration
|
||||
- `ai_postgres_data`, `ai_webui_data`, `ai_crawl4ai_data`: AI stack databases and application data
|
||||
- `netdata_config`: Netdata monitoring configuration
|
||||
- `restic_data`, `restic_config`, `restic_cache`, `restic_tmp`: Backrest backup system
|
||||
- `proxy_letsencrypt_data`: SSL certificates
|
||||
|
||||
|
||||
Reference in New Issue
Block a user