Skip to content

Commit e4c9d47

Browse files
myasnikovdaniilmyasnikovdaniil
authored
Merge branch 'main' into feat/security-summary
Signed-off-by: myasnikovdaniil <60174387+myasnikovdaniil@users.noreply.github.com>
2 parents 0b569cb + 62066fe commit e4c9d47

1,190 files changed

Lines changed: 101208 additions & 657 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/CODEOWNERS‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
* @kvaps @lllamnyp @nbykov0
1+
* @kvaps @lllamnyp

‎.github/workflows/fetch-telemetry.yml‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
name: Fetch Telemetry Data
2+
3+
on:
4+
# Keep this as a manual telemetry-only backfill path. The monthly OSS Health
5+
# refresh intentionally does not update telemetry while /api/overview differs
6+
# from the Grafana-backed source of truth.
7+
workflow_dispatch:
8+
9+
permissions:
10+
contents: write
11+
pull-requests: write
12+
13+
concurrency:
14+
group: fetch-telemetry
15+
cancel-in-progress: false
16+
17+
jobs:
18+
fetch-telemetry:
19+
runs-on: ubuntu-latest
20+
steps:
21+
- name: Checkout repository
22+
uses: actions/checkout@v4
23+
with:
24+
ref: 'main'
25+
26+
- name: Set up Python
27+
uses: actions/setup-python@v5
28+
with:
29+
python-version: '3.12'
30+
31+
- name: Fetch and transform telemetry data
32+
run: python3 hack/fetch_telemetry.py
33+
34+
- name: Check for changes
35+
id: changes
36+
run: |
37+
if git diff --quiet static/oss-health-data/telemetry.json; then
38+
echo "changed=false" >> "$GITHUB_OUTPUT"
39+
else
40+
echo "changed=true" >> "$GITHUB_OUTPUT"
41+
fi
42+
43+
- name: Commit and push
44+
if: steps.changes.outputs.changed == 'true'
45+
run: |
46+
git config user.name "github-actions[bot]"
47+
git config user.email "github-actions[bot]@users.noreply.github.com"
48+
git add static/oss-health-data/telemetry.json
49+
git branch -D update-telemetry || true
50+
git checkout -b update-telemetry
51+
git commit --signoff -m "[oss-health] Update telemetry snapshot $(date -u +'%Y-%m-%d %H:%M:%S')"
52+
git push --force --set-upstream origin update-telemetry
53+
54+
- name: Open pull request if not exists
55+
if: steps.changes.outputs.changed == 'true'
56+
env:
57+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
58+
run: |
59+
pr_state=$(gh pr view update-telemetry --json state --jq .state 2>/dev/null || echo "")
60+
echo "Current PR state: ${pr_state:-NONE}"
61+
62+
if [[ "$pr_state" == "OPEN" ]]; then
63+
echo "An open pull request already exists – skipping creation."
64+
else
65+
gh pr create \
66+
--title "[oss-health] Update telemetry snapshot" \
67+
--body "Automated telemetry update via workflow." \
68+
--head update-telemetry \
69+
--base main
70+
fi

‎.github/workflows/hugo.yaml‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,7 @@ jobs:
3232
build:
3333
runs-on: ubuntu-latest
3434
env:
35-
HUGO_VERSION: 0.151.1
35+
HUGO_VERSION: 0.160.1
3636
steps:
3737
- name: Install Hugo CLI
3838
run: |
@@ -50,6 +50,10 @@ jobs:
5050
uses: actions/configure-pages@v4
5151
- name: Install Node.js dependencies
5252
run: "[[ -f package-lock.json || -f npm-shrinkwrap.json ]] && npm ci || true"
53+
- name: Download OpenAPI specs
54+
run: ./hack/download_openapi.sh
55+
env:
56+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
5357
- name: Build with Hugo
5458
env:
5559
# For maximum backward compatibility with Hugo modules

‎.github/workflows/update-managed-apps.yaml‎

Lines changed: 0 additions & 66 deletions
This file was deleted.

