From 8a2b145fe5be00ccbd6862bd1f99322f90f5c4cf Mon Sep 17 00:00:00 2001 From: George Date: Wed, 14 Oct 2026 03:56:02 +0300 Subject: [PATCH] docs: publish the site at docs.sogeor.com --- .github/ISSUE_TEMPLATE/config.yml | 2 +- .github/workflows/docs.yml | 2 +- CHANGELOG.md | 1 + README.md | 2 +- ROADMAP.md | 1 - docs/about/configuration.md | 2 +- docs/about/setup.md | 21 +++++++++++++++++---- docs/about/troubleshooting.md | 14 ++++++++++++++ mkdocs.yml | 2 +- 9 files changed, 37 insertions(+), 10 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml index 1feb098..3a261fa 100644 --- a/.github/ISSUE_TEMPLATE/config.yml +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -4,5 +4,5 @@ contact_links: url: https://github.com/sogeor/docs/security/advisories/new about: Report vulnerabilities privately, not in public issues. - name: Documentation site - url: https://sogeor.github.io/docs/ + url: https://docs.sogeor.com/ about: Platform overview, deployment guide, ADRs and runbooks. diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index fe3b5e9..204be12 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -20,7 +20,7 @@ jobs: link-args: >- --exclude-path docs/repos --exclude '^https://github\.com/sogeor/[^/]+/(security|issues/new)' - --exclude '^https://sogeor\.github\.io/docs' + --exclude '^https://docs\.sogeor\.com' --exclude '^https?://127\.0\.0\.1' site: diff --git a/CHANGELOG.md b/CHANGELOG.md index fa07ef6..8ca2f66 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -25,3 +25,4 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), - Site aggregates `.github` v0.3.0; repository status table updated (`.github` v0.3.0, `workflows` v0.1.1, `modules` in progress). - Pinning guidance: annotated tags are pinned by the peeled commit SHA. - Renovate proposes versions only 7 days after release (`minimumReleaseAge`); pins of aggregated repositories in `sources.yaml` are exempt. +- Site address is `https://docs.sogeor.com/` (`site_url`, README, issue template, link check exclusion); setup and troubleshooting pages describe the custom domain, DNS-only record and HTTPS. diff --git a/README.md b/README.md index 1e2ac4f..2e40112 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,7 @@ End-to-end documentation of the sogeor DevSecOps platform and the source of its - "Deploy everything": one guide from an empty account to a working platform. - Platform ADRs ([MADR](https://adr.github.io/madr/)), runbooks, threat models, postmortems and exercises. - Aggregates the `docs/` directory of every platform repository, pinned by tag and SHA. -- Builds and publishes the site to GitHub Pages: . +- Builds and publishes the site to GitHub Pages: . ## How it works diff --git a/ROADMAP.md b/ROADMAP.md index 615f3c9..8370d20 100644 --- a/ROADMAP.md +++ b/ROADMAP.md @@ -10,7 +10,6 @@ Horizon: through Q4 2027. Order follows the sogeor platform plan. - Platform ADRs for every foundational decision. - "Deploy everything" guide from an empty account to a working platform, completed as repositories are released. - Runbooks (including incident response), threat models, postmortem and exercise templates. -- Custom domain `docs.sogeor.com`. ## Not planned diff --git a/docs/about/configuration.md b/docs/about/configuration.md index f648d89..9b70b01 100644 --- a/docs/about/configuration.md +++ b/docs/about/configuration.md @@ -36,7 +36,7 @@ Base site configuration. `tools/aggregate.py` writes `mkdocs.generated.yml`, whi | Key | Value | Notes | |---|---|---| -| `site_url` | `https://sogeor.github.io/docs/` | Change in a fork or when a custom domain is added | +| `site_url` | `https://docs.sogeor.com/` | Address of the published site; change it in a fork ([Custom domain](setup.md#custom-domain)) | | `strict` | `true` | Any warning fails the build | | `validation` | all `warn` | Broken links, unknown anchors, pages outside `nav` fail the strict build | | `theme.features` | tabs, sections, indexes, code copy | No edit button: aggregated pages belong to other repositories | diff --git a/docs/about/setup.md b/docs/about/setup.md index 703131f..4faad17 100644 --- a/docs/about/setup.md +++ b/docs/about/setup.md @@ -15,7 +15,7 @@ features work. Steps are in order; each ends with a check. | Field | Value | |---|---| | Description | `Documentation of the sogeor DevSecOps platform: overview, cluster constructor, network, security and compliance, platform ADRs, runbooks and threat models, with pinned docs of every platform repository built into one MkDocs site.` | -| Website | `https://.github.io/docs/` (later the custom documentation domain) | +| Website | `https://docs.sogeor.com/` (in a fork: your custom domain or `https://.github.io/docs/`) | | Topics | `documentation` `mkdocs` `mkdocs-material` `github-pages` `devsecops` `platform-engineering` `architecture-decision-records` `adr` `runbooks` `threat-modeling` `kubernetes` `gitops` `infrastructure-as-code` `supply-chain-security` `compliance` | | Include in the home page | Releases — off until the first release; Deployments — on; Packages — off | @@ -76,9 +76,22 @@ Check: the **Security** tab shows **Report a vulnerability**. Check: **Settings → Pages** shows **Your site is live at `https://.github.io/docs/`**. -!!! note "Custom domain" - A custom domain is configured later: **Settings → Pages → Custom domain**, plus a `CNAME` DNS record - pointing to `.github.io`, and `site_url` in `mkdocs.yml`. +### Custom domain + +The reference site uses `docs.sogeor.com`. In a fork, replace `docs.example.com` with your domain. + +1. In your DNS provider, create a record: type `CNAME`, name `docs`, target `.github.io`. + In Cloudflare: **DNS → Records → Add record**, **Proxy status: DNS only** (grey cloud). +2. **Settings → Pages → Custom domain:** `docs.example.com` → **Save**. Wait for **DNS check successful**. +3. When the certificate is issued (up to an hour), enable **Enforce HTTPS**. +4. Set `site_url: https://docs.example.com/` in `mkdocs.yml` and the domain in the `lychee` exclusion of + `.github/workflows/docs.yml`; merge the change so `pages` republishes the site. + +Check: `https://docs.example.com/` opens the home page, and `https://.github.io/docs/` redirects to it. + +!!! warning "Keep the record DNS only" + With the Cloudflare proxy (orange cloud) enabled, GitHub cannot issue the certificate and + **Enforce HTTPS** stays unavailable. See [Troubleshooting](troubleshooting.md#custom-domain-returns-404-or-https-is-unavailable). ## Renovate diff --git a/docs/about/troubleshooting.md b/docs/about/troubleshooting.md index 5a5b1a1..4b688e2 100644 --- a/docs/about/troubleshooting.md +++ b/docs/about/troubleshooting.md @@ -40,6 +40,20 @@ **Cause:** the entry does not match the expected order `url`, `ref`, `sha` on consecutive lines. **Fix:** keep the key order from [Configuration](configuration.md#sourcesyaml). +## Custom domain returns 404 or HTTPS is unavailable + +| Symptom | Cause | Fix | +|---|---|---| +| The home page returns `404 There isn't a GitHub Pages site here`, while other pages work; the response has a large `Age` header | The CDN of GitHub Pages cached a 404 from before the first deployment | Run **Actions → pages → Run workflow** on `master`, or wait 10–20 minutes; reload with cache bypass | +| **Enforce HTTPS** is unavailable: *domain is not properly configured to support HTTPS* | The DNS record is proxied by Cloudflare, so GitHub cannot issue the certificate | Set the record to **DNS only**, wait up to an hour, then enable **Enforce HTTPS** | +| `sitemap.xml` and canonical links point to the old address | `site_url` in `mkdocs.yml` was not changed | Set `site_url` to the custom domain | + +Check the response headers: + +```bash +curl -sS -o /dev/null -D - https://docs.example.com/ +``` + ## Pages deployment fails with `Branch "…" is not allowed to deploy to github-pages` **Cause:** the environment allows only `master`. diff --git a/mkdocs.yml b/mkdocs.yml index 3b3c9b4..17cc04d 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,6 +1,6 @@ site_name: sogeor platform site_description: Documentation of the sogeor DevSecOps platform -site_url: https://sogeor.github.io/docs/ +site_url: https://docs.sogeor.com/ repo_url: https://github.com/sogeor/docs repo_name: sogeor/docs copyright: Copyright © sogeor. Licensed under Apache-2.0.