{"id":30020429,"url":"https://github.com/anthonyfoust/ai-stack-homelab","last_synced_at":"2026-04-09T01:32:25.999Z","repository":{"id":307498895,"uuid":"1029727890","full_name":"anthonyfoust/ai-stack-homelab","owner":"anthonyfoust","description":"Complete AI automation stack optimized for Mac Mini M4, but can work in multiple machine configurations. Features n8n workflows, Ollama with Llama 3.2, Open WebUI, LiteLLM proxy, and MCP integration. Production-ready with automated backups, security, and family-safe configuration for you to learn more about AI at home.","archived":false,"fork":false,"pushed_at":"2025-10-31T03:20:08.000Z","size":131,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-31T05:25:51.467Z","etag":null,"topics":["ai","automation","docker","docker-compose","family-safe","litellm","llama","local-ai","m4","mac-mini","mcp","n8n","ollama","personal-ai","webui"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/anthonyfoust.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-07-31T13:32:33.000Z","updated_at":"2025-10-31T03:19:14.000Z","dependencies_parsed_at":"2025-07-31T17:33:33.901Z","dependency_job_id":"c942cc90-8534-49ed-8482-d1ac405cde3d","html_url":"https://github.com/anthonyfoust/ai-stack-homelab","commit_stats":null,"previous_names":["anthonyfoust/ai-stack-homelab"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/anthonyfoust/ai-stack-homelab","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anthonyfoust%2Fai-stack-homelab","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anthonyfoust%2Fai-stack-homelab/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anthonyfoust%2Fai-stack-homelab/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anthonyfoust%2Fai-stack-homelab/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/anthonyfoust","download_url":"https://codeload.github.com/anthonyfoust/ai-stack-homelab/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/anthonyfoust%2Fai-stack-homelab/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31581864,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-08T14:31:17.711Z","status":"ssl_error","status_checked_at":"2026-04-08T14:31:17.202Z","response_time":54,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","automation","docker","docker-compose","family-safe","litellm","llama","local-ai","m4","mac-mini","mcp","n8n","ollama","personal-ai","webui"],"created_at":"2025-08-06T02:01:56.960Z","updated_at":"2026-04-09T01:32:25.975Z","avatar_url":"https://github.com/anthonyfoust.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AI Stack - Private AI Infrastructure\n\nComplete home lab AI environment featuring local AI models, workflow automation, chat interface, and AI integrations. Everything runs privately on your infrastructure with zero cloud dependencies.\n\n## Services Included\n\n- **PostgreSQL** with pgvector - Vector database for AI embeddings\n- **Ollama** - Local AI model server (llama3.2:3b, qwen2.5:7b-instruct, nomic-embed-text)\n- **Open WebUI** - ChatGPT-like web interface with filesystem access\n- **n8n** - Workflow automation platform\n- **LiteLLM** - Unified AI proxy for multiple providers\n- **SearXNG** - Privacy-respecting web search engine for RAG\n- **MCP Services** - Model Context Protocol integration (n8n-mcp, mcpo)\n- **Traefik** - Reverse proxy with automatic HTTPS\n- **Redis** - High-performance caching layer\n\n## Quick Start\n\n### Prerequisites\n\n- Docker Desktop installed and running\n- 16GB+ RAM recommended\n- 50GB+ free disk space\n- macOS, Linux, or Windows with WSL2\n\n### Installation\n\n**1. Clone or download this repository**\n```bash\ncd ~/\ngit clone \u003crepository-url\u003e ai-stack\ncd ai-stack\n```\n\n**2. Run setup**\n```bash\n./setup.sh\n```\n\nThe setup script will:\n- Verify Docker is running\n- Create `.env` from template\n- Prompt you to configure environment variables\n- Download all Docker images\n- Generate self-signed SSL certificates\n\n**3. Configure `/etc/hosts`**\n\nAdd these entries to access services via friendly names:\n```bash\nsudo nano /etc/hosts\n```\n\nAdd this line:\n```\n127.0.0.1 open-webui.local n8n.local litellm.local traefik.local ollama.local mcpo.local searxng.local\n```\n\n**4. Start the stack**\n```bash\ndocker compose up -d\n```\n\n**5. Download AI models (runs in background)**\n```bash\ndocker exec ollama sh /configs/ollama/init-models.sh\n```\n\nThis downloads ~7GB of models and takes 10-20 minutes depending on your connection.\n\n## Service Access\n\nOnce running, access services at:\n\n| Service | URL | Purpose |\n|---------|-----|---------|\n| **Open WebUI** | https://open-webui.local | AI chat interface (primary) |\n| **n8n** | https://n8n.local | Workflow automation |\n| **LiteLLM** | https://litellm.local | AI proxy management |\n| **SearXNG** | https://searxng.local | Web search engine |\n| **Traefik** | https://traefik.local | Reverse proxy dashboard |\n| **Ollama** | https://ollama.local | AI model API |\n| **MCPO** | https://mcpo.local | MCP orchestrator |\n\n**First-time setup:**\n- Open WebUI: First user becomes admin\n- n8n: First user becomes owner\n- Accept self-signed certificate warnings in browser\n\n## Configuration\n\n### Environment Variables\n\nAll configuration is in `.env` file. Key variables:\n\n**Database:**\n```bash\nPOSTGRES_USER=aistack\nPOSTGRES_PASSWORD=\u003csecure-password\u003e\nPOSTGRES_DB=aistack_db\n```\n\n**Security Keys** (generate with `openssl rand -hex 16`):\n```bash\nN8N_ENCRYPTION_KEY=\u003c32-char-hex\u003e\nOPEN_WEBUI_SECRET_KEY=\u003c32-char-hex\u003e\nLITELLM_MASTER_KEY=\u003csecure-key\u003e\n```\n\n**Host Filesystem Mounts** (Open WebUI access):\n```bash\nHOST_DOWNLOADS_PATH=/Users/YOUR_USERNAME/Downloads\nHOST_VIRIDAE_PATH=/Users/YOUR_USERNAME/Viridae Network\nHOST_DROPZONE_PATH=/Users/YOUR_USERNAME/Library/Mobile Documents/com~apple~CloudDocs/DropZone\nHOST_DOCSTORE_PATH=/Users/YOUR_USERNAME/Library/Mobile Documents/com~apple~CloudDocs/DocStore\n```\n\nUpdate `YOUR_USERNAME` with your actual username.\n\n### Resource Limits\n\nAdjust resource limits in `.env` based on your system:\n\n**For systems with 16-32GB RAM:**\n```bash\nOLLAMA_MEMORY_LIMIT=8G\nOLLAMA_MAX_MODELS=2\nN8N_MEMORY_LIMIT=2G\nPOSTGRES_MEMORY_LIMIT=2G\n```\n\n**For systems with 32GB+ RAM:**\n```bash\nOLLAMA_MEMORY_LIMIT=12G\nOLLAMA_MAX_MODELS=3\nN8N_MEMORY_LIMIT=3G\nPOSTGRES_MEMORY_LIMIT=4G\n```\n\n## Daily Operations\n\n### Starting and Stopping\n\n```bash\n# Start all services\ndocker compose up -d\n\n# Stop all services\ndocker compose stop\n\n# Stop and remove containers (data persists)\ndocker compose down\n\n# Stop and remove all data (DESTRUCTIVE)\ndocker compose down -v\n```\n\n### Viewing Logs\n\n```bash\n# All services\ndocker compose logs -f\n\n# Specific service\ndocker compose logs -f open-webui\ndocker compose logs -f ollama\ndocker compose logs -f postgresql\n\n# Last 100 lines\ndocker compose logs --tail=100\n```\n\n### Checking Service Status\n\n```bash\n# Service health\ndocker compose ps\n\n# Resource usage\ndocker stats\n\n# Verify models downloaded\ndocker exec ollama ollama list\n```\n\n### Restarting a Service\n\n```bash\n# Restart specific service\ndocker compose restart open-webui\n\n# Restart after config changes\ndocker compose up -d --force-recreate open-webui\n```\n\n## Open WebUI Features\n\n### Filesystem Access\n\nOpen WebUI has read-write access to your mounted directories. Files appear at:\n- `/mnt/host/downloads` - Your Downloads folder\n- `/mnt/host/viridae-network` - Viridae Network folder\n- `/mnt/host/dropzone` - iCloud DropZone\n- `/mnt/host/docstore` - iCloud DocStore\n\nUse these paths when referencing files in conversations.\n\n### Custom Branding\n\nPlace your logo files in `configs/open-webui/`:\n- `favicon.png` (32x32px)\n- `logo.png` (512x512px)\n- `logo-dark.png` (512x512px, optional)\n\nSee [configs/open-webui/BRANDING.md](configs/open-webui/BRANDING.md) for details.\n\n### AI Models\n\nOllama provides these models:\n- **llama3.2:3b** - Fast, balanced model for general use\n- **qwen2.5:7b-instruct** - Larger model for complex tasks\n- **nomic-embed-text** - For document embeddings and RAG\n\nSwitch models in Open WebUI interface. Models load on first use.\n\n## n8n Workflow Automation\n\n### Filesystem Access\n\nn8n has access to:\n- `/home/node/dropzone` - iCloud DropZone\n- `/home/node/docstore` - iCloud DocStore\n\nUse these paths in File nodes for reading/writing files.\n\n### Database Connection\n\nn8n uses PostgreSQL database `n8n_db`. All workflows persist automatically.\n\n### API Access\n\nn8n API available at `https://n8n.local/api/v1/`\n\nAPI key configured via `N8N_API_KEY` in `.env`\n\n## SearXNG Web Search\n\n### Privacy-Respecting Search\n\nSearXNG enables Open WebUI to search the internet and use real-time web data in AI responses.\n\n**Privacy Features**:\n- Self-hosted - runs entirely on your infrastructure\n- No tracking cookies\n- Anonymizes requests to search engines\n- No search history logging\n\n### How It Works\n\n```\nYour Question → Open WebUI → SearXNG → [Google, Bing, DuckDuckGo, etc.]\n                                 ↓\n                         Aggregated Results\n                                 ↓\n                   Ollama AI + Web Context → Response\n```\n\n### Usage in Open WebUI\n\n**Enable web search** in Open WebUI interface when asking questions that require current information:\n- \"What's the weather in Paris today?\"\n- \"What are the latest developments in AI?\"\n- \"Search for recent Docker best practices\"\n\n**Configuration**:\nAll settings in `.env`:\n```bash\nENABLE_RAG_WEB_SEARCH=true\nRAG_WEB_SEARCH_ENGINE=searxng\nRAG_WEB_SEARCH_RESULT_COUNT=5\n```\n\n### Accessing SearXNG Directly\n\nNavigate to https://searxng.local to:\n- Perform manual searches\n- Configure enabled search engines\n- Adjust preferences\n\nSee [configs/searxng/README.md](configs/searxng/README.md) for advanced configuration.\n\n## Troubleshooting\n\n### Services Won't Start\n\n**Check Docker:**\n```bash\ndocker info\n```\n\n**Check logs:**\n```bash\ndocker compose logs [service-name]\n```\n\n**Reset everything:**\n```bash\ndocker compose down\ndocker system prune -f\ndocker compose up -d\n```\n\n### Can't Access Services\n\n**Verify `/etc/hosts`:**\n```bash\ncat /etc/hosts | grep local\n```\n\n**Check Traefik is running:**\n```bash\ndocker compose ps traefik\n```\n\n**Test direct access (bypass Traefik):**\n```bash\ncurl http://localhost:8080  # Open WebUI direct\ncurl http://localhost:5678  # n8n direct\n```\n\n### Database Connection Errors\n\n**Check PostgreSQL:**\n```bash\ndocker compose logs postgresql\ndocker compose exec postgresql pg_isready\n```\n\n**Verify pgvector extension:**\n```bash\ndocker compose exec postgresql psql -U aistack -d openwebui_db -c \"SELECT * FROM pg_extension WHERE extname='vector';\"\n```\n\n### Ollama Models Not Working\n\n**Check model download:**\n```bash\ndocker exec ollama ollama list\n```\n\n**Download manually if missing:**\n```bash\ndocker exec ollama ollama pull llama3.2:3b\ndocker exec ollama ollama pull qwen2.5:7b-instruct\ndocker exec ollama ollama pull nomic-embed-text\n```\n\n**Check Ollama logs:**\n```bash\ndocker compose logs -f ollama\n```\n\n### Out of Memory\n\n**Check resource usage:**\n```bash\ndocker stats --no-stream\n```\n\n**Reduce model memory in `.env`:**\n```bash\nOLLAMA_MEMORY_LIMIT=8G\nOLLAMA_MAX_MODELS=2\n```\n\n**Unload unused models:**\n```bash\ndocker exec ollama ollama stop llama3.2:3b\n```\n\n### Filesystem Mount Permission Errors\n\n**Verify paths exist:**\n```bash\nls -la \"$HOME/Downloads\"\nls -la \"$HOME/Viridae Network\"\n```\n\n**Check container can access:**\n```bash\ndocker compose exec open-webui ls -la /mnt/host/\n```\n\n**Update `.env` with correct username:**\n```bash\nHOST_DOWNLOADS_PATH=/Users/YOUR_ACTUAL_USERNAME/Downloads\n```\n\nThen restart:\n```bash\ndocker compose up -d --force-recreate open-webui\n```\n\n## Security Considerations\n\n### Network Access\n\n- All services behind Traefik reverse proxy\n- Self-signed SSL certificates for local HTTPS\n- Services communicate via internal Docker network\n- Only Traefik exposes ports to host (80, 443, 8090)\n\n### Credentials\n\n- All passwords in `.env` file (git-ignored)\n- Use strong, unique passwords\n- Rotate API keys periodically\n- Never commit `.env` to version control\n\n### For Remote Access\n\n**Not currently configured**. To enable:\n\n1. Configure Let's Encrypt in Traefik\n2. Set up port forwarding on router (80, 443)\n3. Use dynamic DNS for your public IP\n4. Update Traefik to use Let's Encrypt resolver\n5. Consider adding authentication middleware\n\nSee [ARCHITECTURE.md](ARCHITECTURE.md) for details.\n\n## Updating\n\n### Update Docker Images\n\n```bash\n# Pull latest images\ndocker compose pull\n\n# Recreate containers\ndocker compose up -d --force-recreate\n\n# Clean old images\ndocker image prune -f\n```\n\n### Update AI Models\n\n```bash\n# Check for model updates\ndocker exec ollama ollama pull llama3.2:3b\ndocker exec ollama ollama pull qwen2.5:7b-instruct\n```\n\n### Update Configuration\n\n1. Edit `.env` with new values\n2. Restart affected services:\n```bash\ndocker compose up -d --force-recreate [service-name]\n```\n\n## Architecture\n\nSee [ARCHITECTURE.md](ARCHITECTURE.md) for:\n- Design decisions and rationale\n- Network architecture\n- Database schema\n- Service dependencies\n- Future extensibility\n\n## Performance Tips\n\n- Close unused applications while running AI workloads\n- Use smaller models (llama3.2:3b) for faster responses\n- Limit concurrent model usage with `OLLAMA_MAX_MODELS`\n- Monitor disk space - models and data can grow large\n- Restart Ollama periodically to free memory\n\n## Adding Monitoring\n\nStack is designed to easily add monitoring tools:\n\n**Prometheus + Grafana:**\n```yaml\n# Add to docker-compose.yml\nprometheus:\n  image: prom/prometheus\n  # ... configuration\n\ngrafana:\n  image: grafana/grafana\n  # ... configuration\n```\n\n**Portainer:**\n```yaml\nportainer:\n  image: portainer/portainer-ce\n  ports:\n    - \"9443:9443\"\n  volumes:\n    - /var/run/docker.sock:/var/run/docker.sock\n    - portainer_data:/data\n```\n\nAll services already expose metrics endpoints for Prometheus scraping.\n\n## Support\n\n**Check logs first:**\n```bash\ndocker compose logs -f [service-name]\n```\n\n**Verify configuration:**\n```bash\ndocker compose config\n```\n\n**Health check:**\n```bash\ndocker compose ps\ncurl -k https://open-webui.local/health\ncurl -k https://n8n.local/healthz\n```\n\n**Complete reset (nuclear option):**\n```bash\ndocker compose down -v\nrm -rf certs/\n./setup.sh\ndocker compose up -d\n```\n\n---\n\n**Your private AI infrastructure is ready.** Start by accessing https://open-webui.local and creating your admin account.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fanthonyfoust%2Fai-stack-homelab","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fanthonyfoust%2Fai-stack-homelab","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fanthonyfoust%2Fai-stack-homelab/lists"}