‎.github/workflows/update-oss-health.yaml‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
name: Update OSS health snapshots
2+
3+
on:
4+
workflow_dispatch:
5+
schedule:
6+
- cron: '0 4 1 * *'
7+
8+
permissions:
9+
contents: write
10+
pull-requests: write
11+
12+
concurrency:
13+
group: update-oss-health
14+
cancel-in-progress: false
15+
16+
jobs:
17+
update-oss-health:
18+
runs-on: ubuntu-latest
19+
20+
steps:
21+
- name: Checkout target repo
22+
uses: actions/checkout@v4
23+
with:
24+
ref: 'main'
25+
26+
- name: Setup Python
27+
uses: actions/setup-python@v5
28+
with:
29+
python-version: '3.12'
30+
31+
- name: Update OSS health data
32+
env:
33+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
34+
run: |
35+
make update-oss-health
36+
git status -s
37+
38+
- name: Commit & push changes
39+
id: commit
40+
run: |
41+
git config user.name "github-actions[bot]"
42+
git config user.email "github-actions[bot]@users.noreply.github.com"
43+
git add data/oss-health static/oss-health-data content/en/oss-health
44+
if git diff --cached --quiet; then
45+
echo "No changes to commit"
46+
echo "changed=false" >> "$GITHUB_OUTPUT"
47+
exit 0
48+
fi
49+
git branch -D update-oss-health || true
50+
git checkout -b update-oss-health
51+
git commit --signoff -m "[oss-health] Update monthly OSS health snapshot $(date -u +'%Y-%m-%d %H:%M:%S')"
52+
git push --force --set-upstream origin update-oss-health
53+
echo "changed=true" >> "$GITHUB_OUTPUT"
54+
55+
- name: Open pull request if not exists
56+
if: steps.commit.outputs.changed == 'true'
57+
env:
58+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
59+
run: |
60+
pr_state=$(gh pr view update-oss-health --json state --jq .state 2>/dev/null || echo "")
61+
echo "Current PR state: ${pr_state:-NONE}"
62+
63+
if [[ "$pr_state" == "OPEN" ]]; then
64+
echo "An open pull request already exists – skipping creation."
65+
else
66+
gh pr create \
67+
--title "[oss-health] Update monthly OSS health snapshot" \
68+
--body "Automated update via workflow." \
69+
--head update-oss-health \
70+
--base main
71+
fi

‎.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,5 +22,8 @@ hugo/
2222
# IDE files
2323
.idea
2424

