web site first draft

.github/workflows/website.yml

@@ -0,0 +1,37 @@
+name: Project website
+
+on:
+  pull_request:
+    paths:
+      - 'website/**'
+      - '.github/workflows/website.yml'
+  push:
+    branches: [main]
+    paths:
+      - 'website/**'
+      - '.github/workflows/website.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: website-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: website
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: npm
+          cache-dependency-path: website/package-lock.json
+      - run: npm ci
+      - run: npm run build
+      - run: npm run check:links

website/.gitignore

@@ -0,0 +1,3 @@
+node_modules/
+dist/
+.astro/

website/AGENTS.md

@@ -0,0 +1,10 @@
+# Project website
+
+This is the public informational VAuthenticator website, built with Astro for GitHub Pages. Keep website code and content here; do not change the authorization server, management UI, or Helm runtime code as part of website work.
+
+- Pages are static. Markdown pages share `src/layouts/DocsLayout.astro`.
+- Prefix internal links with the configured `/vauthenticator/` base. Use `sitePath` in Astro components.
+- Keep capability claims grounded in the project code and docs. Label incomplete installation guidance clearly.
+- `npm run build` and `npm run check:links` validate the production site.
+- Do not edit `dist`, `.astro`, or `node_modules` by hand.
+- The GitHub Pages address also hosts the Helm repository. Publishing must preserve `index.yaml` and existing chart downloads on `gh-pages`.

website/CONTEXT.md

@@ -0,0 +1,12 @@
+# VAuthenticator Project Website
+
+The public project website introduces VAuthenticator to people considering using it in their applications. Its initial audience is prospective adopters; contributor content is a topic for later discussion.
+
+## Language
+
+**Prospective adopter**:
+A developer or team considering VAuthenticator for authentication and authorization in their applications.
+_Avoid_: User (ambiguous with a person signing in through VAuthenticator)
+
+**Contributor**:
+A person who helps develop or maintain the VAuthenticator project or its documentation.

website/README.md

@@ -0,0 +1,34 @@
+# VAuthenticator website
+
+An incremental, static Astro website for people considering VAuthenticator. This project is independent of the authorization server and management UI.
+
+## Run locally
+
+Use Node.js 22.12 or newer. From this directory:
+
+```sh
+npm ci
+npm run dev
+```
+
+Open http://localhost:4321/.
+
+## Build and preview
+
+```sh
+npm run build
+npm run check:links
+npm run preview
+```
+
+The build generates static files in `dist/`, and the link check verifies that internal URLs work under the `/vauthenticator/` GitHub Pages base path. The repository workflow publishes successful builds while preserving the Helm repository files already hosted on `gh-pages`.
+
+## Content
+
+- `src/pages/index.astro`: product homepage.
+- `src/pages/features/`: Markdown feature summaries.
+- `src/pages/install/`: installation overviews linking to project setup and configuration documentation.
+- `src/layouts/`: shared website and documentation layouts.
+- `src/styles/global.css`: responsive styling.
+
+Installation pages describe the setup path and link to detailed instructions for the authorization server, management UI, and Helm charts.

website/astro.config.mjs

@@ -0,0 +1,8 @@
+import { defineConfig } from 'astro/config';
+
+export default defineConfig({
+  site: 'https://mrflick72.github.io',
+  base: '/vauthenticator',
+  output: 'static',
+  trailingSlash: 'always',
+});

website/docs/project-website-design.md

