Skip to content

Commit 964cf84

Browse files
ShawnMcKeeShawnMcKee
authored
Merge pull request #7 from osg-htc/reorg/personas-use-cases
Reorg/personas use cases, add in super linting for new markdown.
2 parents 2ac2d61 + 1871584 commit 964cf84

File tree

16 files changed

+311
-0
lines changed

16 files changed

+311
-0
lines changed

‎.github/PR_BODY.md‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
Reorganize docs into persona-driven structure (Quick Deploy, Troubleshooter, Researcher)
2+
3+
Summary
4+
- This branch scaffolds a persona-driven documentation layout under `docs/personas/` and adds templates and feature pages.
5+
- Adds tooling to detect and safely repair broken links (`docs/tools/`). A broken-links report was generated and partially applied; backups are available under `docs/.link_check_backups/`.
6+
- Adds a GitHub Actions workflow to run linting and build the MkDocs site and to run the docs link-check script in dry-run mode.
7+
8+
Files changed / added (high level)
9+
- `docs/personas/` (landing pages and starters)
10+
- `docs/features/` (feature guidance pages)
11+
- `docs/templates/` (author templates)
12+
- `docs/tools/` (link-checker and applier)
13+
- `.github/workflows/docs-ci.yml` (this CI workflow)
14+
15+
Checklist
16+
- [ ] Review content in `docs/personas/` and move or expand Quick Deploy quickstarts as needed
17+
- [ ] Confirm link mapping entries in `docs/tools/link_mapping.json`
18+
- [ ] Review mkdocs nav in `mkdocs.yml` and add any missing pages intentionally omitted
19+
- [ ] Run the link-checker locally for a full (non-dry-run) pass before merging if you want the applier to touch files automatically
20+
21+
Notes
22+
- The CI runs `mkdocs build --strict` so build warnings will fail the job. It also runs the link-checker in dry-run mode so PRs will report issues but not modify files.
23+
- If you want the CI to automatically apply safe mapping changes, we should add a separate job with a bot account and commit permissions (not present in this workflow).
24+
25+
If you'd like, I can (a) open this PR as a draft (attempting now), and (b) add a CI job to run the applier in a non-destructive mode or open a second PR that applies safe fixes.
26+
27+
-- Automated draft created by tooling

‎.github/workflows/docs-ci.yml‎

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
1+
name: Docs CI
2+
3+
on:
4+
pull_request:
5+
branches: [ master ]
6+
paths:
7+
- 'docs/**'
8+
- '.github/**'
9+
- 'mkdocs.yml'
10+
push:
11+
branches: [ reorg/personas-use-cases ]
12+
paths:
13+
- 'docs/**'
14+
- '.github/**'
15+
- 'mkdocs.yml'
16+
17+
jobs:
18+
lint:
19+
name: Lint (Super-Linter)
20+
runs-on: ubuntu-latest
21+
steps:
22+
- uses: actions/checkout@v4
23+
- name: Run Super-Linter (limited scope for this PR)
24+
uses: github/super-linter@v4
25+
env:
26+
# Only lint selected paths to avoid failing on large legacy docs set.
27+
# This regex matches files under .github/, docs/personas/, docs/tools/, docs/templates/, docs/features/, and mkdocs.yml
28+
FILTER_REGEX_INCLUDE: '(^\.github/|^docs/personas/|^docs/tools/|^docs/templates/|^docs/features/|^mkdocs.yml|^\.github/PR_BODY.md)'
29+
VALIDATE_ALL_CODEBASE: false
30+
VALIDATE_MARKDOWN: true
31+
VALIDATE_SHELL: true
32+
VALIDATE_YAML: true
33+
VALIDATE_JSON: true
34+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
35+
36+
docs:
37+
name: Build docs + Link checks
38+
needs: lint
39+
runs-on: ubuntu-latest
40+
steps:
41+
- uses: actions/checkout@v4
42+
- name: Set up Python
43+
uses: actions/setup-python@v4
44+
with:
45+
python-version: '3.11'
46+
- name: Install Python dependencies
47+
run: |
48+
python -m pip install --upgrade pip
49+
pip install mkdocs mkdocs-material requests beautifulsoup4
50+
- name: Build MkDocs site
51+
run: mkdocs build --clean --strict
52+
- name: Run docs link-check (dry-run)
53+
run: python docs/tools/find_and_remove_broken_links.py --check-externals --dry-run || true

‎docs/features/fail2ban.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
---
2+
title: Feature: fail2ban
3+
description: Guidance on using fail2ban with perfSONAR testpoints to reduce brute-force attacks.
4+
owners: [networking-team@osg-htc.org]
5+
status: draft
6+
tags: [fail2ban, security]
7+
---
8+
9+
When to enable fail2ban: when exposed services accept external credentials (ssh, web admin). Example configuration and a sample jail are provided.

