-
Notifications
You must be signed in to change notification settings - Fork 1
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
feat(docs/site): add nextjs docs site
- Loading branch information
Showing
13 changed files
with
3,115 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,2 @@ | ||
| .next/ | ||
| node_modules/ |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,9 @@ | ||
| const withNextra = require('nextra')({ | ||
| theme: 'nextra-theme-docs', | ||
| themeConfig: './theme.config.jsx' | ||
| }) | ||
|
|
||
| module.exports = withNextra() | ||
|
|
||
| // If you have other Next.js configurations, you can pass them as the parameter: | ||
| // module.exports = withNextra({ /* other next.js config */ }) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,9 @@ | ||
| { | ||
| "dependencies": { | ||
| "next": "^13.4.16", | ||
| "react": "^18.2.0", | ||
| "react-dom": "^18.2.0", | ||
| "nextra": "^2.11.0", | ||
| "nextra-theme-docs": "^2.11.0" | ||
| } | ||
| } |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,4 @@ | ||
| { | ||
| "index": "Welcome", | ||
| "configuration": "Configuration" | ||
| } |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,6 @@ | ||
| { | ||
| "overview": "Overview", | ||
| "controllers": "Controllers", | ||
| "definitions": "Resource Definitions", | ||
| "bindings": "API Bindings" | ||
| } |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,56 @@ | ||
| API Bindings | ||
| ------------ | ||
|
|
||
| Bindings are the last crucial compontent for exposing resources via the Cup API. | ||
| A binding defines which resource types should be exposed via the API, and what controller should handle their operations. | ||
|
|
||
| ```json | ||
| { | ||
| "apiVersion": "cup.flipt.io/v1alpha1", | ||
| "kind": "Binding", | ||
| "metadata": { | ||
| "name": "flipt" | ||
| }, | ||
| "spec": { | ||
| "controller": "flipt", | ||
| "resources": [ | ||
| "flipt.io/v1alpha1/flags", | ||
| "flipt.io/v1alpha1/segments" | ||
| ] | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| ## Specification | ||
|
|
||
| ### Binding | ||
|
|
||
| Each controller resource definition has the following top-level fields. | ||
| Both `apiVersion` and `kind` are fixed constants, but `metadata` and `spec` can be configured accordingly. | ||
|
|
||
| | Key | Value | | ||
| |------------|-------------------------------------------------------| | ||
| | apiVersion | `"cup.flipt.io/v1alpha1"` | | ||
| | kind | `"Binding"` | | ||
| | metadata | [`<Metadata>`](#metadata) | | ||
| | spec | [`<BindingSpec>`](#bindingsourcedefinitionspec) | | ||
|
|
||
| ### Metadata | ||
|
|
||
| API bindings have a single metadata string field `name`. | ||
| Each configured binding should be uniquely named. | ||
|
|
||
| | Key | Value | Description | | ||
| |------|----------|---------------------------------------| | ||
| | name | `string` | Unique identifier for the API binding | | ||
|
|
||
| ### BindingSpec | ||
|
|
||
| The API binding spec binds a [Controller](/configuration/controllers) to handle a set of [Resource Definitions](/configuration/definitions). | ||
| A single definitions registers all the declared resources on the `cupd` API (under `/apis`). | ||
| Each resource will be handled by the named controller. | ||
|
|
||
| | Key | Value | Description | | ||
| |------------|------------|-----------------------------------------------------------------------------| | ||
| | controller | `string` | Should match the `<metadata.name>` of a loaded controller | | ||
| | versions | `[string]` | A list of resource identifies in the form `<group>/<version>/<plural>` (see [definition names](/configuration/definitions#names) to learn about `plural`) | |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,127 @@ | ||
| Controllers | ||
| ----------- | ||
|
|
||
| Controllers are the engines that drive reading and writing changes to target configuration sources (directories, repositories etc.). | ||
| Internally, Cup abstracts away the details of Git repositories, commits, trees, and pull requests. | ||
| Controllers focus on handling individual actions over a mounted target directory. | ||
|
|
||
| These actions currently include: | ||
|
|
||
| - get | ||
| - list | ||
| - put | ||
| - delete | ||
|
|
||
| Each controller is configured via a JSON file in the `-api-resources` directory. | ||
| There are currently two types of controller configurable in Cup: | ||
|
|
||
| - [Template](#template) | ||
| - [WASM](#wasm) | ||
|
|
||
| ## Template | ||
|
|
||
| Is a simple, built-in controller which uses Go's `text/template` to perform 1:1 API resource to file in repo mappings. | ||
|
|
||
| There exist two templates: | ||
|
|
||
| 1. Directory Template | ||
|
|
||
| This is used during `list` operations to map a namespace onto a target directory exclusively containing files that each represent a single resource instance. | ||
| It can be configured with glob syntax to further constrain, which files in a target directory are considered resources. | ||
|
|
||
| 2. Path Template | ||
|
|
||
| This is used during `get`, `put`, and `delete` operations to identify the particular file the resource should be read from, written to, or deleted respectively. | ||
|
|
||
| ```json | ||
| { | ||
| "apiVersion": "cup.flipt.io/v1alpha1", | ||
| "kind": "Controller", | ||
| "metadata": { | ||
| "name": "some-template-controller" | ||
| }, | ||
| "spec": { | ||
| "type": "template", | ||
| "spec": { | ||
| "directory_template": "{{ .Namespace }}/*.json", | ||
| "path_template": "{{ .Namespace }}/{{ .Group }}-{{ .Version }}-{{ .Kind }}-{{ .Name }}.json" | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| ## WASM | ||
|
|
||
| The WASM controller is an extension point that opens Cup up to the full power of languages which can be compiled to WASM with the WASIP1 extensions. | ||
| Given your controller can be expressed as a command-line tool, conforming to Cup's well-defined set of sub-commands and standard I/O expectations, implemented in a language compiled to WASM with WASIP1, then it can be used in Cup. | ||
|
|
||
| To learn more about the binary API required for a Cup WASM controller, check out the [Design](./docs/DESIGN.md) document in this repo. | ||
| Cup is a very early prototype and this design is likely to change and open to suggestions. | ||
|
|
||
| Given your resulting controller WASM binary is present and reachable on the filesystem by `cupd`, then it can be leveraged by Cup to handle your particular resource management needs. | ||
|
|
||
| The Controller resource specification includes a single field `path` which should point to where the WASM implementation exists on disk. | ||
| This path will resolve relative to the `-api-resources` directory. | ||
|
|
||
| ```json | ||
| { | ||
| "apiVersion": "cup.flipt.io/v1alpha1", | ||
| "kind": "Controller", | ||
| "metadata": { | ||
| "name": "flipt" | ||
| }, | ||
| "spec": { | ||
| "type": "wasm", | ||
| "spec": { | ||
| "path": "flipt.wasm" | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| ## Specification | ||
|
|
||
| ### Resource | ||
|
|
||
| Each controller resource definition has the following top-level fields. | ||
| Both `apiVersion` and `kind` are fixed constants, but `metadata` and `spec` can be configured accordingly. | ||
|
|
||
| | Key | Value | | ||
| |------------|---------------------------------------| | ||
| | apiVersion | `"cup.flipt.io/v1alpha1"` | | ||
| | kind | `"Controller"` | | ||
| | metadata | [`<Metadata>`](#metadata) | | ||
| | spec | [`<ControllerSpec>`](#controllerspec) | | ||
|
|
||
| ### Metadata | ||
|
|
||
| Controllers have a single metadata string field `name`. | ||
| Each configured controller should be uniquely named. | ||
| These names are referenced in `APIBinding` resources when associating them with `ResourceDefinition`s and exposing them through the cup API. | ||
|
|
||
| | Key | Value | | ||
| |------|----------| | ||
| | name | `string` | | ||
|
|
||
| ### ControllerSpec | ||
|
|
||
| The controller specification contains an initial `type` field which signifies the type of the controller. | ||
| Depending on the `type` field value, the `spec` field will contain the corresponding specification for the controller type. | ||
|
|
||
| | Key | Value | | ||
| |------|--------------------------------------------------------------------------------------------------------| | ||
| | type | `["template" \| "wasm"]` | | ||
| | spec | [`<TemplateControllerSpec>`](#templatecontrollerspec) \| [`<WASMControllerSpec>`](#wasmcontrollerspec) | | ||
|
|
||
| ### TemplateControllerSpec | ||
|
|
||
| | Key | Value | Description | | ||
| |--------------------|------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | ||
| | directory_template | `string` | Go `text/template` string which is rendered on `list` operations to identify where to source resource files. The result can be a glob syntax to further narrow the selection criteria. | | ||
| | path_template | `string` | Go `text/template` string which is rendered on `get`, `put` and `delete` operations to identify a specific resource by apiVersion, kind, namespace and name. | | ||
|
|
||
| ### WASMControllerSpec | ||
|
|
||
| | Key | Value | Description | | ||
| |------|----------|-------------| | ||
| | path | `string` | Path on disk (relative to the `-api-resources` directory configuration flag) to the controllers WASM binary file. | |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,112 @@ | ||
| Resource Definitions | ||
| -------------------- | ||
|
|
||
| Resource definitions live in the directory identified by `-api-resources`. | ||
| Each definition contains the group, kind and versioned schemas for resource types handled by Cup. | ||
| These definitions are heavily inspired by Kubernetes' concept of Customer Resource Definitions. | ||
|
|
||
| Any file in the API resources directory ending in `.json` is currently parsed and interpreted. | ||
| Depending on the `apiVersion` and `kind` of the resource, they each get treated accordingly. | ||
|
|
||
| ```json | ||
| { | ||
| "apiVersion": "cup.flipt.io/v1alpha1", | ||
| "kind": "ResourceDefinition", | ||
| "metadata": { | ||
| "name": "flags.flipt.io" | ||
| }, | ||
| "names": { | ||
| "kind": "Flag", | ||
| "singular": "flag", | ||
| "plural": "flags" | ||
| }, | ||
| "spec": { | ||
| "group": "flipt.io", | ||
| "versions": { | ||
| "v1alpha1": { | ||
| "type": "object", | ||
| "properties": { | ||
| "key": { "type": "string" }, | ||
| "name": { "type": "string" }, | ||
| "type": { "enum": ["", "FLAG_TYPE_VARIANT", "FLAG_TYPE_BOOLEAN"] }, | ||
| "enabled": { "type": "boolean" }, | ||
| "description": { "type": "string" }, | ||
| "variants": { | ||
| "type": ["array", "null"], | ||
| "items": { | ||
| "type": "object", | ||
| "properties": { | ||
| "key": { "type": "string" }, | ||
| "description": { "type": "string" }, | ||
| "attachment": { | ||
| "type": "object", | ||
| "additionalProperties": true | ||
| } | ||
| } | ||
| } | ||
| }, | ||
| "rules": { | ||
| "type": ["array", "null"], | ||
| "items": { | ||
| "type": "object" | ||
| } | ||
| }, | ||
| "rollouts": { | ||
| "type": ["array", "null"], | ||
| "items": { | ||
| "type": "object" | ||
| } | ||
| } | ||
| }, | ||
| "additionalProperties": false | ||
| } | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| ## Specification | ||
|
|
||
| ### Resource | ||
|
|
||
| Each controller resource definition has the following top-level fields. | ||
| Both `apiVersion` and `kind` are fixed constants, but `metadata` and `spec` can be configured accordingly. | ||
|
|
||
| | Key | Value | | ||
| |------------|-------------------------------------------------------| | ||
| | apiVersion | `"cup.flipt.io/v1alpha1"` | | ||
| | kind | `"ResourceDefinition"` | | ||
| | metadata | [`<Metadata>`](#metadata) | | ||
| | names | [`<Names>`](#names) | | ||
| | spec | [`<ResourceDefinitionSpec>`](#resourcedefinitionspec) | | ||
|
|
||
| ### Metadata | ||
|
|
||
| Resource definitions have a single metadata string field `name`. | ||
| Each configured definition should be uniquely named. | ||
| These names are referenced in `APIBinding` resources when associating them with `Controller`s and exposing them through the cup API. | ||
|
|
||
| | Key | Value | Description | | ||
| |------|----------|-----------------------------------------------------------------------------------| | ||
| | name | `string` | Unique identifier for the resource kind in the form `<names.plural>.<spec.group>` | | ||
|
|
||
| ### Names | ||
|
|
||
| Names is taken straight out of the Kubernetes CRD playbook. | ||
| These name forms are used throughout the API and in the CLI. | ||
|
|
||
| | Key | Value | Description | | ||
| |----------|----------|---------------------------------------------------------| | ||
| | kind | `string` | Uppercase name of the resource kind | | ||
| | singular | `string` | Lowercase name for a single instance of the resource | | ||
| | plural | `string` | Lowercase name for a multuple instances of the resource | | ||
|
|
||
| ### ResourceDefinitionSpec | ||
|
|
||
| The resource definition spec contains the resource group along with a map of versioned JSON schema payloads. | ||
| Each schema is used to validated incoming resources, and can be retrieved through the generated API to support tooling. | ||
|
|
||
| | Key | Value | Description | | ||
| |----------|-------------------------|---------------------------------------------------------------------------| | ||
| | group | `string` | An identifier for the group the resource belongs to | | ||
| | versions | `map[string]JSONSchema` | A map of version string to JSON Schema definition of the resource payload | |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,37 @@ | ||
| Configuration | ||
| ------------- | ||
|
|
||
| This section is primarily concerned with configuring an instance of `cupd`. | ||
| `cupd` is the server side component of the Cup ecosystem. | ||
| This is where all the components for checking out repositories, hosting and managing API resources, transforming contents and making proposals to Git repositories takes place. | ||
|
|
||
| ## `cupd` | ||
|
|
||
| `cupd` the binary starts with some top-level configuration parameters. | ||
|
|
||
| These parameters can be adjusted in three different ways: | ||
| - As command-line flags | ||
| - As environment variables | ||
| - Via a configuration yaml file | ||
|
|
||
| ### `cupd serve` | ||
|
|
||
| ```console | ||
| ➜ cupd serve --help | ||
| DESCRIPTION | ||
| Run the cupd server | ||
|
|
||
| USAGE | ||
| cupd serve [flags] | ||
|
|
||
| FLAGS | ||
| -api-address :8181 server listen address | ||
| -api-git-repo string target git repository URL | ||
| -api-git-scm github SCM type (one of [github, gitea]) | ||
| -api-local-path . path to local source directory | ||
| -api-resources . path to server configuration directory (controllers, definitions and bindings) | ||
| -api-source local source type (one of [local, git]) | ||
| -tailscale-auth-key string Tailscale auth key (optional) | ||
| -tailscale-ephemeral=false join the network as an ephemeral node (optional) | ||
| -tailscale-hostname string hostname to expose on Tailscale | ||
| ``` |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,13 @@ | ||
| import { Callout } from 'nextra/components' | ||
|
|
||
| Cup | ||
| --- | ||
|
|
||
| <Callout type="info" emoji="🥤"> | ||
| Because Git deserves better contribution automation | ||
| </Callout> | ||
|
|
||
| Cup is an extensible server for building automation around contributions to Git and SCMs like GitHub. | ||
| It exposes a consistent declarative API, with an opinionated convention based on Kubernetes. | ||
| The API is self-describing, allowing for tooling to be developed with broad applicability to a range of usecases. | ||
| All changes made to API resources are handled by Controllers. Controllers do the heavy lifting when it comes to changing the contents of a repository based on the desired state of an API resource. Any calculated changes are proposed as pull or merge requests on your prefered SCM (GitHub, Gitea etc.). |
Oops, something went wrong.