ALT-F4-LLC · hbjydev · May 30, 2025 · May 30, 2025 · May 30, 2025 · May 30, 2025
diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml
@@ -0,0 +1,33 @@
+name: docs
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: withastro/action@v3
+        with:
+          path: docs
+          package-manager: bun
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    if: github.ref == 'refs/heads/main'
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4
diff --git a/docs/.gitignore b/docs/.gitignore
@@ -0,0 +1,21 @@
+# build output
+dist/
+# generated types
+.astro/
+
+# dependencies
+node_modules/
+
+# logs
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+
+# environment variables
+.env
+.env.production
+
+# macOS-specific files
+.DS_Store
diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,54 @@
+# Starlight Starter Kit: Basics
+
+[![Built with Starlight](https://astro.badg.es/v2/built-with-starlight/tiny.svg)](https://starlight.astro.build)
+
+```
+bun create astro@latest -- --template starlight
+```
+
+[![Open in StackBlitz](https://developer.stackblitz.com/img/open_in_stackblitz.svg)](https://stackblitz.com/github/withastro/starlight/tree/main/examples/basics)
+[![Open with CodeSandbox](https://assets.codesandbox.io/github/button-edit-lime.svg)](https://codesandbox.io/p/sandbox/github/withastro/starlight/tree/main/examples/basics)
+[![Deploy to Netlify](https://www.netlify.com/img/deploy/button.svg)](https://app.netlify.com/start/deploy?repository=https://github.com/withastro/starlight&create_from_path=examples/basics)
+[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fwithastro%2Fstarlight%2Ftree%2Fmain%2Fexamples%2Fbasics&project-name=my-starlight-docs&repository-name=my-starlight-docs)
+
+> 🧑‍🚀 **Seasoned astronaut?** Delete this file. Have fun!
+
+## 🚀 Project Structure
+
+Inside of your Astro + Starlight project, you'll see the following folders and files:
+
+```
+.
+├── public/
+├── src/
+│   ├── assets/
+│   ├── content/
+│   │   ├── docs/
+│   └── content.config.ts
+├── astro.config.mjs
+├── package.json
+└── tsconfig.json
+```
+
+Starlight looks for `.md` or `.mdx` files in the `src/content/docs/` directory. Each file is exposed as a route based on its file name.
+
+Images can be added to `src/assets/` and embedded in Markdown with a relative link.
+
+Static assets, like favicons, can be placed in the `public/` directory.
+
+## 🧞 Commands
+
+All commands are run from the root of the project, from a terminal:
+
+| Command                   | Action                                           |
+| :------------------------ | :----------------------------------------------- |
+| `bun install`             | Installs dependencies                            |
+| `bun dev`             | Starts local dev server at `localhost:4321`      |
+| `bun build`           | Build your production site to `./dist/`          |
+| `bun preview`         | Preview your build locally, before deploying     |
+| `bun astro ...`       | Run CLI commands like `astro add`, `astro check` |
+| `bun astro -- --help` | Get help using the Astro CLI                     |
+
+## 👀 Want to learn more?
+
+Check out [Starlight’s docs](https://starlight.astro.build/), read [the Astro documentation](https://docs.astro.build), or jump into the [Astro Discord server](https://astro.build/chat).
diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs
@@ -0,0 +1,28 @@
+// @ts-check
+import { defineConfig } from 'astro/config';
+import starlight from '@astrojs/starlight';
+
+// https://astro.build/config
+export default defineConfig({
+  site: 'https://alt-f4-llc.github.io',
+  base: 'vorpal',
+	integrations: [
+		starlight({
+			title: 'Vorpal',
+      editLink: {
+        baseUrl: 'https://github.com/withastro/starlight/edit/main/docs/',
+      },
+			social: [{ icon: 'github', label: 'GitHub', href: 'https://github.com/ALT-F4-LLC/vorpal' }],
+			sidebar: [
+				{
+					label: 'Guides',
+					autogenerate: { directory: 'guides' },
+				},
+				{
+					label: 'Reference',
+					autogenerate: { directory: 'reference' },
+				},
+			],
+		}),
+	],
+});
diff --git a/docs/bun.lock b/docs/bun.lock
diff --git a/docs/package.json b/docs/package.json
@@ -0,0 +1,17 @@
+{
+  "name": "docs",
+  "type": "module",
+  "version": "0.0.1",
+  "scripts": {
+    "dev": "astro dev",
+    "start": "astro dev",
+    "build": "astro build",
+    "preview": "astro preview",
+    "astro": "astro"
+  },
+  "dependencies": {
+    "@astrojs/starlight": "^0.34.3",
+    "astro": "^5.6.1",
+    "sharp": "^0.32.5"
+  }
+}
diff --git a/docs/public/favicon.svg b/docs/public/favicon.svg
diff --git a/docs/src/assets/houston.webp b/docs/src/assets/houston.webp
diff --git a/docs/src/content.config.ts b/docs/src/content.config.ts
@@ -0,0 +1,7 @@
+import { defineCollection } from 'astro:content';
+import { docsLoader } from '@astrojs/starlight/loaders';
+import { docsSchema } from '@astrojs/starlight/schema';
+
+export const collections = {
+	docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }),
+};
diff --git a/docs/src/content/docs/guides/hello-vorpal.mdx b/docs/src/content/docs/guides/hello-vorpal.mdx
@@ -0,0 +1,10 @@
+---
+title: Hello, Vorpal!
+description: A guide showing you how to build your first artifact with Vorpal.
+---
+
+import { Aside } from '@astrojs/starlight/components';
+
+<Aside>
+Before following this guide, you should [install Vorpal](./install.mdx).
+</Aside>
diff --git a/docs/src/content/docs/guides/install.mdx b/docs/src/content/docs/guides/install.mdx
@@ -0,0 +1,95 @@
+---
+title: Installation
+description: A guide telling you how to go about installing Vorpal.
+sidebar:
+  order: -1
+---
+
+import { Aside, FileTree, Tabs, TabItem } from '@astrojs/starlight/components';
+
+<Aside>
+Eventually, Vorpal will have an installation script that will handle this for
+you! Keep an eye on our GitHub
+</Aside>
+
+This guide will walk you through installing Vorpal.
+
+## Prerequisites
+
+<Tabs>
+  <TabItem label="Linux">    
+    - [Bubblewrap](https://github.com/containers/bubblewrap)
+    - [Docker](https://docs.docker.com/get-started/get-docker/) and the `buildx` plugin
+    - `curl`
+  </TabItem>
+
+  <TabItem label="macOS">
+    - [Bubblewrap](https://github.com/containers/bubblewrap)
+    - [Docker](https://docs.docker.com/get-started/get-docker/) and the `buildx` plugin
+  </TabItem>
+</Tabs>
+
+## Setting up the `/var/lib/vorpal` directory
+
+Vorpal requires that you have a directory (`/var/lib/vorpal`) created ahead of
+time with a specific structure so it can persist built binaries and build
+sources to the disk.
+
+<FileTree>
+- /var/lib/vorpal/
+  - store/
+    - artifact/
+      - alias/ a set of name-path links to built versions of artifacts
+      - archive/ where your sources are stored, compressed with zstandard
+      - config/ the configurations generated by the sdk that tells vorpal how to build your artifacts
+      - output/ your binary output artifacts (the built results of your artifact definitions)
+  - sandbox/ an ephemeral environment where your builds happen
+  - keys/ the home of your cryptographic key matter
+</FileTree>
+
+You can set this filesystem structure up with three simple commands (though
+you'll need root, so either `sudo su` beforehand or prefix each command with
+`sudo`!)
+
+```shell title="Setting up Vorpal's filesystem hierarchy"
+mkdir -pv /var/lib/vorpal/{key,sandbox,store}
+mkdir -pv /var/lib/vorpal/store/artifact/{alias,archive,config,output}
+chown -R $(id -u):$(id -g) /var/lib/vorpal
+```
+
+## Install
+
+Now you've correctly set up your `/var/lib/vorpal` directory, you can install
+the Vorpal binary itself and set up the cryptographic keys used for builds.
+
+### From a binary release
+
+Vorpal distributes a nightly binary release over on GitHub. To install it to
+`/usr/local/bin`, you can run the following:
+
+```bash title="Installing Vorpal's binary distribution"
+export VORPAL_VERSION="nightly"
+export VORPAL_ARCH="x86_64" # either x86_64 or aarch64
+export VORPAL_PLATFORM="linux" # either linux or darwin
+curl -L "https://github.com/ALT-F4-LLC/vorpal/releases/download/$VORPAL_VERSION/vorpal-${VORPAL_ARCH}-${VORPAL_PLATFORM}.tar.gz" -o /tmp/vorpal.tar.gz
+tar -xf /tmp/vorpal.tar.gz -C /usr/local/bin
+rm vorpal.tar.gz
+```
+
+### From source
+
+TODO
+
+## Post-install
+
+Now you've installed Vorpal, the last step to perform is to create some
+cryptographic keys to sign your artifacts & sources with. **This is required.**
+If you do not run this, you will not be able to use the tool.
+
+To create the keys, just run the following:
+
+```bash
+vorpal system keys generate
+```
+
+That's it! You're ready to manage your software lifecycle with Vorpal.
diff --git a/docs/src/content/docs/index.mdx b/docs/src/content/docs/index.mdx
@@ -0,0 +1,44 @@
+---
+title: Vorpal
+description: Manage your entire software supply chain with one tool.
+template: splash
+hero:
+  tagline: Manage your entire software supply chain with one tool.
+  image:
+    file: ../../assets/houston.webp
+  actions:
+    - text: Install Vorpal
+      link: /vorpal/guides/install/
+      icon: right-arrow
+    - text: Learn more
+      link: /vorpal/reference/
+      icon: external
+      variant: minimal
+---
+
+import { Card, CardGrid } from '@astrojs/starlight/components';
+
+## Features
+
+<CardGrid>
+	<Card title="Reproducible builds" icon="puzzle">
+		Thanks to the sandboxed nature of artifacts in Vorpal, builds are entirely
+    reproducible from the get-go. Be rid of pesky _works on my machine!_
+    problems.
+	</Card>
+	<Card title="Ship your code" icon="rocket">
+		Vorpal provides a registry component that can be used to ship code
+    throughout your infrastructure, whether that's the public registry, or your
+    own securely self-hosted one.
+	</Card>
+	<Card title="Secrets supported!" icon="setting">
+		Vorpal comes with powerful build-time secrets injection out of the box. Use
+    the official implementation or a third-party one for whatever secrets
+    platform you use.
+	</Card>
+	<Card title="Verify everything" icon="approve-check-circle">
+		Built with attestations & signing in mind, Vorpal provides the ability to
+    verify the source and artifacts of your builds came from a trusted host, and
+    was not tampered with.
+	</Card>
+</CardGrid>
diff --git a/docs/src/content/docs/reference/example.md b/docs/src/content/docs/reference/example.md
@@ -0,0 +1,11 @@
+---
+title: Example Reference
+description: A reference page in my new Starlight docs site.
+---
+
+Reference pages are ideal for outlining how things work in terse and clear terms.
+Less concerned with telling a story or addressing a specific use case, they should give a comprehensive outline of what you're documenting.
+
+## Further reading
+
+- Read [about reference](https://diataxis.fr/reference/) in the Diátaxis framework
diff --git a/docs/tsconfig.json b/docs/tsconfig.json
@@ -0,0 +1,5 @@
+{
+  "extends": "astro/tsconfigs/strict",
+  "include": [".astro/types.d.ts", "**/*"],
+  "exclude": ["dist"]
+}