25+
# Downloaded OpenAPI specs (fetched at build time)
26+
static/docs/*/cozystack-api/
27+
2528
# Claude Code local settings
2629
.claude/

‎CLAUDE.md‎

Lines changed: 133 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,133 @@
1+
# CLAUDE.md
2+
3+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4+
5+
## Project Overview
6+
7+
Hugo documentation website for Cozystack (Kubernetes-based cloud platform) using the Google Docsy theme. **Production is served by GitHub Pages** — Netlify is only used for deploy previews on PRs. Do not rely on Netlify-specific features (`netlify.toml` redirects, headers, edge functions) for production behavior; they only work in deploy previews. For redirects, use Hugo aliases (per-page) or the JS fallback in `layouts/404.html`.
8+
9+
## Build & Development Commands
10+
11+
```bash
12+
# Install dependencies
13+
npm install
14+
15+
# Local dev server (serves at http://localhost:1313/docs; wipes public/ first)
16+
make serve
17+
18+
# Production build
19+
./hack/download_openapi.sh && hugo --gc --minify
20+
21+
# Sync app docs from cozystack/cozystack repo.
22+
# By default targets content/en/docs/next/ (the version-agnostic trunk).
23+
# With RELEASE_TAG, routing depends on whether the minor version is already released:
24+
# - patch of an existing released version → updates that vX.Y/ in place
25+
# - otherwise → updates next/ (upcoming release)
26+
make update-all # update trunk from upstream main
27+
make update-all RELEASE_TAG=v1.2.5 # patch release → updates v1.2/
28+
make update-all RELEASE_TAG=v1.3.0 # v1.3 not yet released → still updates next/
29+
make update-apps # application docs only (also: update-vms, update-networking, update-k8s, update-services)
30+
make update-oss-health # OSS health metrics (requires Python 3.12+)
31+
32+
# Scaffold front-matter-only stubs into DEST/_include (scaffolding variant of update-*, via hack/fill_templates.sh)
33+
make template-all # or template-apps / template-vms / template-networking / template-k8s / template-services
34+
35+
# Version lifecycle (requires yq v4+)
36+
make init-next # (re)create content/en/docs/next/ from latest released version
37+
make release-next RELEASE_TAG=v1.3.0 # promote next/ → v1.3/, register in hugo.yaml
38+
39+
# Initialize a new docs version directory directly (edge cases / manual backfills)
40+
make init-version DOC_VERSION=v1.3
41+
42+
# Override the app list for any update-*/template-* target
43+
make update-apps APPS="tenant redis"
44+
45+
# Debug routing
46+
make show-target RELEASE_TAG=v1.3.0 # prints the resolved DOC_VERSION/BRANCH
47+
```
48+
49+
Required tools: Hugo extended v0.160.1, Go 1.23+, Node 20+, yq v4+ (for version lifecycle targets).
50+
51+
## Architecture
52+
53+
- **Hugo modules** (not git submodules): Docsy theme v0.12.0 pulled via `go.mod`
54+
- **Versioned docs**: `content/en/docs/v0/`, `content/en/docs/v1.0/`, `content/en/docs/v1.1/`, `content/en/docs/v1.2/` plus the permanent trunk `content/en/docs/next/`. Version switching handled by `layouts/partials/version-switcher.html` (honours the `hidden: true` flag on version entries). Version derived from RELEASE_TAG (e.g., v1.2.1 → v1.2)
55+
- **Content sync scripts**: `hack/update_apps.sh` fetches READMEs from the upstream cozystack repo and appends autogenerated notices. Driven by the `make update-*` targets (manual)
56+
- **OpenAPI specs**: v0/v1.0 api.json stored in git; v1.1+ downloaded at build time from GitHub releases via `hack/download_openapi.sh`
57+
- **OSS health pipeline**: `hack/update_oss_health.py` collects metrics from GitHub API, OpenSSF, DevStats, OSS Insight → writes JSON to `data/oss-health/` and `static/oss-health-data/`. Monthly GitHub Action
58+
- **Asset pipeline**: Bootstrap 5.3 + Font Awesome 6.7 mounted from node_modules via Hugo mounts (configured in `hugo.yaml`). SCSS entry point: `assets/scss/main.scss`
59+
- **Blog**: `content/en/blog/` with permalink pattern `:section/:year/:month/:slug/`
60+
61+
## Versioning
62+
63+
Docs are versioned per Cozystack minor release. Each version is an independent copy of the tree under `content/en/docs/<version>/` and is built into its own URL prefix (`/docs/<version>/`).
64+
65+
**Directory layout**
66+
- One directory per minor version: `content/en/docs/v0/`, `v1.0/`, `v1.1/`, `v1.2/`
67+
- Version name derivation: major `0` → `v0` (legacy, covers all 0.x); major ≥ 1 → `v<major>.<minor>` (e.g., `v1.2`). Patch level is not reflected in the directory name
68+
- Each version directory is self-contained: all pages under `applications/`, `virtualization/`, `networking/`, `operations/`, `storage/`, `install/`, `guides/`, etc. live once per version
69+
- `content/en/docs/_index.md` is the single version-agnostic landing page
70+
- `content/en/docs/next/` is the permanent trunk for upcoming/unreleased docs. Internal links use `/docs/next/`; these are rewritten at release time by `hack/release_next.sh`. Excluded from production builds via the `hidden: true` entry in `hugo.yaml` and the content mount exclusion `- '! docs/next/**'`
71+
72+
**Version registration (`hugo.yaml`)**
73+
- `params.latest_version_id` — id of the current/default version
74+
- `params.versions[]` — ordered list consumed by the version switcher (`layouts/partials/version-switcher.html`). Newest goes first, `order` highest. **When adding a new version, update both fields.**
75+
- `hidden: true` on a version entry hides it from the dropdown selector. Combined with the content mount exclusion pattern (`- '! docs/<id>/**'`), the whole version is also excluded from production builds. Used for the `next` trunk; the dev server and Netlify deploy previews still render it at `/docs/next/`.
76+
77+
**Where to add changes**
78+
- Docs for an upcoming (unreleased) feature → edit `content/en/docs/next/`. These materialize as `v<next-release>/` when `make release-next RELEASE_TAG=vX.Y.Z` runs
79+
- Bug fix or addition to the current release → edit only `content/en/docs/<latest_version_id>/` (currently `v1.2`)
80+
- Content that also applies to older supported versions → copy the change into each relevant `v*/` directory (no automatic backport)
81+
- Cross-version/landing content → `content/en/docs/_index.md`
82+
- Blog posts are version-independent → `content/en/blog/`
83+
84+
**Autogenerated files — do not edit in-place**
85+
- App/VM/networking/services pages synced from `cozystack/cozystack` have the footer `Autogenerated content. Don't edit this file directly; edit sources instead.` (injected by `hack/update_apps.sh`)
86+
- To change the body: edit the upstream README in `cozystack/cozystack` under `packages/apps/<app>/` (or `packages/extra/<svc>/` for services), then re-run the corresponding `make update-*` target
87+
- To change only front matter (title, weight, aliases) for a specific version: edit the stub at `content/en/docs/<version>/<section>/_include/<app>.md` — `update-*` merges this with the upstream README. `make template-*` scaffolds these stubs
88+
89+
**RELEASE_TAG → routing (Makefile)**
90+
91+
The Makefile routes updates between `next/` and released `vX.Y/` directories. Given a `RELEASE_TAG` like `v1.2.5` the minor version `v1.2` is derived; routing is:
92+
93+
- `make update-all` (no tag) → `DOC_VERSION=next`, `BRANCH=main`
94+
- `make update-all RELEASE_TAG=v1.2.5` and `content/en/docs/v1.2/` exists and is a non-hidden entry in `hugo.yaml` → `DOC_VERSION=v1.2` (patch release, updates in place)
95+
- `make update-all RELEASE_TAG=v1.3.0` and `content/en/docs/v1.3/` does not yet exist → `DOC_VERSION=next` (still accumulating in the trunk)
96+
- `make release-next RELEASE_TAG=v1.3.0` copies `content/en/docs/next/` → `content/en/docs/v1.3/`, rewrites `/docs/next/` links, and registers `v1.3` via `hack/register_version.sh --release v1.3`. `next/` is unchanged
97+
- After `release-next`, subsequent `make update-all RELEASE_TAG=v1.3.1` routes to `v1.3/`
98+
99+
**Releasing a new minor (`v1.3.0`)**
100+
1. `make release-next RELEASE_TAG=v1.3.0` — copies `next/` → `v1.3/`, rewrites internal links, registers `v1.3` as the new `latest_version_id`. `next/` stays in place for the next cycle
101+
2. (optional) `make update-all RELEASE_TAG=v1.3.0` — pulls fresh upstream READMEs pinned to the exact tag into `v1.3/`
102+
103+
**Refreshing the trunk from the latest released version**
104+
- `make init-next` — removes `content/en/docs/next/` and reinitializes it from the latest `v*/` directory. `hack/init_version.sh` handles the `next/` case specially (sets title to "Cozystack Next (unreleased)", strips aliases, prepends a draft banner shortcode)
105+
106+
**OpenAPI per version**
107+
- `v0` and `v1.0` ship their `api.json` in git under `static/docs/<version>/cozystack-api/api.json`
108+
- `v1.1+` are fetched at build time from `https://github.com/cozystack/cozystack/releases/download/<tag>/openapi.json` by `hack/download_openapi.sh` (run before `hugo --gc --minify`). `openapi.json` is produced as a release asset by the upstream tags workflow (cozystack/cozystack#2214)
109+
110+
**How new-version docs arrive**
111+
- Docs updates are pushed by the upstream `cozystack/cozystack` release workflow (`.github/workflows/tags.yaml`, `update-website-docs` job). On every `vX.Y.Z` tag it checks out this repo at `main` and opens/updates a PR titled `[docs] Update managed apps reference for v<version>`
112+
- Upstream workflow contract:
113+
- Always calls `make update-all RELEASE_TAG=vX.Y.Z` — routing (above) picks the right target directory
114+
- Additionally calls `make release-next RELEASE_TAG=vX.Y.Z` for new minor/major releases (not patch releases). `release-next` validates preconditions and fails hard if they aren't met — there is no silent no-op. Detection of "new minor vs patch" is owned by the upstream workflow (explicit conditional), not by the website-side Makefile
115+
- The website-side `make update-*` / `make template-*` / `make release-next` / `make init-next` targets and `hack/update_apps.sh` / `hack/fill_templates.sh` / `hack/download_openapi.sh` / `hack/release_next.sh` are the contract this upstream workflow invokes
116+
- The previous website-side daily cron (`.github/workflows/update-managed-apps.yaml`) is obsolete (superseded by the upstream flow from cozystack/cozystack#2214)
117+
118+
## Key Config
119+
120+
- `hugo.yaml` — main Hugo config including module mounts, menus, params, multi-version setup
121+
- `netlify.toml` — Netlify build settings (deploy previews include `--buildFuture`)
122+
- `package.json` — npm deps (Bootstrap, Font Awesome, PostCSS/autoprefixer)
123+
124+
## Custom Shortcodes
125+
126+
Located in `layouts/shortcodes/`: `tabs`/`tab`, `note`, `warning`, `caution`, `include`, `youtube`, `system-resource-calculator`, `blocks/hero`, `blocks/resource`, `blocks/flux_ui_galleries`.
127+
128+
## Content Conventions
129+
130+
- Docs synced from upstream have autogenerated notices — don't manually edit those files; update the source in cozystack/cozystack instead
131+
- Hugo frontmatter uses YAML
132+
- OSS health app pages use custom layout (`layouts/_default/oss-health-app.html`) with frontmatter keys: `oss_health_key`, `oss_health_kind`, `lede`, `source_url`
133+
- Goldmark rendering has `unsafe: true` enabled (raw HTML allowed in markdown)

0 commit comments

Comments
 (0)