End-to-end documentation of the sogeor DevSecOps platform and the source of its documentation site.
- Cross-cutting pages: platform overview, principles, cluster constructor, network, security, compliance, capacity.
- "Deploy everything": one guide from an empty account to a working platform.
- Platform ADRs (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: https://docs.sogeor.com/.
flowchart LR
subgraph repos[Platform repositories]
images[sogeor/images docs/]
other[other repositories docs/]
end
pages[Cross-cutting pages and ADRs]
ci[GitHub Actions: copy pinned docs, rewrite links, mkdocs build --strict]
site[GitHub Pages]
images --> ci
other --> ci
pages --> ci
ci --> site
git clone https://github.com/sogeor/docs.git
cd docs
pip install --require-hashes -r .github/requirements-docs.txt
python tools/aggregate.py
mkdocs serve -f mkdocs.generated.ymltools/aggregate.py fetches the pinned docs/ of every repository listed in sources.yaml.
Use --local images=../images to preview a local checkout instead. Details: Getting started.
| Page | Contents |
|---|---|
| Overview | What the platform is, where to start, repositories |
| Platform overview | Loops, dependency rule, reference clusters, failure model, stack |
| Vision and roadmap | Long-term direction: sogeor platform as a multi-provider PaaS |
| Principles | Principles and repository conventions |
| Cluster constructor | Cluster description, distributions, OS, providers, topology, sizes, validations, node contract |
| Deploy everything | End-to-end deployment path |
| Network | Sites, CIDRs, mesh, inbound traffic, DNS and TLS |
| Security | Supply chain, policies, secrets, access, detection, vulnerability management |
| Compliance | International and Russian tracks |
| Capacity | Sizing and budget |
| Decisions | Platform ADRs |
| Runbooks | Cross-repository operational procedures |
| Incident response | Process, severity, playbooks |
| Threat models | STRIDE models of components and flows |
| Postmortems | Blameless incident reviews |
| Exercises | Restore drills, chaos experiments, tabletop exercises |
| About this repository | Getting started, setup, configuration, usage, operations, architecture, security, troubleshooting, reference |
| Tool | Version |
|---|---|
| Python | 3.12 |
| MkDocs Material | 9.7.7 |
| PyYAML | 6.0.3 |
| pre-commit-hooks | 6.0.0 |
| gitleaks | 8.30.1 |
| shellcheck | 0.11.0 |
| yamllint | 1.38.0 |
| markdownlint-cli2 | 0.23.3 |
| actionlint | 1.7.12 |
| zizmor | 1.30.1 |
sogeor/workflows (docs) |
0.1.1 |
| actions/checkout | 7.0.1 |
| actions/configure-pages | 6.0.0 |
| actions/upload-pages-artifact | 5.0.0 |
| actions/deploy-pages | 5.0.1 |
| actions/upload-artifact | 7.0.2 |
| github/codeql-action | 4.38.3 |
| ossf/scorecard-action | 2.4.4 |
See CONTRIBUTING.md, GOVERNANCE.md and CODE_OF_CONDUCT.md.
Report vulnerabilities privately as described in SECURITY.md.