Docs First Release

.github/workflows/ci.yml

@@ -2,6 +2,7 @@ name: CI
 
 on:
   push:
+    branches: [main]
   pull_request:
   workflow_dispatch: {}
 

.github/workflows/docs.yml

@@ -0,0 +1,56 @@
+name: docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - ".github/workflows/docs.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    env:
+      BASE_PATH: /${{ github.event.repository.name }}/
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version: "24"
+          cache: npm
+          cache-dependency-path: docs/package-lock.json
+
+      - uses: actions/configure-pages@v5
+
+      - name: Install docs dependencies
+        working-directory: docs
+        run: npm ci
+
+      - name: Build site
+        working-directory: docs
+        run: npm run build
+
+      - uses: actions/upload-pages-artifact@v5
+        with:
+          path: docs/.vitepress/dist
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v5

.gitignore

@@ -32,9 +32,13 @@ dependency-reduced-pom.xml
 *.log
 .env
 .env.*
-harness/configs/.env
-!harness/configs/.env.example
+!.env.example
 
 ### Conformance / temp ###
 server/conformance-run.log
 **/node_modules/
+
+### Docs ###
+/docs/node_modules/
+/docs/.vitepress/cache/
+/docs/.vitepress/dist/

README.md

@@ -4,8 +4,8 @@ A durable stream engine on object storage, with storage, metadata, and protocol
 
 <p align="left">
   <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="docs/assets/architecture-dark.svg">
-    <img src="docs/assets/architecture-light.svg" alt="Stream Stack architecture" width="920">
+    <source media="(prefers-color-scheme: dark)" srcset="docs/pages/assets/images/architecture-dark.svg">
+    <img src="docs/pages/assets/images/architecture-light.svg" alt="Stream Stack architecture" width="920">
   </picture>
 </p>
 
@@ -20,34 +20,48 @@ mvn clean package
 ## Quickstart
 
 ```bash
-docker compose --env-file harness/configs/minio.env \
-  -f harness/docker/docker-compose.minio.yml \
-  -f harness/docker/docker-compose.ds.yml \
+cp harness/local/.env.example harness/local/.env
+docker compose --env-file harness/local/.env \
+  -f harness/local/docker-compose.minio.yml \
+  -f harness/local/docker-compose.ds.yml \
   up -d --build
 ```
 
-Node listens on `127.0.0.1:4437`. MinIO, cluster, and topo files: [harness/README.md](harness/README.md).
+Node listens on `127.0.0.1:4437`. MinIO, cluster, AWS, and Fly: [harness/README.md](harness/README.md).
 
 ## Deployment
 
-Create data and WAL S3 buckets. Copy `harness/configs/.env.example` to `harness/configs/.env` and fill `AWS_*`, `DATA_BUCKET`, and `WAL_BUCKET`.
+Create data and WAL S3 buckets. Copy `harness/aws/.env.example` to `harness/aws/.env` and fill `AWS_*`, `DATA_BUCKET`, and `WAL_BUCKET`.
 
 ```bash
-docker compose --env-file harness/configs/.env \
-  -f harness/docker/docker-compose.ds.yml \
+docker compose --env-file harness/aws/.env \
+  -f harness/aws/docker-compose.ds.yml \
   up -d --build
 ```
 
-Swap `docker-compose.ds.yml` for `docker-compose.s2.yml` to run S2 facade. Node listens on `127.0.0.1:4437`.
+Swap `docker-compose.ds.yml` for `docker-compose.s2.yml` to run S2 facade. Node listens on `127.0.0.1:4437`. Three nodes: `harness/aws/docker-compose.cluster.ds.yml`.
 
-Multi-Node (3 nodes) cluster (ports 4437–4439):
+Multi-node (3 nodes) local cluster (ports 4437–4439):
 
 ```bash
-docker compose --env-file harness/configs/.env \
-  -f harness/docker/docker-compose.cluster.ds.yml \
+docker compose --env-file harness/local/.env \
+  -f harness/local/docker-compose.minio.yml \
+  -f harness/local/docker-compose.cluster.ds.yml \
   up -d --build
 ```
 
