diff --git a/.gitignore b/.gitignore index f8546bb..31bebf6 100644 --- a/.gitignore +++ b/.gitignore @@ -3,6 +3,9 @@ dist/ # generated types .astro/ +# d2 diagrams +public/d2/ + # dependencies node_modules/ diff --git a/.mise.toml b/.mise.toml index c3e7b38..17ef45f 100644 --- a/.mise.toml +++ b/.mise.toml @@ -1,5 +1,6 @@ [tools] pnpm = "9.1.0-0" +"ubi:terrastruct/d2" = "latest" [settings] idiomatic_version_file_enable_tools = ["node"] diff --git a/astro.config.mjs b/astro.config.mjs index 9c9eccf..f882c3a 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -7,142 +7,151 @@ import moduleReferencePlugin from "./src/plugins/moduleReferencePlugin"; import githubActionReferencePlugin from "./src/plugins/githubActionReferencePlugin"; import modulesJsonGeneratorPlugin from "./src/plugins/modulesJsonGeneratorPlugin"; +import d2 from "astro-d2"; + // https://astro.build/config export default defineConfig({ site: "https://blue-build.org/", integrations: [ - starlight({ - title: "BlueBuild", - logo: { - replacesTitle: true, - dark: "./src/assets/logo-dark.svg", - light: "./src/assets/logo-light.svg", - alt: "BlueBuild. A minimal logo with a blue-billed duck holding a golden wrench in its beak.", - }, - editLink: { - baseUrl: "https://github.com/blue-build/website/edit/main/", - }, - social: [ - { icon: 'github', label: 'GitHub', href: 'https://github.com/blue-build/' }, + // icon(), + starlight({ + title: "BlueBuild", + logo: { + replacesTitle: true, + dark: "./src/assets/logo-dark.svg", + light: "./src/assets/logo-light.svg", + alt: "BlueBuild. A minimal logo with a blue-billed duck holding a golden wrench in its beak.", + }, + editLink: { + baseUrl: "https://github.com/blue-build/website/edit/main/", + }, + social: [ + { + icon: "github", + label: "GitHub", + href: "https://github.com/blue-build/", + }, + ], + sidebar: [ + { + label: "Learn", + items: [ + { + label: "Getting started", + link: "/learn/getting-started/", + }, + { + label: "Thinking like a distribution", + link: "/learn/mindset/", + }, + { + label: "Building on Universal Blue", + link: "/learn/universal-blue/", + }, + { + label: "How BlueBuild works", + link: "/learn/how/", + }, + { + label: "Troubleshooting, reporting bugs, and common issues", + link: "/learn/troubleshooting/", + }, + { + label: "Contributing", + link: "/learn/contributing/", + }, + { + label: "Scope", + link: "/learn/scope/", + }, ], - sidebar: [ - { - label: "Learn", - items: [ - { - label: "Getting started", - link: "/learn/getting-started/", - }, - { - label: "Thinking like a distribution", - link: "/learn/mindset/", - }, - { - label: "Building on Universal Blue", - link: "/learn/universal-blue/", - }, - { - label: "How BlueBuild works", - link: "/learn/how/", - }, - { - label: "Troubleshooting, reporting bugs, and common issues", - link: "/learn/troubleshooting/", - }, - { - label: "Contributing", - link: "/learn/contributing/", - }, - { - label: "Scope", - link: "/learn/scope/", - }, - ], - }, - { - label: "How-to", - autogenerate: { - directory: "how-to", - }, - }, - { - label: "Reference", - items: [ - { - label: "recipe.yml", - link: "/reference/recipe/", - }, - { - label: "blue-build/github-action", - link: "/reference/github-action/", - }, - { - label: "Module", - link: "/reference/module/", - }, - { - label: "Stages", - link: "/reference/stages/", - }, - { - label: "Modules", - autogenerate: { - directory: "reference/modules", - }, - }, - ], + }, + { + label: "How-to", + autogenerate: { + directory: "how-to", + }, + }, + { + label: "Reference", + items: [ + { + label: "recipe.yml", + link: "/reference/recipe/", + }, + { + label: "blue-build/github-action", + link: "/reference/github-action/", + }, + { + label: "Module", + link: "/reference/module/", + }, + { + label: "Stages", + link: "/reference/stages/", + }, + { + label: "Modules", + autogenerate: { + directory: "reference/modules", }, + }, ], - plugins: [ - modulesJsonGeneratorPlugin({ - moduleSources: [ - { - source: "https://api.github.com/repos/blue-build/modules/contents/modules", - }, - { - source: "https://api.github.com/repos/blue-build/cli/contents/template/templates/modules", - }, - ], - }), - moduleReferencePlugin(), - githubActionReferencePlugin({ - source: "https://raw.githubusercontent.com/blue-build/github-action/main/action.yml", - path: "reference/github-action.md", - }), - ], - customCss: [ - "@fontsource/atkinson-hyperlegible/400.css", - "@fontsource/atkinson-hyperlegible/700.css", - "@fontsource-variable/rubik", - "@fontsource/ibm-plex-mono", - "./src/styles/global.css", + }, + ], + plugins: [ + modulesJsonGeneratorPlugin({ + moduleSources: [ + { + source: + "https://api.github.com/repos/blue-build/modules/contents/modules", + }, + { + source: + "https://api.github.com/repos/blue-build/cli/contents/template/templates/modules", + }, ], - components: { - SocialIcons: "./src/components/NavLinks.astro", - Hero: "./src/components/Hero.astro", - Footer: "./src/components/Footer.astro", - Head: "./src/components/Head.astro", - Search: "./src/components/Search.astro", - Sidebar: "./src/components/Sidebar.astro", - MarkdownContent: "./src/components/MarkdownContent.astro", + }), + moduleReferencePlugin(), + githubActionReferencePlugin({ + source: + "https://raw.githubusercontent.com/blue-build/github-action/main/action.yml", + path: "reference/github-action.md", + }), + ], + customCss: [ + "@fontsource/atkinson-hyperlegible/400.css", + "@fontsource/atkinson-hyperlegible/700.css", + "@fontsource-variable/rubik", + "@fontsource/ibm-plex-mono", + "./src/styles/global.css", + ], + components: { + SocialIcons: "./src/components/NavLinks.astro", + Hero: "./src/components/Hero.astro", + Footer: "./src/components/Footer.astro", + Head: "./src/components/Head.astro", + Search: "./src/components/Search.astro", + Sidebar: "./src/components/Sidebar.astro", + MarkdownContent: "./src/components/MarkdownContent.astro", + }, + head: [ + { + tag: "script", + attrs: { + defer: true, + src: "https://eu.umami.is/script.js", + "data-website-id": "fdbab42b-cab4-4f46-b06a-172700ea1e1c", }, - head: [ - { - tag: "script", - attrs: { - defer: true, - src: "https://eu.umami.is/script.js", - "data-website-id": - "fdbab42b-cab4-4f46-b06a-172700ea1e1c", - }, - }, - ], - }) - // icon(), + }, + ], + }), + d2(), ], vite: { plugins: [tailwindcss()], }, -}); \ No newline at end of file +}); diff --git a/package.json b/package.json index 946b2f3..5e682fc 100644 --- a/package.json +++ b/package.json @@ -25,6 +25,7 @@ "@iconify-json/ri": "^1.2.5", "@tailwindcss/vite": "^4.1.4", "astro": "^5.12.3", + "astro-d2": "^0.8.0", "astro-og-canvas": "^0.4.2", "canvaskit-wasm": "^0.39.1", "sharp": "^0.34.3", diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 48cc949..0c6f078 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -50,6 +50,9 @@ importers: astro: specifier: ^5.12.3 version: 5.12.3(@types/node@22.15.2)(jiti@2.4.2)(lightningcss@1.29.2)(rollup@4.40.0)(typescript@5.8.3)(yaml@2.7.1) + astro-d2: + specifier: ^0.8.0 + version: 0.8.0(astro@5.12.3(@types/node@22.15.2)(jiti@2.4.2)(lightningcss@1.29.2)(rollup@4.40.0)(typescript@5.8.3)(yaml@2.7.1)) astro-og-canvas: specifier: ^0.4.2 version: 0.4.2(astro@5.12.3(@types/node@22.15.2)(jiti@2.4.2)(lightningcss@1.29.2)(rollup@4.40.0)(typescript@5.8.3)(yaml@2.7.1)) @@ -1292,6 +1295,12 @@ packages: resolution: {integrity: sha512-LElXdjswlqjWrPpJFg1Fx4wpkOCxj1TDHlSV4PlaRxHGWko024xICaa97ZkMfs6DRKlCguiAI+rbXv5GWwXIkg==} hasBin: true + astro-d2@0.8.0: + resolution: {integrity: sha512-vs1crOjTmYeQg+kHUymB8AhcmFRZyiQBuK1bsuMoTbX1upX3ljhny8DdvOWoiEVUBQAwlUojjwO5bB8tRo8hCw==} + engines: {node: '>=18'} + peerDependencies: + astro: '>=5.0.0' + astro-eslint-parser@0.16.3: resolution: {integrity: sha512-CGaBseNtunAV2DCpwBXqTKq8+9Tw65XZetMaC0FsMoZuLj0gxNIkbCf2QyKYScVrNOU7/ayfNdVw8ZCSHBiqCg==} engines: {node: ^14.18.0 || >=16.0.0} @@ -5291,6 +5300,13 @@ snapshots: astring@1.9.0: {} + astro-d2@0.8.0(astro@5.12.3(@types/node@22.15.2)(jiti@2.4.2)(lightningcss@1.29.2)(rollup@4.40.0)(typescript@5.8.3)(yaml@2.7.1)): + dependencies: + astro: 5.12.3(@types/node@22.15.2)(jiti@2.4.2)(lightningcss@1.29.2)(rollup@4.40.0)(typescript@5.8.3)(yaml@2.7.1) + hast-util-from-html: 2.0.3 + hast-util-to-html: 9.0.5 + unist-util-visit: 5.0.0 + astro-eslint-parser@0.16.3: dependencies: '@astrojs/compiler': 2.11.0 diff --git a/src/content/docs/learn/how.mdx b/src/content/docs/learn/how.mdx index cbe7e22..040f531 100644 --- a/src/content/docs/learn/how.mdx +++ b/src/content/docs/learn/how.mdx @@ -9,11 +9,93 @@ This page is a draft, so contents are unfinished or nonexistent. https://diataxis.fr/explanation/ -- recipe transformed into containerfile with cli - - link to recipe reference -- containerfile built -- pulls in modules - - what are modules - - you could make your own (why?) - - link to making your own modules and to modules reference -- pushed to registry +- recipe transformed into containerfile with cli + - link to recipe reference +- containerfile built +- pulls in modules + - what are modules + - you could make your own (why?) + - link to making your own modules and to modules reference +- pushed to registry + +```d2 pad=50 +direction: right +recipe: recipe.yml { + label.near: border-top-center + meta: Image metadata { + shape: sql_table + + name: string + description: string + } + base: Base image { + shape: sql_table + + base-image: oci image ref + image-version: oci image tag + } + modules: Modules { + label.near: border-top-center + files: |yaml + type: files + files: + - source: system + destination: / + | + containerfile: |yaml + type: containerfile + snippets: + - RUN echo "Hello, world!" + | + } +} +containerfile: Containerfile { + label.near: border-top-center + + from: |dockerfile + FROM ${base-image}:${image-version} AS ${name} + | + _.recipe.meta -> from: Containerfile.j2 + _.recipe.base -> from: Containerfile.j2 + + modules: Modules { + label.near: border-top-center + + files: |dockerfile + RUN /tmp/scripts/run_module.sh \ + 'files' '{"type":"files","files":[{"source":"system","destination":"/"}]}' + | + _._.recipe.modules.files -> files: modules.j2 + + containerfile: |dockerfile + RUN echo "Hello, world!" + | + _._.recipe.modules.containerfile -> containerfile: containerfile.j2 + } +} +image: Final image { + label.near: border-top-center + _.containerfile -> _.image: BuildDriver + + meta: Image metadata { + shape: sql_table + + name: string + description: string + } + _.recipe.meta -> meta: BuildDriver +} +``` + +```d2 pad=50 +shape: sequence_diagram +You -> "recipe.yml": Configure image +You -> BlueBuild: `bluebuild build` +"recipe.yml" -> BlueBuild: Read build instructions +BlueBuild -> Containerfile: Build a Containerfile based on recipe +Containerfile -> You: Read the Containerfile if you want to peek under the hood +BlueBuild -> Image: Build image +Image -> You: You can `bluebuild switch` to a locally built image +BlueBuild -> Registry: Push image to registry +Registry -> You: Switch to the hosted image or get the latest version through auto-updates +```