# Self-hosting the Cisco IOS XE OpenAPI Documentation Hub Run the full site from a `git clone` on a laptop, behind a corporate proxy, on an internal web server, or inside a fully **air-gapped / high-security** network. The repository is self-contained: there are no runtime build steps, no required services, no analytics, no telemetry, and (since v33) **no external CDN or web-font requests**. --- ## TL;DR ```powershell git clone https://github.com/CiscoDevNet/cisco-ios-xe-openapi-swagger.git cd cisco-ios-xe-openapi-swagger python -m http.server 8000 # open http://localhost:8000 ``` That is the entire deployment for a single user. For multi-user use behind a real web server, see [Hosting behind nginx / IIS / Apache](#hosting-behind-a-real-web-server). --- ## What runs locally without internet The site is 100% static HTML / CSS / JS / JSON. Every dependency required to render any page is in the repository: | Component | Where | |-----------|-------| | OpenAPI 2.0 spec bundles | `swagger-*-model/*.json` and `releases//...` | | Swagger UI 5.31.0 | `assets/vendor/swagger-ui-5.31.0/` (SRI-verified) | | Fuse.js 7.0.0 (search) | `assets/vendor/fuse.js` (SRI-verified) | | Chart.js 4.4.0 (hub charts) | `assets/vendor/chart.umd.js` (SRI-verified) | | Postman / Bruno collections | `tools/` and `releases//exports/` | | YANG tree HTML | `yang-trees/` and `releases//yang-trees/` | | Per-release search & accountability indices | `releases//*.json` | | Fonts | System sans-serif fallback (`Roboto, system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Arial, sans-serif`). Google Fonts is **not** loaded. | A strict `Content-Security-Policy` declared in every HTML `` enforces `default-src 'self'` with no external hosts. You can verify by opening DevTools → Network and confirming every request resolves to your own host. --- ## Prerequisites | Requirement | Minimum | Notes | |-------------|---------|-------| | Disk space | ~1 GB | Repository is large because of `releases/` snapshots. Use shallow clone (`--depth 1`) to halve it. | | Python | 3.9+ | Only needed if you use `python -m http.server`; the site itself has no Python runtime. | | Browser | Any modern Chromium / Firefox / Edge / Safari from the last 2 years | The site is PWA-capable but does not require service workers to function. | | Network egress from server | **None.** | Only the initial `git clone` needs internet (or transfer the repo by USB / artifact server). | ### Shallow clone (recommended for transfer) If you only need the current release and want a smaller payload to move into the air-gapped network: ```powershell git clone --depth 1 https://github.com/CiscoDevNet/cisco-ios-xe-openapi-swagger.git ``` Then bundle and transfer: ```powershell Compress-Archive -Path cisco-ios-xe-openapi-swagger -DestinationPath xe-docs.zip ``` On the destination machine extract and serve. No further fetch is required. --- ## Quick start: single-user laptop ```powershell cd cisco-ios-xe-openapi-swagger python -m http.server 8000 ``` Open `http://localhost:8000` in any modern browser. Every page (Universal Search, every `swagger-*-model/` viewer, Tree Compare, Code Generator, Telemetry, Platform Coverage, YANG Accountability, App Map) will function with no further configuration. ### Optional: skip the service worker If you do not want the PWA install prompt or offline caching, just ignore it. The site works identically without registering the worker. To fully disable it, delete `assets/js/sw-register.js` references — but there is no need. --- ## Hosting behind a real web server The site is just a directory of static files. Point any web server at the repository root. ### nginx ```nginx server { listen 443 ssl; server_name xe-docs.internal.example.com; ssl_certificate /etc/nginx/certs/xe-docs.crt; ssl_certificate_key /etc/nginx/certs/xe-docs.key; root /srv/cisco-ios-xe-openapi-swagger; index index.html; # YANG files are text; some browsers will offer to download them # without this hint. types { text/plain yang; application/json json; } # Cache the immutable vendored libs for a year. location /assets/vendor/ { add_header Cache-Control "public, max-age=31536000, immutable"; } # Service worker should never be cached at the edge. location = /service-worker.js { add_header Cache-Control "no-cache, no-store, must-revalidate"; } # SPA-style 404 -> the bundled 404.html (smart-suggest viewer). error_page 404 /404.html; } ``` ### IIS The repo ships a `web.config` is **not** required. Default static-file serving works. To suggest a `.yang` MIME mapping, add via IIS Manager → MIME Types: `.yang` → `text/plain`. ### Apache (`httpd.conf` snippet) ```apache AddType text/plain .yang AddType application/json .json Options -Indexes AllowOverride None Require all granted ErrorDocument 404 /404.html Header set Cache-Control "public, max-age=31536000, immutable" Header set Cache-Control "no-cache, no-store, must-revalidate" ``` ### Python (production) For very small deployments (a few users, intranet) `python -m http.server` is fine. For anything larger, prefer nginx — `http.server` is single-threaded and not hardened for production. --- ## Security posture What ships: - **Strict CSP.** Every top-level page declares `default-src 'self'`. Viewer pages additionally allow `'unsafe-inline' 'unsafe-eval'` in `script-src` only because Swagger UI's bundle requires it; no external hosts are allowed under any directive. - **Subresource Integrity (SRI).** Every `