‎docs/features/nftables.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
---
2+
title: Feature: nftables
3+
description: Recommended nftables snippets and common troubleshooting for perfSONAR testpoints.
4+
owners: [networking-team@osg-htc.org]
5+
status: draft
6+
tags: [nftables, firewall]
7+
---
8+
9+
Example rules and tips for debugging blocked tests.

‎docs/features/selinux.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
---
2+
title: Feature: SELinux guidance
3+
description: SELinux considerations and recommended policy for perfSONAR testpoints.
4+
owners: [networking-team@osg-htc.org]
5+
status: draft
6+
tags: [selinux, security]
7+
---
8+
9+
Short guidance: prefer permissive mode for initial deployment only; then create minimal allow rules and move to enforcing mode.

‎docs/migration_inventory.yml‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# Migration inventory: map source documents (Google Drive or site) to new repo paths
2+
# Fields: source_title, source_link, target_path, owner, priority (1=high quick-deploy)
3+
4+
- source_title: "Install perfSONAR Testpoint (Drive)"
5+
source_link: "https://drive.google.com/..."
6+
target_path: "docs/personas/quick-deploy/quickstart-perfsonar-testpoint.md"
7+
owner: networking-team@osg-htc.org
8+
priority: 1
9+
10+
- source_title: "Network debugging document"
11+
source_link: "https://drive.google.com/..."
12+
target_path: "docs/personas/troubleshoot/triage-checklist.md"
13+
owner: networking-team@osg-htc.org
14+
priority: 1

‎docs/personas/quick-deploy/automated-setup/README.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
---
2+
title: Automated setup — perfSONAR Testpoint
3+
description: Examples for automating setup using Ansible and container-based examples.
4+
persona: quick-deploy
5+
owners: [networking-team@osg-htc.org]
6+
status: draft
7+
tags: [automation, ansible]
8+
---
9+
10+
This directory contains examples and pointers for automated deployment:
11+
12+
- `ansible/` — playbooks and roles (example skeleton)
13+
- `docker/` — example container-based testpoint deployments (optional)
14+
15+
Use these examples as a starting point and adapt to site policies.

‎docs/personas/quick-deploy/landing.md‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
---
2+
title: Quick Deploy — perfSONAR Testpoint (Quick Deploy)
3+
description: Quick, minimal steps to deploy a perfSONAR testpoint for WLCG/OSG monitoring.
4+
persona: quick-deploy
5+
owners: [networking-team@osg-htc.org]
6+
status: draft
7+
tags: [quickstart, perfSONAR, testpoint]
8+
---
9+
10+
# Quick Deploy — perfSONAR Testpoint
11+
12+
This page provides a concise, tested minimal path to deploy a perfSONAR testpoint suitable for WLCG/OSG monitoring. Use the Quickstart for a fast, verified deployment. For optional features (fail2ban, selinux, nftables, automation) see the linked pages.
13+
14+
- Quickstart: `quickstart-perfsonar-testpoint.md`
15+
- Optional features and automated setup: `automated-setup/README.md`
16+
17+
Follow the quickstart if you need a working testpoint in a single admin session.

‎docs/personas/quick-deploy/quickstart-perfsonar-testpoint.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
---
2+
title: Quickstart: perfSONAR Testpoint (Minimal)
3+
description: Minimal set of commands and verification to deploy a perfSONAR testpoint for WLCG/OSG.
4+
persona: quick-deploy
5+
owners: [networking-team@osg-htc.org]
6+
status: draft
7+
tags: [quickstart, perfSONAR]
8+
---
9+
10+
## Quickstart (minimal)
11+
12+
1. Prepare a clean EL8/EL9 host with network connectivity and root access.
13+
2. Install packages (example for EL9):
14+
15+
```bash
16+
sudo dnf install -y perfsonar-toolkit
17+
```
18+
19+
3. Run initial configuration (example):
20+
21+
```bash
22+
sudo psconfig setup --auto
23+
```
24+
25+
4. Verify the testpoint is reachable and tests are scheduled:
26+
27+
```bash
28+
curl -sSf http://localhost/ | head
29+
pscheduler tasks --host localhost
30+
```
31+
32+
See `automated-setup/README.md` for Ansible examples and optional feature toggles.

‎docs/personas/research/architecture.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
---
2+
title: Architecture of OSG perfSONAR monitoring
3+
description: High-level architecture, components, and data flow for OSG perfSONAR monitoring.
4+
persona: research
5+
owners: [networking-team@osg-htc.org]
6+
status: draft
7+
tags: [architecture, data-pipeline]
8+
---
9+
10+
## Architecture (summary)
11+
12+
- perfSONAR agents (testpoints)
13+
- central collectors (ELK/Elasticsearch ingestion)
14+
- configuration services (psconfig / psetf)
15+
16+
Diagram and detailed flow to follow.

0 commit comments

Comments
 (0)