Merge pull request #953 from slumbering/docs-menu-refacto
docs: ♻️ merge API Reference and Universe menu entries
This commit is contained in:
Sam Alba
GitHub
@@ -133,6 +133,7 @@ In Dagger terms, this component has two essential properties:
|
||||
Let's write the corresponding Cue code to a new file in our package:
|
||||
|
||||
```cue file=./tests/multibucket/source.cue title="todoapp/cue.mod/multibucket/source.cue"
|
||||
|
||||
```
|
||||
|
||||
This code defines a component at the key `src` and specifies that it is both an artifact and an input.
|
||||
@@ -142,12 +143,13 @@ This code defines a component at the key `src` and specifies that it is both an
|
||||
The second component of our plan is the Yarn package built from the app source code:
|
||||
|
||||
```cue file=./tests/multibucket/yarn.cue title="todoapp/cue.mod/multibucket/yarn.cue"
|
||||
|
||||
```
|
||||
|
||||
Let's break it down:
|
||||
|
||||
- `package multibucket`: this file is part of the multibucket package
|
||||
- `import ( "alpha.dagger.io/js/yarn" )`: import a package from the [Dagger Universe](../reference/universe/README.md).
|
||||
- `import ( "alpha.dagger.io/js/yarn" )`: import a package from the [Dagger Universe](../reference/README.md).
|
||||
- `app: yarn.#Package`: apply the `#Package` definition at the key `app`
|
||||
- `&`: also merge the following values at the same key...
|
||||
- `{ source: src }`: set the key `app.source` to the value of `src`. This snippet of code connects our two components, forming the first link in our DAG
|
||||
@@ -161,12 +163,13 @@ _FIXME_: this section is not yet available because the [Amazon S3 package](https
|
||||
The third component of our plan is the Netlify site to which the app will be deployed:
|
||||
|
||||
```cue file=./tests/multibucket/netlify.cue title="todoapp/cue.mod/multibucket/netlify.cue"
|
||||
|
||||
```
|
||||
|
||||
This component is very similar to the previous one:
|
||||
|
||||
- We use the same package name as the other files
|
||||
- We import another package from the [Dagger Universe](../reference/universe/README.md).
|
||||
- We import another package from the [Dagger Universe](../reference/README.md).
|
||||
- `site: "netlify": site.#Netlify`: apply the `#Site` definition at the key `site.netlify`. Note the use of quotes to protect the key from name conflict.
|
||||
- `&`: also merge the following values at the same key...
|
||||
- `{ contents: app.build }`: set the key `site.netlify.contents` to the value of `app.build`. This line connects our components 2 and 3, forming the second link in our DAG.
|
||||
@@ -174,14 +177,14 @@ This component is very similar to the previous one:
|
||||
### Exploring a package documentation
|
||||
|
||||
But wait: how did we know what fields were available in `yarn.#Package` and `netlify.#Site`?
|
||||
Answer: thanks to the `dagger doc` command, which prints the documentation of any package from [Dagger Universe](../reference/universe/README.md).
|
||||
Answer: thanks to the `dagger doc` command, which prints the documentation of any package from [Dagger Universe](../reference/README.md).
|
||||
|
||||
```shell
|
||||
dagger doc alpha.dagger.io/netlify
|
||||
dagger doc alpha.dagger.io/js/yarn
|
||||
```
|
||||
|
||||
You can also browse the [Dagger Universe](../reference/universe/README.md) reference in the documentation.
|
||||
You can also browse the [Dagger Universe](../reference/README.md) reference in the documentation.
|
||||
|
||||
## Setup the environment
|
||||
|
||||
|
||||
@@ -18,7 +18,7 @@ The provisioning strategy detailed below follows S3 best practices. However, to
|
||||
|
||||
#### Relays
|
||||
|
||||
The first thing to consider when developing a plan based on relays is to read their universe reference: it summarizes the expected inputs and their corresponding formats. [Here](../reference/universe/aws/cloudformation.md) is the Cloudformation one.
|
||||
The first thing to consider when developing a plan based on relays is to read their universe reference: it summarizes the expected inputs and their corresponding formats. [Here](../reference/aws/cloudformation.md) is the Cloudformation one.
|
||||
|
||||
## Initialize a Dagger Workspace and Environment
|
||||
|
||||
@@ -59,11 +59,12 @@ The idea here is to follow best practices in [S3 buckets](https://docs.aws.amazo
|
||||
Create a file named `template.cue` and add the following configuration to it.
|
||||
|
||||
```cue file=./tests/cloudformation/template.cue title="todoapp/cloudformation/template.cue"
|
||||
|
||||
```
|
||||
|
||||
##### 2. Cloudformation relay
|
||||
|
||||
As our plan relies on [Cloudformation's relay](../reference/universe/aws/cloudformation.md), let's dissect the expected inputs by gradually incorporating them into our plan.
|
||||
As our plan relies on [Cloudformation's relay](../reference/aws/cloudformation.md), let's dissect the expected inputs by gradually incorporating them into our plan.
|
||||
|
||||
```shell
|
||||
dagger doc alpha.dagger.io/aws/cloudformation
|
||||
@@ -96,6 +97,7 @@ The config values are all part of the `aws` relay. Regarding this package, as yo
|
||||
Let's implement the first step, use the `aws.#Config` relay, and request its first inputs: the region to deploy and the AWS credentials.
|
||||
|
||||
```cue file=./tests/cloudformation/source-begin.cue title="todoapp/cloudformation/source.cue"
|
||||
|
||||
```
|
||||
|
||||
This defines:
|
||||
@@ -138,6 +140,7 @@ dagger up -e cloudformation # Try to run the plan. As expected, we encounter a f
|
||||
Now that we have the `config` definition properly configured, let's modify the Cloudformation one:
|
||||
|
||||
```cue file=./tests/cloudformation/source-end.cue title="todoapp/cloudformation/source.cue"
|
||||
|
||||
```
|
||||
|
||||
This defines:
|
||||
@@ -184,11 +187,11 @@ dagger input secret awsConfig.secretKey yourSecretKey -e cloudformation
|
||||
|
||||
Finally ! We now have a working template ready to be used to provision S3 infrastructures. Let's deploy it:
|
||||
<Tabs
|
||||
defaultValue="nd"
|
||||
values={[
|
||||
{ label: 'Normal deploy', value: 'nd', },
|
||||
{ label: 'Debug deploy', value: 'dd', },
|
||||
]
|
||||
defaultValue="nd"
|
||||
values={[
|
||||
{ label: 'Normal deploy', value: 'nd', },
|
||||
{ label: 'Debug deploy', value: 'dd', },
|
||||
]
|
||||
}>
|
||||
<TabItem value="nd">
|
||||
|
||||
@@ -257,6 +260,7 @@ import Tabs from "@theme/Tabs";
|
||||
import TabItem from "@theme/TabItem";
|
||||
|
||||
```cue file=./tests/cloudformation/template/convert.cue title="todoapp/cloudformation/convert.cue"
|
||||
|
||||
```
|
||||
|
||||
This defines:
|
||||
@@ -300,6 +304,7 @@ rm cloudformation/convert.cue
|
||||
Open `cloudformation/template.cue` and append below elements with copied Cue definition of the JSON:
|
||||
|
||||
```cue file=./tests/cloudformation/template/template-begin.cue title="todoapp/cloudformation/template.cue"
|
||||
|
||||
```
|
||||
|
||||
We're using the built-in `json.Marshal` function to convert CUE back to JSON, so Cloudformation still receives the same template.
|
||||
@@ -315,11 +320,13 @@ Now that the template is defined in CUE, we can use the language to add more fle
|
||||
Let's define a re-usable `#Deployment` definition in `todoapp/cloudformation/deployment.cue`:
|
||||
|
||||
```cue file=./tests/cloudformation/template/deployment.cue title="todoapp/cloudformation/deployment.cue"
|
||||
|
||||
```
|
||||
|
||||
`template.cue` can be rewritten as follows:
|
||||
|
||||
```cue file=./tests/cloudformation/template/template-end.cue title="todoapp/cloudformation/template.cue"
|
||||
|
||||
```
|
||||
|
||||
Verify template
|
||||
@@ -352,6 +359,7 @@ dagger query template -f text -e cloudformation
|
||||
Reimplement `source.cue`:
|
||||
|
||||
```cue file=./tests/cloudformation/source-end.cue title="todoapp/cloudformation/source.cue"
|
||||
|
||||
```
|
||||
|
||||
And we can now deploy it:
|
||||
|
||||
Reference in New Issue
Block a user