Skip to content

docs: document well-known discovery workflow and exclude internal assets #24

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
anwar3606 merged 2 commits into from
Sep 8, 2026
Merged

docs: document well-known discovery workflow and exclude internal assets #24

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b8e2a21
docs: document well-known discovery workflow and exclude internal assets
anwar3606 Sep 8, 2026
930889a
refactor: remove legacy webflow assets and document legacy oobi mirror
anwar3606 Sep 8, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
52 changes: 0 additions & 52 deletions 401.html
View file
Open in desktop

This file was deleted.

35 changes: 32 additions & 3 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -70,7 +70,36 @@ utils/website-contact-form/

---

## 3. Local Development
## 3. GLEIF & KERI `.well-known` Discovery

Provenant publishes its Qualified vLEI Issuer (QVI) discovery surface at `/.well-known` adhering to the GLEIF discovery convention.

### Source Assets & Generation

- **Source of truth (`well-known-assets/`)**: Contains raw JSON definitions organized by resource type:
- `well-known-assets/aid/`: QVI and Root AIDs (e.g., Provenant QVI, GLEIF Root).
- `well-known-assets/schema/`: vLEI credential schemas.
- `well-known-assets/witness/`: Witness inception events and endpoints.
- **Generator script (`scripts/build-wellknown.py`)**: Compiles `well-known-assets/` into:
- `/.well-known/host-meta.json`: RFC 6415 machine discovery entry point.
- `/.well-known/oobi/index.json`: Full catalog inventory.
- `/.well-known/oobi/<SAID>/index.json`: Type-agnostic direct OOBI resolution.
- `/.well-known/index.html`: Human-readable landing page.
Comment thread
anwar3606 marked this conversation as resolved.
- `/oobi/<SAID>/index.json`: Legacy root mirror for backward compatibility.

### How to Update Discovery Resources

When adding or updating identifiers, witnesses, or schemas:
1. Add or edit the source files under `well-known-assets/<type>/<SAID>/index.json`.
2. Re-compile the discovery directory:
```bash
python3 scripts/build-wellknown.py --host https://provenant.net
```
3. Commit both the updated source in `well-known-assets/` and the compiled files in `.well-known/` and `oobi/`.

---

## 4. Local Development

### Prerequisites

Expand All @@ -95,13 +124,13 @@ utils/website-contact-form/

---

## 4. Deployment & CI/CD
## 5. Deployment & CI/CD

Deployment is fully automated through GitHub Actions (`.github/workflows/deploy.yml`):

- **Trigger**: Every push to the default branch (`main`) (or a manual `workflow_dispatch`).
- **Build**: Compiles Jekyll assets with `bundle exec jekyll build --destination ./_site`.
- **Deploy**: Packages and uploads the `_site/` directory to GitHub Pages using `actions/deploy-pages`.
- **Deploy**: Packages and uploads the `_site/` directory to GitHub Pages using `actions/deploy-pages` (with `include-hidden-files: true` to publish `/.well-known`).

### DNS Configuration (Route 53)

Expand Down
3 changes: 3 additions & 0 deletions _config.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,12 +8,15 @@ permalink: pretty

exclude:
- README.md
- WELL-KNOWN.md
- Gemfile
- Gemfile.lock
- _site
- vendor
- .sass-cache
- .jekyll-cache
- scripts
- well-known-assets

include:
- ".well-known"
Expand Down
Loading