+## Documentation
+
+The documentation source is in [`docs/pages`](docs/pages).
+
+```bash
+cd docs
+npm install
+npm run dev
+```
+
+Open http://localhost:5173.
+
 ## License
 
 Apache 2.0.

docs/.vitepress/config.mts

@@ -0,0 +1,74 @@
+import { defineConfig } from 'vitepress';
+
+function sideItem(label: string, link: string, path: string) {
+  return {
+    text: `<span class="ss-side-ico" aria-hidden="true"><svg viewBox="0 0 24 24" fill="none">${path}</svg></span>${label}`,
+    link,
+  };
+}
+
+export default defineConfig({
+  title: 'Stream Stack',
+  description: 'A durable stream engine on object storage.',
+  base: process.env.BASE_PATH ?? '/',
+  cleanUrls: true,
+  appearance: 'force-dark',
+  srcDir: 'pages',
+  vite: {
+    publicDir: 'assets',
+  },
+  markdown: {
+    theme: 'github-dark',
+  },
+  head: [
+    ['link', { rel: 'icon', href: '/images/favicon.ico', sizes: 'any' }],
+    ['link', { rel: 'icon', type: 'image/svg+xml', href: '/images/logo.svg' }],
+    [
+      'script',
+      {},
+      `(function(){function m(h,a){var n=parseInt(h.slice(1),16),r=n>>16,g=n>>8&255,b=n&255;return'#'+[r,g,b].map(function(c){c=Math.round(c+(255-c)*a);return c.toString(16).padStart(2,'0')}).join('')}try{var h=localStorage.getItem('ss-accent-hex-v2');if(h&&/^#[0-9a-fA-F]{6}$/.test(h)){var s=document.documentElement.style;var n=parseInt(h.slice(1),16);s.setProperty('--vp-c-brand-1',h);s.setProperty('--vp-c-brand-2',m(h,.18));s.setProperty('--vp-c-brand-3',m(h,.36));s.setProperty('--vp-c-brand-soft','rgb('+(n>>16)+' '+(n>>8&255)+' '+(n&255)+' / 0.14)')}}catch(e){}})();`,
+    ],
+  ],
+  themeConfig: {
+    siteTitle: false,
+    nav: [
+      { text: 'Home', link: '/' },
+      { text: 'Docs', link: '/introduction' },
+    ],
+    sidebar: [
+      sideItem(
+        'Introduction',
+        '/introduction',
+        '<path d="M6 4.5h9.5A2.5 2.5 0 0 1 18 7v13H8.5A2.5 2.5 0 0 0 6 17.5V4.5Z" stroke="currentColor" stroke-width="1.7"/><path d="M6 4.5A2.5 2.5 0 0 0 3.5 7v10.5A2.5 2.5 0 0 1 6 17.5" stroke="currentColor" stroke-width="1.7"/>',
+      ),
+      sideItem(
+        'Quickstart',
+        '/quickstart',
+        '<path d="M8 6.5v11l10-5.5L8 6.5Z" stroke="currentColor" stroke-width="1.7" stroke-linejoin="round"/>',
+      ),
+      sideItem(
+        'Benchmark',
+        '/benchmark',
+        '<path d="M3 16l5.2-5.2 3.6 3.6L21 5" stroke="currentColor" stroke-width="1.7" stroke-linecap="round" stroke-linejoin="round"/>',
+      ),
+      sideItem(
+        'Deployment',
+        '/deployment',
+        '<path d="M12 3v10M8 7l4-4 4 4" stroke="currentColor" stroke-width="1.7" stroke-linecap="round" stroke-linejoin="round"/><path d="M5 14.5v3A2.5 2.5 0 0 0 7.5 20h9a2.5 2.5 0 0 0 2.5-2.5v-3" stroke="currentColor" stroke-width="1.7" stroke-linecap="round"/>',
+      ),
+    ],
+    search: {
+      provider: 'local',
+    },
+    socialLinks: [
+      { icon: 'github', link: 'https://github.com/Modak-Labs/streamstack' },
+    ],
+    outline: {
+      level: [1, 3],
+      label: 'On this page',
+    },
+    footer: {
+      copyright: '© 2026 Modak Labs. Apache 2.0.',
+    },
+  },
+});