Janady13/seo-sidecar / README.md

1# SEO Sidecar 2 3> Inject up-to-date Schema.org JSON-LD into your nginx-served sites with **zero crons, zero site file changes, always fresh.** A FastAPI sidecar + nginx SSI integration that lets an upstream AI/automation push schemas to your hosting machine in real time. 4 5[](LICENSE) 6[](https://www.python.org/downloads/) 7[](https://fastapi.tiangolo.com/) 8[](https://nginx.org/) 9 10## Why this exists 11 12If you host static or server-rendered HTML through nginx and want **fresh, dynamic Schema.org JSON-LD** in every page's `<head>` without redeploying the site every time a schema changes, you have three bad options: 13 141. **Edit the HTML files** every time → site redeployment per schema change 152. **Cron job that rebuilds + redeploys** → stale between cron runs, slow propagation 163. **Server-side rendering** → couples schema generation to your rendering tier 17 18SEO Sidecar is the fourth option. An upstream process (your AI, your CMS, your trend analyzer, whatever) pushes JSON-LD to a tiny FastAPI service on your nginx host. nginx pulls the schema in via SSI on every page load. Schema updates take effect **instantly** with no site redeployment, no cron lag, no rendering coupling. 19 20Built in production for [ThatDevPro](https://www.thatdevpro.com)'s network of nine client websites. 21 22## Architecture 23 24``` 25<UPSTREAM> (your AI publishing source) 26 │ 27 │ Push over Tailscale (event-driven) 28 │ POST /update/{site} with JSON-LD 29 │ 30 ▼ 31┌──────────────────────────────────────────┐ 32│ <SIDECAR_HOST> (your nginx host) │ 33│ │ 34│ seo-sidecar (localhost:9090) │ 35│ ├── SQLite: /var/lib/seo-sidecar/ │ 36│ ├── Receives pushes from upstream │ 37│ ├── Serves schemas to nginx │ 38│ └── Keeps history + versioning │ 39│ │ 40│ nginx │ 41│ ├── SSI include on every page load │ 42│ ├── Fetches from localhost:9090 │ 43│ ├── 5min proxy_cache (configurable) │ 44│ └── 1s timeout (pages never stall) │ 45│ │ 46│ 9 hosted sites │ 47│ └── Each gets dynamic JSON-LD in <head> │ 48└──────────────────────────────────────────┘ 49``` 50 51## How It Works 52 531. **Your upstream service decides** a schema needs updating (trend shift, new FAQ, competitor gap) 542. **Upstream pushes** the new JSON-LD to `http://<SIDECAR_HOST>:9090/update/{site}` over Tailscale 553. **Sidecar stores** it in SQLite with version history 564. **nginx SSI** fetches from `localhost:9090/schema/{site}` on every HTML page load 575. **Schema appears** in the `<head>` of the site — search engines and AI crawlers see it immediately 58 59No cron jobs. No file writes. No site deployments. Upstream controls schema state remotely. 60 61## Files 62 63| File | Where It Goes | Purpose | 64|------|--------------|---------| 65| `sidecar.py` | `/opt/seo-sidecar/` on the sidecar host | FastAPI service — receives pushes, serves to nginx | 66| `nginx-seo-sidecar.conf` | `/etc/nginx/conf.d/` on the sidecar host | Upstream + hostname map | 67| `seo-inject.conf` | `/etc/nginx/snippets/` on the sidecar host | Drop-in include for server blocks | 68| `megamind_push.py` | upstream nodes | CLI push client | 69| `seo_client.go` | Go push client | Go push client for integration | 70| `seo-sidecar.service` | `/etc/systemd/system/` on the sidecar host | systemd unit | 71| `deploy-sidecar.sh` | Run once on the sidecar host | Full automated deployment | 72 73## Deploy on the sidecar host 74 75```bash 76# Copy files to your sidecar host 77scp -r seo-sidecar/ <YOUR_SERVER>:/tmp/seo-sidecar/ 78 79# SSH in and deploy 80ssh <YOUR_SERVER> 81cd /tmp/seo-sidecar 82sudo bash deploy-sidecar.sh 83``` 84 85Then add one line to each nginx server block: 86```nginx 87include /etc/nginx/snippets/seo-inject.conf; 88``` 89 90Reload nginx: 91```bash 92nginx -t && systemctl reload nginx 93``` 94 95## Push from your upstream 96 97```bash 98# Push single site 99python megamind_push.py push thatdeveloperguy 100 101# Push all 9 sites 102python megamind_push.py push-all 103 104# Bulk push (single HTTP request) 105python megamind_push.py push-bulk 106 107# Check what's live 108python megamind_push.py status 109 110# View version history 111python megamind_push.py history thatdeveloperguy 112``` 113 114Or from Go: 115```go 116client := seo.NewClient("http://<SIDECAR_HOST>:9090", "your-token") 117client.Push("thatdeveloperguy", jsonldString) 118``` 119 120## API Endpoints 121 122### Push (MEGAMIND → Sidecar) 123- `POST /update/{site}` — Push schema for one site 124- `POST /update-bulk` — Push schemas for multiple sites 125- `DELETE /schema/{site}` — Remove a schema 126 127### Serve (nginx → Sidecar) 128- `GET /schema/{site}` — Returns `<script type="application/ld+json">` HTML 129 130### Monitor 131- `GET /status` — All sites, versions, freshness 132- `GET /history/{site}` — Version history 133 134## Config 135 136Set in `/etc/systemd/system/seo-sidecar.service`: 137 138| Env Var | Default | Description | 139|---------|---------|-------------| 140| `SEO_DB_PATH` | `/var/lib/seo-sidecar/schemas.db` | SQLite database location | 141| `SEO_AUTH_TOKEN` | `CHANGE_ME_BEFORE_DEPLOY` | Bearer token for push auth | 142| `SEO_HOST` | `127.0.0.1` | Listen address (keep localhost) | 143| `SEO_PORT` | `9090` | Listen port | 144 145## Adding New Sites 146 1471. Add the hostname mapping in `nginx-seo-sidecar.conf` (the `map` block) 1482. Add `include /etc/nginx/snippets/seo-inject.conf;` to the new site's server block 1493. Push a schema: `python megamind_push.py push newsite` 150 151That's it. No other config changes. 152 153## Companion tools 154 155- [aio-surfaces](https://github.com/Janady13/aio-surfaces) — MIT-licensed Python toolkit that generates the four AI-citation surfaces (llms.txt, aeo.json, entity.json, brand.json) from a single site config. Pairs naturally with this — generate schemas with `aio-surfaces`, push them with this sidecar. 156- [llms.txt generator](https://huggingface.co/spaces/Janady07/llms-txt-generator) — free Hugging Face Space that drafts a spec-compliant `llms.txt` from any homepage URL. 157 158## License 159 160MIT © 2026 Joseph W. Anady ([ThatDevPro](https://www.thatdevpro.com)). See [LICENSE](LICENSE). 161 162--- 163 164Built and used in production by **[ThatDevPro](https://www.thatdevpro.com)** — SDVOSB-certified veteran-owned web + AI engineering studio. Cassville, Missouri. 165