-
----
+A production-ready, self-hosted Docker Compose stack for Hermes Agents β memory, search, browser automation, and file sync, all optimized for CPU-based hardware.
-## β¨ Features
+[](https://github.com/OneByJorah/StackDeploy)
+[](LICENSE)
+[](https://javascript.com)
+[](https://github.com/OneByJorah)
-- **One Command Deploy** β Single bootstrap script for full stack
-- **CPU Only** β Optimized for consumer hardware (GPU optional for Ollama)
-- **Privacy-Focused** β Self-hosted search with SearXNG, no third-party APIs
-- **Long-Term Memory** β Honcho API with PostgreSQL + pgvector + Redis
-- **Vector Database** β Qdrant for RAG and semantic search
-- **Obsidian Integration** β CouchDB LiveSync vault with web viewer
-- **P2P File Sync** β Syncthing between server and laptop
-- **Browser Automation** β Selenium standalone Chrome for agent web tasks
-- **Local LLM** β Ollama for offline inference
-- **Tailscale Ready** β All services exposed on a single Tailscale IP
+
---
-## π Services
-
-| Service | Port | Health Check | Purpose |
-|---------|------|--------------|---------|
-| **SearXNG** | 8080 | `wget --spider http://localhost:8080/` | Privacy-respecting metasearch |
-| **Qdrant** | 6333 | `bash /dev/tcp` port probe | Vector database for embeddings |
-| **Honcho API** | 8000 | `python3 urllib GET /health` | Long-term memory for agents |
-| **Honcho DB** | 5432 | `pg_isready` | PostgreSQL + pgvector |
-| **Honcho Redis** | 6379 | `redis-cli ping` | Cache layer |
-| **CouchDB** | 5984 | `curl GET /` (allows 401) | Obsidian LiveSync backend |
-| **Obsidian Viewer** | 8083 | `curl -f http://localhost:80/` | Web vault UI via Caddy |
-| **Syncthing** | 8384 | `python3 urllib GET /` | P2P file sync (laptop β server) |
-| **Selenium Chrome** | 4444 | `curl -f /status` | Browser automation |
-| **Ollama** | 11434 | `bash /dev/tcp` port probe | Local LLM inference |
-
----
+## Why This Exists
-## π Quick Start
+Standing up the full Hermes agent infrastructure means wiring together a dozen services β database, vector store, search, browser automation, file sync β each with its own config. StackDeploy bundles them into a single `docker-compose` stack tuned for consumer CPU hardware, with optional GPU support for Ollama. One config, one `up` command, and your Hermes agents have everything they need.
-### Prerequisites
+## Services
-- Docker & docker-compose (v1 or v2)
-- Tailscale (recommended, for multi-machine access)
-- 8GB+ RAM, 50GB+ disk
+| Service | Port | Purpose |
+|---|---|---|
+| **SearXNG** | β | Private meta-search engine |
+| **Qdrant** | β | Vector database for RAG and memory |
+| **Ollama** | β | Local LLM inference (GPU optional) |
+| **Honcho API** | 8000 | Agent memory and state management |
+| **PostgreSQL** | 5432 | Relational data with pgvector |
+| **Redis** | 6379 | Caching and message broker |
+| **CouchDB** | 5984 | Obsidian LiveSync database |
+| **Obsidian Web** | 8083 | In-browser Obsidian access |
+| **Syncthing** | 8384 | Peer-to-peer file synchronization |
+| **Selenium Chrome** | 4444 | Headless browser for web agents |
-### Setup
+## Quick Start
```bash
git clone https://github.com/OneByJorah/StackDeploy.git
cd StackDeploy
-
-# 1. Configure environment
-cp .env.example .env
-# Edit .env β set SERVER_IP, HONCHO_DB_PASSWORD, COUCHDB passwords
-
-# 2. Optional: configure Honcho LLM provider
-cp .env.honcho.example .env.honcho
-# Edit .env.honcho β set your OpenAI-compatible API keys
-
-# 3. Start the stack
-docker-compose up -d
-```
-
-### First-time Honcho Setup
-
-Honcho requires database schema migrations on first run:
-
-```bash
-docker run --rm \
- --network stackdeploy-backend \
- -e DB_CONNECTION_URI=postgresql+psycopg://honcho:YOUR_PASSWORD@honcho-db:5432/honcho \
- --entrypoint alembic \
- ghcr.io/plastic-labs/honcho:latest upgrade head
+cp .env.example .env # set server IP, database passwords, etc.
+docker compose up -d
```
-Then restart the Honcho API container:
-
-```bash
-docker-compose stop honcho-api
-docker-compose rm -f honcho-api
-docker-compose up -d honcho-api
-```
-
-### Health Check
-
-```bash
-# Check all services
-docker-compose ps
-
-# Verify Honcho specifically
-curl -s http://localhost:8000/health
-# β {"status":"ok"}
-```
-
----
-
-## βοΈ Healthcheck Notes
-
-Many container images don't ship `curl`. The stack uses the tool each image actually has:
-
-| Image | Available Tool | Healthcheck Method |
-|-------|---------------|--------------------|
-| searxng/searxng | `wget` | `wget --spider -q http://localhost:8080/` |
-| qdrant/qdrant | `bash` + `timeout` | `bash -c 'cat < /dev/null > /dev/tcp/localhost/6333'` |
-| ghcr.io/plastic-labs/honcho | `python3` | `python3 -c "urllib.request.urlopen(...)"` |
-| couchdb:3.4 | `curl` | `curl -s -o /dev/null http://127.0.0.1:5984/` (no `-f` β allows 401) |
-| caddy:2-alpine | `curl` | `curl -f http://localhost:80/` |
-| syncthing/syncthing | `python3` | `python3 -c "urllib.request.urlopen(...)"` |
-| selenium/standalone-chrome | `curl` | `curl -f http://localhost:4444/status` |
-| ollama/ollama | `bash` + `timeout` | `bash -c 'cat < /dev/null > /dev/tcp/localhost/11434'` |
-
-If you see `(unhealthy)` in `docker ps`, check the healthcheck method matches your image. The `bash /dev/tcp` pattern works on any image with bash and `timeout` β no extra packages needed.
-
----
-
-## π§ Service Management
-
-```bash
-# Start all
-docker-compose up -d
-
-# Stop all
-docker-compose down
-
-# View logs (all or specific)
-docker-compose logs -f
-docker-compose logs -f honcho-api
-
-# Restart single service
-docker-compose restart honcho-api
-
-# Health check
-docker-compose ps
-```
-
----
-
-## π Environment Variables
-
-All secrets in `.env` (never committed β it's in `.gitignore`). See `.env.example` for the full list.
-
-| Variable | Purpose | Required |
-|----------|---------|----------|
-| `SERVER_IP` | Your Tailscale/local IP for service URLs | Yes |
-| `HONCHO_DB_PASSWORD` | PostgreSQL password for Honcho | Yes |
-| `HONCHO_TOKEN` | Honcho API auth token | Yes |
-| `COUCHDB_ADMIN_USER` | CouchDB admin username | Yes |
-| `COUCHDB_ADMIN_PASSWORD` | CouchDB admin password | Yes |
-| `COUCHDB_SYNC_USER` | CouchDB sync user for Obsidian | Yes |
-| `COUCHDB_SYNC_PASSWORD` | CouchDB sync password | Yes |
-| `OBSIDIAN_VAULT_PATH` | Host path for Hermes agent notes | Optional |
-
-### Honcho LLM Provider (`.env.honcho`)
-
-Honcho needs an OpenAI-compatible LLM provider for its embedding/LLM features. Copy `.env.honcho.example` to `.env.honcho` and configure:
-
-| Variable | Purpose | Example |
-|----------|---------|---------|
-| `LLM_VLLM_API_KEY` | Primary LLM API key | `sk-or-v1-...` |
-| `LLM_VLLM_BASE_URL` | Primary LLM base URL | `https://openrouter.ai/api/v1` |
-| `LLM_EMBEDDING_API_KEY` | Embeddings API key | `sk-or-v1-...` |
-| `LLM_EMBEDDING_BASE_URL` | Embeddings base URL | `https://openrouter.ai/api/v1` |
-| `LLM_EMBEDDING_MODEL` | Embedding model | `openai/text-embedding-3-small` |
-
----
-
-## π Hermes Agent Integration
-
-The entire stack is designed to be consumed by Hermes agents. Configure your agent's provider settings to point at the Tailscale IP where StackDeploy runs.
-
-### Agent configuration
-
-| Service | URL Pattern | Hermes Provider |
-|---------|-------------|-----------------|
-| Honcho | `http://YOUR_IP:8000` | `custom` memory provider |
-| SearXNG | `http://YOUR_IP:8080` | `custom` search provider |
-| Qdrant | `http://YOUR_IP:6333` | `custom` vector store |
-| Ollama | `http://YOUR_IP:11434` | `ollama` provider |
-| Obsidian | `http://YOUR_IP:8083` | Web vault viewer |
-| CouchDB | `http://YOUR_IP:5984` | LiveSync sync backend |
-| Syncthing | `http://YOUR_IP:8384` | File sync UI |
-| Selenium | `http://YOUR_IP:4444` | Browser automation |
-
----
+Prerequisites: Docker, Docker Compose, Tailscale, 8GB+ RAM, 50GB+ disk.
## Architecture
```
-ββββββββββββββββββββββββββββββββββββββββββββββββββββββ
-β TAILSCALE NETWORK β
-β Single IP exposes all ports β
-ββββββββββββββββββββββββββββββββββββββββββββββββββββββ
- β
- βΌ
-ββββββββββββββββββββββββββββββββββββββββββββββββββββββ
-β STACKDEPLOY β
-β β
-β SEARCH MEMORY STORAGE β
-β SearXNG Honcho + PG Qdrant β
-β (8080) + Redis (8000) (6333) β
-β β
-β NOTES FILE SYNC BROWSER LOCAL LLM β
-β CouchDB Syncthing Selenium Ollama β
-β (5984/8083) (8384) (4444) (11434) β
-ββββββββββββββββββββββββββββββββββββββββββββββββββββββ
+ββββββββββββββββββββββββββββββββββββββββββββ
+β Tailscale Mesh β
+β (all services on a single Tailscale IP)β
+ββββββββ¬βββββββ¬βββββββ¬βββββββ¬βββββββ¬βββββββ
+ β β β β β
+ βΌ βΌ βΌ βΌ βΌ βΌ
+ ββββββ ββββββ ββββββ ββββββ ββββββ ββββββ
+ βLLM β βVec β βMem β βSyncβ βWeb β βSrchβ
+ βOll β βQdr β βHon β βSyn β βObs β βSxNGβ
+ ββββββ ββββββ ββββββ ββββββ ββββββ ββββββ
```
-**Data Flow:**
-- Hermes Agent β Local services (search, memory, browser) β Optional upstream LLM via Hermes config
-- All services communicate over Docker internal network
-- Single Tailscale IP exposes everything via direct ports
+## Documentation
----
-
-## Project Structure
-
-```
-StackDeploy/
-βββ docker-compose.yml # Main compose file β all services
-βββ .env.example # Environment variable template
-βββ .env.honcho.example # Honcho LLM provider config template
-βββ bootstrap.sh # One-command deploy script
-βββ searxng/ # SearXNG configuration
-β βββ settings.yml
-βββ honcho/
-β βββ config.toml # Honcho API config
-β βββ couchdb-init.sh # CouchDB user initialization
-βββ obsidian/
-β βββ Caddyfile # Caddy reverse proxy config
-β βββ index.html # Vault viewer HTML
-β βββ vault/ # Markdown note vault
-β βββ Welcome.md
-βββ syncthing/
- βββ config/ # Syncthing device configuration
-```
+| Doc | Description |
+|---|---|
+| [Getting Started](docs/start.md) | Prerequisites and first deployment |
+| [Service Configuration](docs/services.md) | Tuning each service for your hardware |
+| [Tailscale Setup](docs/tailscale.md) | Networking all services on your mesh VPN |
---
-## π License
-
-MIT
-
----
+## License
-## Security
+MIT Β© JorahOne, LLC β see [LICENSE](LICENSE)
-- **No secrets in git** β `.env`, `.env.honcho` in `.gitignore`; `.env.example` has placeholders
-- **Network isolation** β Internal Docker network (`stackdeploy-backend`) for DB/cache; ports explicitly mapped
-- **Tailscale** β All inter-host traffic encrypted; no public ports needed
-- **Read-only mounts** β Config files mounted `:ro` where possible
-- **Health checks** β Every service auto-reports status to Docker
\ No newline at end of file
+
- 
- 
- 
-