forked from dagger/dagger
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs: Updates quickstart examples (dagger#7172)
* docs: Updates quickstart examples Signed-off-by: Vikram Vaswani <[email protected]> * Fixed capitalization according to new style guide Signed-off-by: Vikram Vaswani <[email protected]> * Updates examples Signed-off-by: Vikram Vaswani <[email protected]> * Copy fix Signed-off-by: Vikram Vaswani <[email protected]> * Added feedback Signed-off-by: Vikram Vaswani <[email protected]> --------- Signed-off-by: Vikram Vaswani <[email protected]>
- Loading branch information
1 parent
1b16d32
commit 0bc7168
Showing
8 changed files
with
154 additions
and
100 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
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
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 |
---|---|---|
|
@@ -33,8 +33,95 @@ As you can see, Dagger loaded a module directly from its GitHub repository, and | |
|
||
If you [inspect the source code of the module](https://github.com/shykes/daggerverse/blob/main/hello/main.go), you'll see a `Hello()` function, written in Go, which prepares a message and returns it as a string. | ||
|
||
Note that the function supports arguments - we'll get to that later. | ||
|
||
:::info | ||
When using `dagger call`, all names (functions, arguments, fields, etc) are converted into a shell-friendly "kebab-case" style. This is why the function named `Hello()` is invoked as `dagger call hello`. | ||
::: | ||
|
||
### List available function arguments | ||
|
||
Dagger Functions, just like regular functions, can accept arguments. Appending the `--help` flag to a `dagger call` command will display a context-sensitive list of supported arguments and sub-commands. | ||
|
||
Inspect the arguments of the `hello` function you called earlier: | ||
|
||
```shell | ||
dagger -m github.com/shykes/daggerverse/[email protected] call hello --help | ||
``` | ||
|
||
You should see output that looks like this: | ||
|
||
```shell | ||
Say hello to the world! | ||
|
||
Usage: | ||
dagger call hello [flags] | ||
|
||
Flags: | ||
--figlet-container Container Optional container for running the figlet tool | ||
--giant Encode the message in giant multi-character letters | ||
--greeting string An optional greeting (default is "hello") | ||
--name string An optional name (default is "world") | ||
--shout Make the message uppercase, and add more exclamation | ||
points | ||
``` | ||
|
||
### Call a function with arguments | ||
|
||
Let's pass two string arguments to the `hello` function, from the list above: | ||
|
||
```shell | ||
dagger -m github.com/shykes/daggerverse/[email protected] call hello --greeting=bonjour --name=daggernaut | ||
``` | ||
|
||
You should see the following output: | ||
|
||
```shell | ||
bonjour, daggernaut! | ||
``` | ||
|
||
### Use complex types as arguments | ||
|
||
In addition to basic types (string, boolean, integer, array...), Dagger also defines powerful core types which functions can use as arguments: `Directory`, `File`, `Container`, `Service`, `Secret` and others. | ||
|
||
You'll see this in action as you continue through the quickstart, but here's a quick example that demonstrates passing a `Directory` type as argument to a Dagger Function: | ||
|
||
```shell | ||
dagger -m github.com/vikram-dagger/daggerverse/fileutils call tree --dir='https://github.com/dagger/dagger#main:cmd/dagger' | ||
``` | ||
|
||
Here, the `Tree()` function accepts a `Directory` as argument and returns a tree representation of that directory. The directory could be a local directory, or a remote Git reference. In this example, the directory is the `cmd/dagger` sub-directory of Dagger's open-source GitHub repository. | ||
|
||
You should see the following output, which should be the same file listing as [this GitHub page](https://github.com/dagger/dagger/tree/main/cmd/dagger): | ||
|
||
```shell | ||
. | ||
├── call.go | ||
├── cloud.go | ||
├── config.go | ||
├── debug.go | ||
├── engine.go | ||
├── exec_nonunix.go | ||
├── exec_unix.go | ||
├── flags.go | ||
├── functions.go | ||
├── gen.go | ||
├── licenses.go | ||
├── listen.go | ||
├── log.go | ||
├── main.go | ||
├── module.go | ||
├── module_test.go | ||
├── query.go | ||
├── run.go | ||
├── session.go | ||
├── shell.go | ||
├── shell_nounix.go | ||
├── shell_unix.go | ||
├── version.go | ||
└── watch.go | ||
|
||
0 directories, 24 files | ||
``` | ||
|
||
:::tip | ||
All of Dagger's core types, such as `Directory`, `File`, `Container`, `Service`, `Secret`, can be used as arguments by Dagger Functions. These core types are not merely strings referencing local or remote resources; they are actual representations of the corresponding resource states, managed by the Dagger Engine, and passed to and between Dagger Functions like other variables. This feature makes it easy to assemble complex pipelines where container state flows from function to function, in just a few lines of code. | ||
::: |
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 |
---|---|---|
|
@@ -14,8 +14,8 @@ So far, you've learned the basics of calling Dagger Functions. The next step is | |
|
||
Here are the basic steps to Daggerizing an existing project: | ||
|
||
1. Initialize a new Dagger Module with `dagger init` | ||
2. Install other useful Dagger Modules as dependencies with `dagger install` | ||
1. Initialize a new Dagger module with `dagger init` | ||
2. Install other useful Dagger modules from the [Daggerverse](./183917-daggerverse.mdx) as dependencies with `dagger install` | ||
3. Call useful Dagger Functions with `dagger call` | ||
4. Add useful `dagger call` commands to existing scripts and CI configuration | ||
|
||
|
@@ -49,7 +49,7 @@ You should see the following: | |
```json | ||
{ | ||
"name": "example", | ||
"engineVersion": "v0.10.1" | ||
"engineVersion": "v0.11.1" | ||
} | ||
``` | ||
|
||
|
@@ -64,30 +64,26 @@ git add dagger.json | |
git commit -m 'dagger init' | ||
``` | ||
|
||
Congratulations! Your repository is now a Dagger Module. | ||
|
||
### Install a dependency | ||
|
||
Now that your project is a Dagger Module, you can install other modules into it, as dependencies. A dependency is just a Dagger Module installed into another. As an example, install the `hello` module from earlier: | ||
Now that your project has a Dagger module, you can install other modules into it, as dependencies. A dependency is just a Dagger module installed into another. Since the project is a Go project, install the Go builder module from earlier as a dependency: | ||
|
||
```shell | ||
dagger install github.com/shykes/daggerverse/hello@v0.1.2 | ||
dagger install github.com/kpenfound/dagger-modules/golang@v0.1.8 | ||
``` | ||
|
||
Once the command completes, look at the `dagger.json` file again. You should see that a new dependency has been added, similar to that shown below: | ||
|
||
```json | ||
{ | ||
"name": "example", | ||
"sdk": "go", | ||
"dependencies": [ | ||
{ | ||
"name": "hello", | ||
"source": "github.com/shykes/daggerverse/hello@3d608cb5e6b4b18036a471400bc4e6c753f229d7" | ||
"name": "golang", | ||
"source": "github.com/kpenfound/dagger-modules/golang@8d662e001caf8c16253226d0d456f2f0f374f009" | ||
} | ||
], | ||
"source": "dagger", | ||
"engineVersion": "v0.10.1" | ||
"engineVersion": "v0.11.1" | ||
} | ||
``` | ||
|
||
|
@@ -99,44 +95,7 @@ Go ahead and commit this change as well: | |
|
||
```shell | ||
git add dagger.json | ||
git commit -m 'dagger install github.com/shykes/daggerverse/hello' | ||
``` | ||
|
||
### Use the installed module | ||
|
||
Now that your module has its first dependency installed, you can start using it! To do so, simply refer to it by its short name - in this case, `hello`. | ||
|
||
List available functions: | ||
|
||
```shell | ||
dagger -m hello functions | ||
``` | ||
|
||
You should see a familiar result: | ||
|
||
``` | ||
Name Description | ||
hello Say hello to the world! | ||
``` | ||
|
||
Call a function: | ||
|
||
```shell | ||
dagger -m hello call hello | ||
``` | ||
|
||
Again, the output should be familiar: | ||
|
||
``` | ||
hello, world! | ||
``` | ||
|
||
### Daggerize a Go build | ||
|
||
The `hello` module is a good example to start with, but it doesn't have any functions to work with a Go project. To Daggerize the Go build for this example project, install the Go builder module from a previous section as another dependency: | ||
|
||
```shell | ||
dagger install github.com/kpenfound/dagger-modules/[email protected] | ||
git commit -m 'Added Go builder module' | ||
``` | ||
|
||
Then, call the `BuildContainer()` function from the Go builder module to build the project and publish a container image with the built binary: | ||
|
@@ -168,4 +127,4 @@ You should see the following output: | |
Hello, world! | ||
``` | ||
|
||
Your project is slowly becoming more and more Daggerized...you're now able to build it, containerize it and publish it, all with a single Dagger Function call. If you like, you can integrate this call into your existing shell scripts, or perhaps a Makefile. Or, you can create a custom Dagger Module, which enables you to connect one or more Dagger Functions together in portable, expressive workflows with all the benefits of a native programming language. | ||
Your project is slowly becoming more and more Daggerized...you're now able to build it, containerize it and publish it, all with a single Dagger Function call. If you like, you can integrate this call into your existing shell scripts, or perhaps a Makefile. Or, you can create a custom Dagger module, which enables you to connect one or more Dagger Functions together in portable, expressive workflows with all the benefits of a native programming language. |
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 |
---|---|---|
|
@@ -6,7 +6,6 @@ title: "Build a binary with a function" | |
|
||
# Quickstart | ||
|
||
|
||
## Build a binary with a function | ||
|
||
Not only can functions use Dagger's core types in their arguments; they can use them in their return value as well. | ||
|
@@ -21,7 +20,7 @@ Try calling this Go builder Dagger Function, which builds the Dagger CLI: | |
dagger -m github.com/kpenfound/dagger-modules/[email protected] call build --source=https://github.com/dagger/dagger --args=./cmd/dagger --os=$(uname -s | awk '{print tolower($0)}') | ||
``` | ||
|
||
This function takes a `source` argument of type `Directory`. Similar to how the CLI can pass a `Container` from a remote OCI address, it can also pass a `Directory` from a local path or remote Git address. Here, you're passing the address of Dagger's open-source repository. | ||
This function takes a `project` argument of type `Directory`. Here, you're passing the address of Dagger's open-source repository. It also takes an `args` argument, which is a list of strings representing the arguments to be passed to the `go build` command. | ||
|
||
:::note | ||
By default, the Go builder Dagger Function builds a binary based on information derived from the runtime container. Since the runtime container uses Linux, this usually means that the compiled binary will be a `linux/amd64` binary. This can be overridden by passing additional `--os` and `--arch` arguments to the Go builder Dagger Function. The previous example uses `uname` to dynamically derive the host operating system type, and passes that to the Dagger Function via the `--os` argument. | ||
|
@@ -84,7 +83,7 @@ dagger (registry.dagger.io/engine) linux/amd64 | |
``` | ||
|
||
:::tip | ||
As you've seen in the previous examples, Dagger modules can contain one or more functions, each with different arguments and return values. You can list all the functions available in a module with the `dagger functions` command, or append `--help` to any `dagger call` command to see a context-sensitive list of supported arguments and sub-commands. Try it with the Go builder module: | ||
As you've seen in the previous examples, Dagger modules can contain one or more Dagger Functions, each with different arguments and return values. You can list all the functions available in a module with the `dagger functions` command, or append `--help` to any `dagger call` command to see a context-sensitive list of supported arguments and sub-commands. Try it with the Go builder module: | ||
|
||
```shell | ||
dagger -m github.com/kpenfound/dagger-modules/[email protected] functions | ||
|
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 |
---|---|---|
|
@@ -15,12 +15,12 @@ Just as you can chain and return `Directory` types, you can also chain and retur | |
Try calling this function: | ||
|
||
```shell | ||
dagger -m github.com/shykes/daggerverse/[email protected] call container --packages=cowsay | ||
dagger -m github.com/shykes/daggerverse/[email protected] call container --packages=python3 | ||
``` | ||
|
||
This Wolfi container builder module exposes a `Container()` function that returns a base Wolfi container image, and accepts arguments to additional packages in the base image; | ||
|
||
You can use this function to build and return a Wolfi container image containing specific packages - in this example, the `cowsay` package. You should see the container being built and the packages being added, as shown below: | ||
You can use this function to build and return a Wolfi container image containing specific packages - in this example, the `python3` package. You should see the container being built and the packages being added, as shown below: | ||
|
||
``` | ||
Container evaluated. Use "dagger call base with-package container --help" to see available sub-commands. | ||
|
@@ -35,28 +35,22 @@ One of the most interesting `Container` functions is `Terminal()`, which can be | |
To see this in action, call the previous function again, this time chaining an additional function call to `Terminal()` on the returned `Container`: | ||
|
||
```shell | ||
dagger -m github.com/shykes/daggerverse/[email protected] call container --packages=cowsay terminal | ||
dagger -m github.com/shykes/daggerverse/[email protected] call \ | ||
container --packages=python3 terminal | ||
``` | ||
|
||
This revised command builds the container image and then drops you into an interactive terminal, allowing you to directly execute commands in the running container. | ||
|
||
Verify this by executing the following command: | ||
|
||
```shell | ||
cowsay "dagger" | ||
python3 -c "print('Hello from Dagger')" | ||
``` | ||
|
||
You should see output similar to the following: | ||
You should see the following output: | ||
|
||
``` | ||
________ | ||
< dagger > | ||
-------- | ||
\ ^__^ | ||
\ (oo)\_______ | ||
(__)\ )\/\ | ||
||----w | | ||
|| || | ||
```shell | ||
Hello from Dagger | ||
``` | ||
|
||
:::caution | ||
|
@@ -65,43 +59,46 @@ While most terminal programs such as `htop` or `vim` work with `dagger ... termi | |
|
||
### Execute commands in the container | ||
|
||
The `Container` type has a `WithExec()` function, which returns the container after executing a specific command inside it. So, you could achieve the same result as before (although non-interactively) by chaining a function call to `withExec()` on the `Container` returned previously, as shown in the following command: | ||
The `Container` type has a `WithExec()` function, which returns the container after executing a specific command inside it. So, you could achieve the same result as before (although non-interactively) by chaining function calls to `WithExec()` and `Stdout()` on the `Container` returned previously, as shown in the following command: | ||
|
||
```shell | ||
dagger -m github.com/shykes/daggerverse/[email protected] call \ | ||
container --packages=python3 \ | ||
with-exec --args=python3,-c,"print('Hello from Dagger')" \ | ||
stdout | ||
``` | ||
|
||
You should see the following output: | ||
|
||
```shell | ||
dagger -m github.com/shykes/daggerverse/[email protected] call container --packages=cowsay with-exec --args cowsay,dagger stdout | ||
Hello from Dagger | ||
``` | ||
|
||
### Publish the container image to a registry | ||
|
||
The `Container` type also has a `Publish()` function, which publishes the container to a registry. To see this in action, call the previous function again, this time chaining an additional function call to `Publish()` on the returned `Container`: | ||
The `Container` type also makes a number of other functions available. To see some of these in action, call the previous function again, chaining additional function calls to `WithEntrypoint()` and `Publish()` on the returned `Container` to set the container entrypoint command and publish it to a registry: | ||
|
||
```shell | ||
dagger -m github.com/shykes/daggerverse/[email protected] \ | ||
call container --packages=cowsay \ | ||
publish --address ttl.sh/dagger-cowsay-$RANDOM | ||
dagger -m github.com/shykes/daggerverse/[email protected] call \ | ||
container --packages=python3 \ | ||
with-entrypoint --args=python3,-c,"print('Hello from Dagger')" \ | ||
publish --address ttl.sh/dagger-$RANDOM | ||
``` | ||
|
||
The output will be a container image reference on the [ttl.sh container registry](https://ttl.sh), as shown below: | ||
|
||
``` | ||
ttl.sh/dagger-cowsay-10939@sha256:57c15999fdc59df452161f648aaa9b9a1ea9dbda710a0a0242f509966a286b4b | ||
```shell | ||
ttl.sh/dagger-10939@sha256:57c15999fdc59df452161f648aaa9b9a1ea9dbda710a0a0242f509966a286b4b | ||
``` | ||
|
||
Test the container image using the command below (remember to update the image reference based on the function output): | ||
|
||
```shell | ||
docker run --rm -it ttl.sh/dagger-cowsay-10939 cowsay "dagger" | ||
docker run --rm ttl.sh/dagger-10939 | ||
``` | ||
|
||
You should see the output below: | ||
You should see the following output: | ||
|
||
``` | ||
________ | ||
< dagger > | ||
-------- | ||
\ ^__^ | ||
\ (oo)\_______ | ||
(__)\ )\/\ | ||
||----w | | ||
|| || | ||
```shell | ||
Hello from Dagger | ||
``` |
Oops, something went wrong.