{"id":50417462,"url":"https://github.com/Janady13/seo-sidecar","last_synced_at":"2026-06-16T23:00:39.473Z","repository":{"id":360343598,"uuid":"1247952650","full_name":"Janady13/seo-sidecar","owner":"Janady13","description":"Inject up-to-date Schema.org JSON-LD into nginx-served sites with zero crons, zero file changes, always fresh. FastAPI sidecar + nginx SSI integration.","archived":false,"fork":false,"pushed_at":"2026-05-26T01:54:36.000Z","size":71,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-26T03:29:54.800Z","etag":null,"topics":["aeo","ai-seo","fastapi","go","jsonld","nginx","nginx-ssi","python","schema-org","seo","sidecar"],"latest_commit_sha":null,"homepage":"https://www.thatdevpro.com/","language":"Go","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/Janady13.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","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},"funding":{"github":["Janady13"],"custom":["https://www.thatdevpro.com/","https://thatdeveloperguy.com/","https://feedthejoe.com/joseph/"]}},"created_at":"2026-05-24T02:03:18.000Z","updated_at":"2026-05-26T01:51:35.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Janady13/seo-sidecar","commit_stats":null,"previous_names":["janady13/seo-sidecar"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/Janady13/seo-sidecar","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Janady13%2Fseo-sidecar","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Janady13%2Fseo-sidecar/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Janady13%2Fseo-sidecar/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Janady13%2Fseo-sidecar/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Janady13","download_url":"https://codeload.github.com/Janady13/seo-sidecar/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Janady13%2Fseo-sidecar/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34426745,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-16T02:00:06.860Z","response_time":126,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["aeo","ai-seo","fastapi","go","jsonld","nginx","nginx-ssi","python","schema-org","seo","sidecar"],"created_at":"2026-05-31T07:00:23.427Z","updated_at":"2026-06-16T23:00:39.468Z","avatar_url":"https://github.com/Janady13.png","language":"Go","funding_links":["https://github.com/sponsors/Janady13","https://www.thatdevpro.com/","https://thatdeveloperguy.com/","https://feedthejoe.com/joseph/"],"categories":["Tools"],"sub_categories":["Lua Modules"],"readme":"# SEO Sidecar\n\n\u003e 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.\n\n[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)\n[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)\n[![FastAPI](https://img.shields.io/badge/FastAPI-0.104%2B-009688.svg)](https://fastapi.tiangolo.com/)\n[![nginx](https://img.shields.io/badge/nginx-1.18%2B-009639.svg)](https://nginx.org/)\n\n## Why this exists\n\nIf you host static or server-rendered HTML through nginx and want **fresh, dynamic Schema.org JSON-LD** in every page's `\u003chead\u003e` without redeploying the site every time a schema changes, you have three bad options:\n\n1. **Edit the HTML files** every time → site redeployment per schema change\n2. **Cron job that rebuilds + redeploys** → stale between cron runs, slow propagation\n3. **Server-side rendering** → couples schema generation to your rendering tier\n\nSEO 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.\n\nBuilt in production for [ThatDevPro](https://www.thatdevpro.com)'s network of nine client websites.\n\n## Architecture\n\n```\n\u003cUPSTREAM\u003e (your AI publishing source)\n    │\n    │  Push over Tailscale (event-driven)\n    │  POST /update/{site} with JSON-LD\n    │\n    ▼\n┌──────────────────────────────────────────┐\n│ \u003cSIDECAR_HOST\u003e (your nginx host)                │\n│                                          │\n│  seo-sidecar (localhost:9090)            │\n│  ├── SQLite: /var/lib/seo-sidecar/       │\n│  ├── Receives pushes from upstream       │\n│  ├── Serves schemas to nginx             │\n│  └── Keeps history + versioning          │\n│                                          │\n│  nginx                                   │\n│  ├── SSI include on every page load      │\n│  ├── Fetches from localhost:9090         │\n│  ├── 5min proxy_cache (configurable)     │\n│  └── 1s timeout (pages never stall)      │\n│                                          │\n│  9 hosted sites                          │\n│  └── Each gets dynamic JSON-LD in \u003chead\u003e │\n└──────────────────────────────────────────┘\n```\n\n## How It Works\n\n1. **Your upstream service decides** a schema needs updating (trend shift, new FAQ, competitor gap)\n2. **Upstream pushes** the new JSON-LD to `http://\u003cSIDECAR_HOST\u003e:9090/update/{site}` over Tailscale\n3. **Sidecar stores** it in SQLite with version history\n4. **nginx SSI** fetches from `localhost:9090/schema/{site}` on every HTML page load\n5. **Schema appears** in the `\u003chead\u003e` of the site — search engines and AI crawlers see it immediately\n\nNo cron jobs. No file writes. No site deployments. Upstream controls schema state remotely.\n\n## Files\n\n| File | Where It Goes | Purpose |\n|------|--------------|---------|\n| `sidecar.py` | `/opt/seo-sidecar/` on the sidecar host | FastAPI service — receives pushes, serves to nginx |\n| `nginx-seo-sidecar.conf` | `/etc/nginx/conf.d/` on the sidecar host | Upstream + hostname map |\n| `seo-inject.conf` | `/etc/nginx/snippets/` on the sidecar host | Drop-in include for server blocks |\n| `megamind_push.py` | upstream nodes | CLI push client |\n| `seo_client.go` | Go push client | Go push client for integration |\n| `seo-sidecar.service` | `/etc/systemd/system/` on the sidecar host | systemd unit |\n| `deploy-sidecar.sh` | Run once on the sidecar host | Full automated deployment |\n\n## Deploy on the sidecar host\n\n```bash\n# Copy files to your sidecar host\nscp -r seo-sidecar/ \u003cYOUR_SERVER\u003e:/tmp/seo-sidecar/\n\n# SSH in and deploy\nssh \u003cYOUR_SERVER\u003e\ncd /tmp/seo-sidecar\nsudo bash deploy-sidecar.sh\n```\n\nThen add one line to each nginx server block:\n```nginx\ninclude /etc/nginx/snippets/seo-inject.conf;\n```\n\nReload nginx:\n```bash\nnginx -t \u0026\u0026 systemctl reload nginx\n```\n\n## Push from your upstream\n\n```bash\n# Push single site\npython megamind_push.py push thatdeveloperguy\n\n# Push all 9 sites\npython megamind_push.py push-all\n\n# Bulk push (single HTTP request)\npython megamind_push.py push-bulk\n\n# Check what's live\npython megamind_push.py status\n\n# View version history\npython megamind_push.py history thatdeveloperguy\n```\n\nOr from Go:\n```go\nclient := seo.NewClient(\"http://\u003cSIDECAR_HOST\u003e:9090\", \"your-token\")\nclient.Push(\"thatdeveloperguy\", jsonldString)\n```\n\n## API Endpoints\n\n### Push (MEGAMIND → Sidecar)\n- `POST /update/{site}` — Push schema for one site\n- `POST /update-bulk` — Push schemas for multiple sites\n- `DELETE /schema/{site}` — Remove a schema\n\n### Serve (nginx → Sidecar)\n- `GET /schema/{site}` — Returns `\u003cscript type=\"application/ld+json\"\u003e` HTML\n\n### Monitor\n- `GET /status` — All sites, versions, freshness\n- `GET /history/{site}` — Version history\n\n## Config\n\nSet in `/etc/systemd/system/seo-sidecar.service`:\n\n| Env Var | Default | Description |\n|---------|---------|-------------|\n| `SEO_DB_PATH` | `/var/lib/seo-sidecar/schemas.db` | SQLite database location |\n| `SEO_AUTH_TOKEN` | `CHANGE_ME_BEFORE_DEPLOY` | Bearer token for push auth |\n| `SEO_HOST` | `127.0.0.1` | Listen address (keep localhost) |\n| `SEO_PORT` | `9090` | Listen port |\n\n## Adding New Sites\n\n1. Add the hostname mapping in `nginx-seo-sidecar.conf` (the `map` block)\n2. Add `include /etc/nginx/snippets/seo-inject.conf;` to the new site's server block\n3. Push a schema: `python megamind_push.py push newsite`\n\nThat's it. No other config changes.\n\n## Companion tools\n\n- [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.\n- [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.\n\n## License\n\nMIT © 2026 Joseph W. Anady ([ThatDevPro](https://www.thatdevpro.com)). See [LICENSE](LICENSE).\n\n---\n\nBuilt and used in production by **[ThatDevPro](https://www.thatdevpro.com)** — SDVOSB-certified veteran-owned web + AI engineering studio. Cassville, Missouri.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FJanady13%2Fseo-sidecar","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FJanady13%2Fseo-sidecar","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FJanady13%2Fseo-sidecar/lists"}