diff --git a/src/assets/grlx.webp b/src/assets/grlx.webp new file mode 100644 index 0000000..be0afa9 --- /dev/null +++ b/src/assets/grlx.webp @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:5de242e9332bf9e47d1331e19604fc13e8d2eb9f32d8a56d53dd306831ee3c03 +size 30508 diff --git a/src/content/config.ts b/src/content/config.ts new file mode 100644 index 0000000..9df91b6 --- /dev/null +++ b/src/content/config.ts @@ -0,0 +1,7 @@ +import { defineCollection } from 'astro:content'; +import { docsSchema, i18nSchema } from '@astrojs/starlight/schema'; + +export const collections = { + docs: defineCollection({ schema: docsSchema() }), + i18n: defineCollection({ type: 'data', schema: i18nSchema() }), +}; diff --git a/src/content/docs/getting-started.mdx b/src/content/docs/getting-started.mdx new file mode 100644 index 0000000..f3af887 --- /dev/null +++ b/src/content/docs/getting-started.mdx @@ -0,0 +1,61 @@ +--- +title: Getting Started +description: Getting Started with grlx +--- + +import {Tabs,TabItem} from '@astrojs/starlight/components'; + +Want to get up and running as quickly as possible to see what all the fuss is about? +Use our bootstrap scripts! Follow our Quick Start to get started! + +## Quick Start + +1. Download and initialize the command line utility from our releases to your dev machine. + + + ```bash + curl -L https://releases.grlx.dev/linux/amd64/latest/grlx > grlx && chmod +x grlx + ./grlx init + ``` + + + + ```bash + curl -L https://releases.grlx.dev/darwin/amd64/latest/grlx > grlx && chmod +x grlx + ./grlx init + ``` + + +You'll be asked some questions, such as which interface the `farmer` is listening on, and which ports to use for communication. +Set the interface to the domain name or IP address of the `farmer`. +Once configured, the CLI prints out your administrator public key, which you'll need for the next step! +It's recommended you now add `grlx` somewhere in your `$PATH`. + +2. On your control server, you'll need to install the `farmer`. +```bash +# or, just run as root instead of sudo +curl -L https://bootstrap.grlx.dev/latest/farmer | sudo bash +``` +You'll be asked several questions about the interface to listen on, which ports to use, etc. +For the quick start, it's recommended to use the default ports (make sure there's no firewall in the way!). +You'll be prompted for an admin public key, which you should have gotten from the prior step, and a certificate host name(s). +Make sure the certificate host name matches the external-facing interface (a domain or IP address) as it will be used for TLS validation! + +3. On all of your fleet nodes, you'll need to install the `sprout`. +```bash +# or, just run as root instead of sudo +# FARMER_BUS_PORT and FARMER_API_PORT variables are available in case you chose +# to use different ports. +curl -L https://bootstrap.grlx.dev/latest/sprout | FARMER_INTERFACE=localhost sudo -E bash +``` +Once the sprout is up and running, return to the CLI. + +4. If all is well, you're ready to `cook`! Accept the TLS cert and the `sprout` keys when prompted. +```bash +grlx version +grlx keys accept -A +sleep 15; +grlx -T \* test ping +grlx -T \* cmd run whoami +grlx -T \* cmd run --out json -- uname -a +``` diff --git a/src/content/docs/guides/example.md b/src/content/docs/guides/example.md new file mode 100644 index 0000000..ebd0f3b --- /dev/null +++ b/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 diff --git a/src/content/docs/index.mdx b/src/content/docs/index.mdx new file mode 100644 index 0000000..55722be --- /dev/null +++ b/src/content/docs/index.mdx @@ -0,0 +1,36 @@ +--- +title: grlx +description: Get started building your docs site with Starlight. +template: splash +hero: + tagline: Effective Fleet Configuration Management + image: + file: ../../assets/grlx.webp + actions: + - text: Get Started + link: /getting-started/ + icon: right-arrow + variant: primary + - text: Check out our GitHub + link: https://github.com/gogrlx/grlx + icon: github +--- + +import { Card, CardGrid } from '@astrojs/starlight/components'; + +## Next steps + + + + Edit `src/content/docs/index.mdx` to see this page change. + + + Add Markdown or MDX files to `src/content/docs` to create new pages. + + + Edit your `sidebar` and other config in `astro.config.mjs`. + + + Learn more in [the Starlight Docs](https://starlight.astro.build/). + + diff --git a/src/content/docs/ingredients/cmd.md b/src/content/docs/ingredients/cmd.md new file mode 100644 index 0000000..3b815a4 --- /dev/null +++ b/src/content/docs/ingredients/cmd.md @@ -0,0 +1,18 @@ +--- +title: grlx.ingredients.cmd +description: cmd +--- +The cmd ingredient allows for us to run arbitrary shell commands against sprouts. +## **cmd.run** +Runs shell commands against a sprout +#### Parameters +| parameter | type | required | description | +|-----------|------|----------|-------------| +| _name_ | string | true | the command to run +| _runas_ | string | false | user who will run this command +```yaml +cmd.run: + - name: go version + - runas: super-cool-user +``` + diff --git a/src/content/docs/ingredients/file-providers.md b/src/content/docs/ingredients/file-providers.md new file mode 100644 index 0000000..ba16b86 --- /dev/null +++ b/src/content/docs/ingredients/file-providers.md @@ -0,0 +1,26 @@ +--- +title: grlx.ingedients.file.providers +description: grlx built-in file providers +--- +`grlx` has a concept of file providers for different ways that you might obtain a file to be added to a given `sprout`. This uses a provider interface to keep this extensible and provide a standard way to use different file types. By default, `grlx` has three built-in providers: local, HTTP, and S3. + +## Local +The local provider would be how you would use a file from your host system. +#### Example +```yaml +file.cached: + - source: go1.21.3.src.tar.gz + - hash: sha256=186f2b6f8c8b704e696821b09ab2041a5c1ee13dcbc3156a13adcf75931ee488 +``` + +## HTTP +The HTTP provider allows you to download files via HTTP for use. The [example](/ingredients/file-providers/#example) below is using the HTTP provider to download Go from the Internet. This file then gets cached to the sprout. +#### Example +```yaml +file.cached: + - source: https://go.dev/dl/go1.21.3.src.tar.gz + - hash: sha256=186f2b6f8c8b704e696821b09ab2041a5c1ee13dcbc3156a13adcf75931ee488 +``` + +## TODO: S3 +The S3 allows you to get a file from an S3 compatible bucket. diff --git a/src/content/docs/ingredients/file.md b/src/content/docs/ingredients/file.md new file mode 100644 index 0000000..49afbf9 --- /dev/null +++ b/src/content/docs/ingredients/file.md @@ -0,0 +1,131 @@ +--- +title: grlx.ingredients.file +description: file +--- +The file ingredient handles all file operations on various [file providers](/ingredients/file-providers) (such as local files, HTTP, etc.) +## **file.absent** +Deletes a file or directory +#### Parameters +| parameter | type | required | description | +|-----------|------|----------|-------------| +| _name_ | string | yes | the name/path of the file to delete +#### Example +```yaml +file.absent: + name: ~/.config/sytemd/user/backup.service +``` + +## **file.append** +Appends content to a file. Only appends the content if it doesn't exist. +#### Parameters +| parameter | type | required | description | +|-----------|------|----------|-------------| +| _name_ | string |required| the name/path of the file to delete +| _text_ | string |required| the text to append to a file +#### Example +```yaml +file.append: + - name: /etc/profile + - text: | + export PATH=$PATH:/usr/local/go/bin +``` + +## **file.cached** +Validates if a file is cached in the sprout's cache. If it isn't the file will be cached. +#### Parameters +| parameter | type | required | description | +|-----------|------|----------|-------------| +| _source_ | string | yes | a file source (such as HTTP, file, etc.) to reference +| _hash_ | string | no | a valid hash of the `source` file +| _skip_verify_ | boolean | no | whether to skip hash validation, false by default +#### Example +```yaml +file.cached: + - source: https://go.dev/dl/go1.21.3.src.tar.gz + - hash: sha256=186f2b6f8c8b704e696821b09ab2041a5c1ee13dcbc3156a13adcf75931ee488 +``` + +## **file.content** +TODO +#### Parameters +| parameter | type | required | description | +|-----------|------|----------|-------------| +#### Example +```yaml +file.content: +``` + +## **file.contains** +Checks if a file contains a given selection. If multiple sources are provided, all must be satisfied. +#### Parameters +| parameter | type | required | description | +|-----------|------|----------|-------------| +| _name_ | string | yes | the name/path of the file to check +| _text_ | string | no |the item to search for +| _source_ | string | no | a file source (such as HTTP, file, etc.) to reference +| _source_hash_ | string | no | a hash for a given source +| _sources_ | list | no | a list of sources to check against +| _source_hashes_ | list | no | a list of source hashes +| _skip_verify_ | boolean | no | whether to skip hash validation, false by default + + +## **file.directory** +Handles many directory operations. Ensures that a directory exists with the given permissions. +#### Parameters +| parameter | type | required | description | +|-----------|------|----------|-------------| +| _name_ | string | yes | the name/path of the directory +| _makedirs_ | bool | no |option to make directory if it doesn't exist, defaults to true +| _user_ | string | no |the user who will own the directory +| _group_ | string | no |the group who will own the directory +| _dir_mode_ | string | no |the directory mode +| _file_mode_ | string | no |the file mode to set +| _recurse_ | bool | no |whether to recurse the directories and apply permissions +#### Example +```yaml +file.directory: + - name: /tmp/item + - makdirs: false + - user: grlx + - group: grlx + - dir_moode: 755 + - recurse: false +``` + +## **file.exists** +Checks if a file exists. +#### Parameters +| parameter | type | required | description | +|-----------|------|----------|-------------| +| _name_ | string | yes | the name/path of the file +#### Example +```yaml +file.exists: + - name: /tmp/exists +``` + +## **file.missing** +Checks if a file is missing. +#### Parameters +| parameter | type | required | description | +|-----------|------|----------|-------------| +| _name_ | string | yes | the name/path of the file +#### Example +```yaml +file.missing: + - name: /tmp/missing +``` + +## **file.symlink** +Creates a symlink at `name` that points to `target` +#### Parameters +| parameter | type | required | description | +|-----------|------|----------|-------------| +| _name_ | string | yes | the name/path of the file +| _target_ | string | yes | the target path to link to +#### Example +```yaml +file.symlink: + - name: ~/localbash + - target: /usr/bin/bash +``` diff --git a/src/content/docs/ingredients/overview.md b/src/content/docs/ingredients/overview.md new file mode 100644 index 0000000..a419230 --- /dev/null +++ b/src/content/docs/ingredients/overview.md @@ -0,0 +1,8 @@ +--- +title: Overview +description: The foundation of grlx +sidebar: + order: 1 +--- +Recipe ingredients are how we build configurations with `grlx`. They can be thought of as the building blocks for completing various file, service, or management operations. + diff --git a/src/content/docs/reference/example.md b/src/content/docs/reference/example.md new file mode 100644 index 0000000..ac8cfa8 --- /dev/null +++ b/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 your documenting. + +## Further reading + +- Read [about reference](https://diataxis.fr/reference/) in the Diátaxis framework diff --git a/src/env.d.ts b/src/env.d.ts new file mode 100644 index 0000000..acef35f --- /dev/null +++ b/src/env.d.ts @@ -0,0 +1,2 @@ +/// +///