@@ -0,0 +1,49 @@
+# Project website design
+
+This document captures decisions from the grill-with-docs session and the first version of the website.
+
+## Agreed scope
+
+- Publish an informational VAuthenticator website through GitHub Pages.
+- Focus the first version on prospective adopters. Discuss contributor sections later.
+- Help visitors understand whether VAuthenticator fits their needs, then provide a clear path to getting started.
+- Include a general introduction, dedicated feature pages, and installation guides.
+- Prioritize local Docker installation for evaluation, followed by a separate Kubernetes installation guide using Helm.
+- The local installation guide succeeds when the authorization server and management UI are running and the local tenant is provisioned.
+- Feature pages explain each capability, when it is useful, and a small example, with links to detailed configuration documentation.
+- Installation guides provide the complete steps needed to reach the documented working setup.
+- Use a product-style homepage with a project introduction, architecture overview, feature highlights, and a prominent Get started action.
+- Use documentation-style navigation on feature and installation pages.
+- Publish the website at the existing GitHub Pages address, `https://mrflick72.github.io/vauthenticator`.
+- Preserve the existing Helm chart repository index and chart downloads at that address so existing Helm repository commands continue to work.
+- Organize feature pages into OAuth2 and OpenID Connect; accounts and password lifecycle; multi-factor authentication; administration through the management UI; and token customization and infrastructure options.
+- Keep architecture and installation as separate site sections.
+- Build the website with Astro in a dedicated root-level `website/` directory.
+- Author feature pages and installation guides in Markdown.
+
+## Delivery
+
+- Open a GitHub issue containing the final scope and decisions when the grilling session concludes.
+- Keep all website code on a dedicated branch before integration. The branch for this work is `feat/project-website`.
+
+## First increment
+
+- Deliver a small, usable Astro site: product homepage, architecture overview, five feature summaries, and local/Kubernetes installation landing pages.
+- Use English initially, matching the existing project documentation.
+- Use a midnight and electric-blue hero, with light content sections and a consistent light documentation layout. Keep the existing page structure, use restrained hover transitions, and respect reduced-motion preferences.
+- Present installation pages as setup overviews linking to detailed project documentation. Describe the supported setup accurately without draft labels or promises of future walkthroughs.
+- Build and check the site on pull requests. Publish website changes merged to `main`, with a manual publishing trigger as well.
+- Keep the existing `gh-pages` publishing source and update only website-owned paths. Preserve Helm's `index.yaml` and packaged charts.
+- Keep server, management UI, and chart implementations outside this increment.
+
+## Follow-up increments
+
+- Provide a verified local quick-start using released Docker images, covering a running server, management UI, and provisioned local tenant.
+- Expand feature examples and Kubernetes installation instructions.
+- Revisit contributor content after the adopter experience is useful.
+
+## Existing setup evidence
+
+The current local setup documentation describes infrastructure services, local hostnames, tenant provisioning, email verification, and MFA before signing into the management UI. The website installation guide needs a coherent path through these steps.
+
+Reference: [Local tenant installer](../../auth-server/local/readme.md).

website/docs/project-website-issue.md

@@ -0,0 +1,41 @@
+# Build an incremental VAuthenticator project website with Astro and GitHub Pages
+
+## Goal
+
+Give prospective adopters a public website that explains VAuthenticator, helps them evaluate its capabilities, and provides a path to installation. Ship a first version and improve it incrementally.
+
+## Decisions from the grill-with-docs session
+
+- Audience: prospective adopters first; contributor content comes later.
+- Visitor journey: understand the project and assess fit, then get started.
+- Homepage: product-style introduction, architecture overview, feature highlights, and a prominent Get started link.
+- Inner pages: documentation-style navigation, authored in Markdown.
+- Technology and ownership: Astro in a dedicated root-level `website/` directory, independent of the authorization server, admin UI, and Helm charts.
+- Feature pages: OAuth2/OIDC; accounts and password lifecycle; MFA; administration through the management UI; token customization and infrastructure options.
+- Feature depth: explain each capability, its use cases, and a small example; link to detailed configuration documentation.
+- Installation: local Docker first, Kubernetes with Helm second.
+- Local setup finish line: a working authorization server, management UI, and provisioned local tenant.
+- Desired eventual quick-start: released Docker images rather than source builds; a new verified Compose example is needed.
+- Hosting: reuse https://mrflick72.github.io/vauthenticator/ and preserve the Helm chart repository index and downloads at that URL.
+- All website code must be developed on a dedicated branch before integration. Website branch: `feat/project-website`.
+
+## Increment 1: first website version
+
+- [ ] Product homepage, architecture overview, and responsive navigation.
+- [ ] Five feature pages with concise, accurate summaries.
+- [ ] Local and Kubernetes installation overviews that describe the setup path and link to detailed instructions.
+- [ ] Independent Astro build and local development instructions.
+- [ ] GitHub Actions build validation and publishing to the existing `gh-pages` branch without deleting Helm artifacts.
+- [ ] Verify production build, internal links/assets under `/vauthenticator/`, and desktop/mobile layouts.
+
+English and a responsive light theme are initial implementation defaults. Increment 1 does not claim to supply a completed Docker quick-start or exhaustive feature documentation.
+
+## Follow-up increments
+
+- [ ] Add and validate the image-based Docker quick-start through local tenant provisioning.
+- [ ] Expand feature examples and Kubernetes installation guidance.
+- [ ] Discuss contributor-focused sections.
+
+## Acceptance criteria
+
+The first version can be served as a static site under `/vauthenticator/`, provides useful introductory content, and has no dead internal navigation. Publishing preserves existing Helm repository functionality. No runtime code changes to `auth-server`, `management-ui`, or Helm templates are required for this increment.