Initial commit

.dockerignore

@@ -0,0 +1,22 @@
+.git
+.gitignore
+.github
+node_modules
+dist
+.astro
+.output
+.vercel
+.netlify
+.env
+.env.*
+!.env.example
+*.log
+npm-debug.log*
+.DS_Store
+.vscode
+.idea
+coverage
+docker-compose*.yml
+Dockerfile
+.dockerignore
+README*.md

.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

.vscode/extensions.json

@@ -0,0 +1,4 @@
+{
+  "recommendations": ["astro-build.astro-vscode"],
+  "unwantedRecommendations": []
+}

.vscode/launch.json

@@ -0,0 +1,11 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "command": "./node_modules/.bin/astro dev",
+      "name": "Development server",
+      "request": "launch",
+      "type": "node-terminal"
+    }
+  ]
+}

AGENTS.md

@@ -0,0 +1,22 @@
+## Development
+
+When starting the dev server, use background mode:
+
+```
+astro dev --background
+```
+
+Manage the background server with `astro dev stop`, `astro dev status`, and `astro dev logs`.
+
+## Documentation
+
+Full documentation: https://docs.astro.build
+
+Consult these guides before working on related tasks:
+
+- [Adding pages, dynamic routes, or middleware](https://docs.astro.build/en/guides/routing/)
+- [Working with Astro components](https://docs.astro.build/en/basics/astro-components/)
+- [Using React, Vue, Svelte, or other framework components](https://docs.astro.build/en/guides/framework-components/)
+- [Adding or managing content](https://docs.astro.build/en/guides/content-collections/)
+- [Adding styles or using Tailwind](https://docs.astro.build/en/guides/styling/)
+- [Supporting multiple languages](https://docs.astro.build/en/guides/internationalization/)

CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

Dockerfile

@@ -0,0 +1,42 @@
+# astro-docs — Astro + Starlight documentation site
+# Serves on 7701 via the Astro Node adapter (standalone). No proxy, no auth.
+
+ARG NODE_VERSION=24
+
+# ---------- base ----------
+FROM node:24-alpine AS base
+ENV NPM_CONFIG_UPDATE_NOTIFIER=false \
+    NPM_CONFIG_FUND=false \
+    NPM_CONFIG_AUDIT=false \
+    ASTRO_TELEMETRY_DISABLED=1
+WORKDIR /app
+
+# ---------- dependencies (dev + prod, for the build) ----------
+FROM base AS deps
+COPY package.json package-lock.json* ./
+RUN if [ -f package-lock.json ]; then npm ci --include=dev; else npm install --include=dev; fi
+
+# ---------- dependencies (prod only, for the runtime) ----------
+FROM base AS prod-deps
+COPY package.json package-lock.json* ./
+RUN if [ -f package-lock.json ]; then npm ci --omit=dev; else npm install --omit=dev; fi
+
+# ---------- build ----------
+FROM deps AS build
+ENV NODE_ENV=production
+COPY . .
+RUN npm run build
+
+# ---------- runtime ----------
+FROM base AS runtime
+ENV NODE_ENV=production \
+    HOST=0.0.0.0 \
+    PORT=7701
+COPY --from=prod-deps --chown=node:node /app/node_modules ./node_modules
+COPY --from=build --chown=node:node /app/dist ./dist
+COPY --from=build --chown=node:node /app/package.json ./package.json
+USER node
+EXPOSE 7701
+HEALTHCHECK --interval=30s --timeout=5s --start-period=20s --retries=3 \
+  CMD node -e "fetch('http://127.0.0.1:'+(process.env.PORT||7701)+'/').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"
+CMD ["node", "./dist/server/entry.mjs"]

README.docker.md

@@ -0,0 +1,90 @@
+# astro-docs — Docker deployment
+
+Single container. Astro + Starlight, served by the Astro Node adapter on port 7701.
+TLS, hostname routing, and auth stay with your existing nginx + Authelia.
+
+## 1. Create the app source
+
+These Docker files expect an Astro project alongside them. There isn't one yet — generate it:
+
+```bash
+npm create astro@latest astro-docs -- --template starlight
+```
+
+Copy `Dockerfile`, `.dockerignore`, and `compose.yaml` into the generated project, then add the
+Node adapter:
+
+```bash
+npx astro add node
+```
+
+## 2. Required config
+
+`astro.config.mjs` must produce a standalone server — the container runs `dist/server/entry.mjs`:
+
+```js
+import { defineConfig } from 'astro/config';
+import node from '@astrojs/node';
+import starlight from '@astrojs/starlight';
+
+export default defineConfig({
+  site: 'https://docs.example.org', // public URL served by nginx
+  output: 'server',
+  adapter: node({ mode: 'standalone' }),
+  integrations: [starlight({ title: 'astro-docs' })],
+});
+```
+
+Starlight prerenders its routes, so pages are static output; the Node server just delivers them.
+`package.json` needs `"build": "astro build"` (the Starlight template includes it).
+
+Commit `package-lock.json`. Without it the image build falls back to `npm install`, which gives
+up reproducible dependency versions.
+
+## 3. Deploy via Dockhand
+
+Dockhand expects the stack at `{DATA_DIR}/stacks/{environment}/astro-docs/compose.yaml`. Because
+this stack builds from source, the whole project has to live in that directory — Dockhand's Git
+auto-sync is the intended way to get it there.
+
+1. Push the project (app source + these Docker files) to Gitea.
+2. Create the `astro-docs` stack in Dockhand and point its Git sync at that repo, so the stack
+   directory is populated from the repo rather than by hand.
+3. Set `TZ` in Dockhand's encrypted environment editor. Do not commit a `.env` — auto-sync will
+   overwrite it. `TZ` is the only variable; everything else is fixed in `compose.yaml`.
+4. Deploy. The first run builds the image on the NAS, which takes several minutes.
+5. Verify over SSH on the NAS:
+
+```bash
+curl -I http://localhost:7701/
+```
+
+6. Point an nginx vhost at `http://<nas-ip>:7701`, and decide whether it sits behind Authelia or
+   is publicly readable.
+
+### Faster alternative: build off-NAS
+
+Building on NAS hardware is slow and memory-hungry. To build on your workstation and push to
+Gitea's registry instead, drop the `build:` block from `compose.yaml` and set
+`image: <gitea-host>/<user>/astro-docs:latest`. Dockhand then only pulls, and the stack
+directory needs nothing but `compose.yaml`.
+
+## 4. Publishing content changes
+
+The image holds a build artifact, so edits under `src/content/docs/` go live only after a
+rebuild — push to Gitea, then trigger Dockhand's rebuild/redeploy on the stack.
+
+## Notes
+
+- No `name:` or `container_name:` — they collide across Dockhand environments.
+- No bind mounts: this stack is stateless, so nothing survives or needs to survive a redeploy.
+- `platform: linux/amd64` is pinned for Synology x86 hardware. Remove that line on ARM models.
+- Runs as the non-root `node` user, read-only root filesystem, `/tmp` on tmpfs.
+- The health check uses Node's built-in `fetch`; the image ships no curl or wget.
+- Base image is `node:24-bookworm-slim` rather than Alpine, because Starlight's image
+  optimization pulls in `sharp`, which is less trouble on glibc.
+
+## Not verified
+
+Neither Node nor Docker is available in the environment where these files were written, so
+nothing here has been built or run. The first Dockhand deploy is the first real test.

README.md

@@ -0,0 +1,49 @@
+# Starlight Starter Kit: Basics
+
+[![Built with Starlight](https://astro.badg.es/v2/built-with-starlight/tiny.svg)](https://starlight.astro.build)
+
+```
+npm create astro@latest -- --template starlight
+```
+
+> 🧑‍🚀 **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                                           |
+| :------------------------ | :----------------------------------------------- |
+| `npm install`             | Installs dependencies                            |
+| `npm run dev`             | Starts local dev server at `localhost:4321`      |
+| `npm run build`           | Build your production site to `./dist/`          |
+| `npm run preview`         | Preview your build locally, before deploying     |
+| `npm run astro ...`       | Run CLI commands like `astro add`, `astro check` |
+| `npm run 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).

astro.config.mjs

@@ -0,0 +1,32 @@
+// @ts-check
+import { defineConfig } from 'astro/config';
+import starlight from '@astrojs/starlight';
+import node from '@astrojs/node';
+
+// https://astro.build/config
+export default defineConfig({
+	site: 'https://doc.brendonconnett.com',
+	output: 'server', // or 'hybrid'
+  	adapter: node({
+    	mode: 'standalone', // or 'middleware'
+  	}),
+	integrations: [
+		starlight({
+			title: 'My Docs',
+			social: [{ icon: 'github', label: 'GitHub', href: 'https://github.com/withastro/starlight' }],
+			sidebar: [
+				{
+					label: 'Guides',
+					items: [
+						// Each item here is one entry in the navigation menu.
+						{ label: 'Example Guide', slug: 'guides/example' },
+					],
+				},
+				{
+					label: 'Reference',
+					items: [{ autogenerate: { directory: 'reference' } }],
+				},
+			],
+		}),
+	],
+});

compose.yaml

@@ -0,0 +1,31 @@
+services:
+  site:
+    build:
+      context: .
+      target: runtime
+      args:
+        NODE_VERSION: "24"
+    image: astro-docs:latest
+    platform: linux/amd64
+    restart: unless-stopped
+    ports:
+      - "7701:7701"
+    environment:
+      TZ: ${TZ:-America/Los_Angeles}
+      NODE_ENV: production
+      HOST: 0.0.0.0
+      PORT: "7701"
+    read_only: true
+    tmpfs:
+      - /tmp
+    security_opt:
+      - no-new-privileges:true
+    deploy:
+      resources:
+        limits:
+          memory: 512M
+    logging:
+      driver: json-file
+      options:
+        max-size: "10m"
+        max-file: "3"

package.json

@@ -0,0 +1,19 @@
+{
+  "name": "astro-docs",
+  "type": "module",
+  "version": "0.0.1",
+  "scripts": {
+    "dev": "astro dev",
+    "start": "astro dev",
+    "build": "astro build",
+    "preview": "astro preview",
+    "astro": "astro"
+  },
+  "dependencies": {
+    "@astrojs/node": "^11.1.4",
+    "@astrojs/starlight": "^0.41.7",
+    "astro": "^7.1.6",
+    "full-icu": "^1.6.0",
+    "sharp": "^0.35.3"
+  }
+}

public/favicon.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 128 128"><path fill-rule="evenodd" d="M81 36 64 0 47 36l-1 2-9-10a6 6 0 0 0-9 9l10 10h-2L0 64l36 17h2L28 91a6 6 0 1 0 9 9l9-10 1 2 17 36 17-36v-2l9 10a6 6 0 1 0 9-9l-9-9 2-1 36-17-36-17-2-1 9-9a6 6 0 1 0-9-9l-9 10v-2Zm-17 2-2 5c-4 8-11 15-19 19l-5 2 5 2c8 4 15 11 19 19l2 5 2-5c4-8 11-15 19-19l5-2-5-2c-8-4-15-11-19-19l-2-5Z" clip-rule="evenodd"/><path d="M118 19a6 6 0 0 0-9-9l-3 3a6 6 0 1 0 9 9l3-3Zm-96 4c-2 2-6 2-9 0l-3-3a6 6 0 1 1 9-9l3 3c3 2 3 6 0 9Zm0 82c-2-2-6-2-9 0l-3 3a6 6 0 1 0 9 9l3-3c3-2 3-6 0-9Zm96 4a6 6 0 0 1-9 9l-3-3a6 6 0 1 1 9-9l3 3Z"/><style>path{fill:#000}@media (prefers-color-scheme:dark){path{fill:#fff}}</style></svg>

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() }),
+};

src/content/docs/guides/example.md

@@ -0,0 +1,11 @@
+---
+title: Example Guide
+description: A guide in my new Starlight docs site.
+---
+
+Guides lead a user through a specific task they want to accomplish, often with a sequence of steps.
+Writing a good guide requires thinking about what your users are trying to do.
+
+## Further reading
+
+- Read [about how-to guides](https://diataxis.fr/how-to-guides/) in the Diátaxis framework

src/content/docs/index.mdx

@@ -0,0 +1,40 @@
+---
+title: Welcome to Starlight
+description: Get started building your docs site with Starlight.
+template: splash # Remove or comment out this line to display the site sidebar on this page.
+hero:
+  tagline: Congrats on setting up a new Starlight project!
+  image:
+    file: ../../assets/houston.webp
+  actions:
+    - text: Example Guide
+      link: /guides/example/
+      icon: right-arrow
+    - text: Read the Starlight docs
+      link: https://starlight.astro.build
+      icon: external
+      variant: minimal
+---
+
+import { Card, CardGrid } from '@astrojs/starlight/components';
+
+## Next steps
+
+<CardGrid stagger>
+	<Card title="Update content" icon="pencil">
+		Edit `src/content/docs/index.mdx` to see this page change.
+	</Card>
+	<Card title="Change page layout" icon="document">
+		Delete `template: splash` in `src/content/docs/index.mdx` to display a
+		sidebar on this page.
+	</Card>
+	<Card title="Add new content" icon="add-document">
+		Add Markdown or MDX files to `src/content/docs` to create new pages.
+	</Card>
+	<Card title="Configure your site" icon="setting">
+		Edit your `sidebar` and other config in `astro.config.mjs`.
+	</Card>
+	<Card title="Read the docs" icon="open-book">
+		Learn more in [the Starlight Docs](https://starlight.astro.build/).
+	</Card>
+</CardGrid>

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

tsconfig.json

@@ -0,0 +1,5 @@
+{
+  "extends": "astro/tsconfigs/strict",
+  "include": [".astro/types.d.ts", "**/*"],
+  "exclude": ["dist"]
+}