8000 docs: Add documentation and examples for mounts by vikram-dagger · Pull Request #10074 · dagger/dagger · GitHub
[go: up one dir, main page]
More Web Proxy on the site http://driver.im/
Skip to content

docs: Add documentation and examples for mounts #10074

New issue 8000

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
Apr 10, 2025
Merged

docs: Add documentation and examples for mounts #10074

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
6fb9e7d
docs: Add documentation and examples for mounts
vikram-dagger Apr 4, 2025
a908e11
Update docs/current_docs/api/fs-filters.mdx
vikram-dagger Apr 10, 2025
09b17c6
Update docs/current_docs/cookbook/cookbook.mdx
vikram-dagger Apr 10, 2025
394b0c0
Updated structure
vikram-dagger Apr 10, 2025
bf86483
Updated text
vikram-dagger Apr 10, 2025
65067ec
Added text
vikram-dagger Apr 10, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 15 additions & 0 deletions docs/current_docs/api/fs-filters.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -344,6 +344,21 @@ var dirOpts = new Container.WithDirectoryArguments()
</TabItem>
</Tabs>

## Mounts

When working with directories and files, you can choose whether to copy or mount them in the containers created by your Dagger Function. The Dagger API provides the following methods:

- `Container.withDirectory()` returns a container plus a directory written at the given path
- `Container.withFile()` returns a container plus a file written at the given path
- `Container.withMountedDirectory()` returns a container plus a directory mounted at the given path
- `Container.withMountedFile()` returns a container plus a file mounted at the given path

Mounts only take effect within your pipeline invocation; they are not copied to, or included, in the final image. In addition, any changes to mounted files and/or directories will only be reflected in the target directory and not in the mount sources.

:::tip
Besides helping with the final image size, mounts are more performant and resource-efficient. The rule of thumb should be to always use mounts where possible.
:::

## Debugging

### Using logs
Expand Down
231 changes: 222 additions & 9 deletions docs/current_docs/cookbook/cookbook.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,14 +9,49 @@ import TabItem from "@theme/TabItem";

## Filesystem

### Copy a directory or remote repository to a container
### Mount or copy a directory or remote repository to a container

The following Dagger Function accepts a `Directory` argument, which could reference either a directory from the local filesystem or from a [remote Git repository](../api/arguments.mdx#remote-repositories). It copies the specified directory to the `/src` path in a container and returns the modified container.
The following Dagger Function accepts a `Directory` argument, which could reference either a directory from the local filesystem or from a [remote Git repository](../api/arguments.mdx#remote-repositories). It mounts the specified directory to the `/src` path in a container and returns the modified container.

:::note
When working with private Git repositories, ensure that [SSH authentication is properly configured](../api/remote-repositories.mdx#ssh-authentication) on your Dagger host.
:::


<Tabs groupId="language">
<TabItem value="Go">

```go file=./snippets/mount-dir/go/main.go
```

</TabItem>
<TabItem value="Python">

```python file=./snippets/mount-dir/python/main.py
```

</TabItem>
<TabItem value="TypeScript">

```typescript file=./snippets/mount-dir/typescript/index.ts
```

</TabItem>

<TabItem value="PHP">

```php file=./snippets/mount-dir/php/src/MyModule.php
```

</TabItem>
</Tabs>

An alternative option is to copy the target directory in the container. The difference between these two approaches is that mounts only take effect within your pipeline invocation; they are not copied to, or included, in the final image. In addition, any changes to mounted files and/or directories will only be reflected in the target directory and not in the mount sources.

:::tip
Besides helping with the final image size, mounts are more performant and resource-efficient. The rule of thumb should be to always use mounts where possible.
:::

<Tabs groupId="language">
<TabItem value="Go">

Expand Down Expand Up @@ -47,6 +82,89 @@ When working with private Git repositories, ensure that [SSH authentication is p

#### Examples

- Mount the `/myapp` host directory to `/src` in the container and return the modified container:

<Tabs groupId="shell">
<TabItem value="System shell">
```shell
dagger -c 'mount-directory ./myapp/'
```
</TabItem>
<TabItem value="Dagger Shell">
```shell title="First type 'dagger' for interactive mode."
mount-directory ./myapp/
```
</TabItem>
<TabItem value="Dagger CLI">
```shell
dagger call mount-directory --source=./myapp/
```
</TabItem>
</Tabs>

- Mount the public `dagger/dagger` GitHub repository to `/src` in the container and return the modified container:

<Tabs groupId="shell">
<TabItem value="System shell">
```shell
dagger -c 'mount-directory https://github.com/dagger/dagger#main'
```
</TabItem>
<TabItem value="Dagger Shell">
```shell title="First type 'dagger' for interactive mode."
mount-directory https://github.com/dagger/dagger#main
```
</TabItem>
<TabItem value="Dagger CLI">
```shell
dagger call mount-directory --source=https://github.com/dagger/dagger#main
```
</TabItem>
</Tabs>

- Mo 5D32 unt the private `user/foo` GitHub repository to `/src` in the container and return the modified container:

<Tabs groupId="shell">
<TabItem value="System shell">
```shell
dagger -c 'mount-directory ssh://git@github.com/user/foo#main'
```
</TabItem>
<TabItem value="Dagger Shell">
```shell title="First type 'dagger' for interactive mode."
mount-directory ssh://git@github.com/user/foo#main
```
</TabItem>
<TabItem value="Dagger CLI">
```shell
dagger call mount-directory --source=ssh://git@github.com/user/foo#main
```
</TabItem>
</Tabs>

- Mount the public `dagger/dagger` GitHub repository to `/src` in the container and list the contents of the directory:

<Tabs groupId="shell">
<TabItem value="System shell">
```shell
dagger -c 'mount-directory https://github.com/dagger/dagger#main | directory /src | entries'
```
</TabItem>
<TabItem value="Dagger Shell">
```shell title="First type 'dagger' for interactive mode."
mount-directory https://github.com/dagger/dagger#main | directory /src | entries
```
</TabItem>
<TabItem value="Dagger CLI">
```shell
dagger call \
mount-directory --source=https://github.com/dagger/dagger#main \
directory --path=/src \
entries
```
</TabItem>
</Tabs>

- Copy the `/myapp` host directory to `/src` in the container and return the modified container:

<Tabs groupId="shell">
Expand All @@ -72,17 +190,17 @@ When working with private Git repositories, ensure that [SSH authentication is p
<Tabs groupId="shell">
<TabItem value="System shell">
```shell
dagger -c 'copy-directory github.com/dagger/dagger#main'
dagger -c 'copy-directory https://github.com/dagger/dagger#main'
```
</TabItem>
<TabItem value="Dagger Shell">
```shell title="First type 'dagger' for interactive mode."
copy-directory github.com/dagger/dagger#main
copy-directory https://github.com/dagger/dagger#main
```
</TabItem>
<TabItem value="Dagger CLI">
```shell
dagger call copy-directory --source=github.com/dagger/dagger#main
dagger call copy-directory --source=https://github.com/dagger/dagger#main
```
</TabItem>
</Tabs>
Expand Down Expand Up @@ -387,9 +505,36 @@ For examples of SSH-based cloning, including private or public Git repositories
dagger call clone-with-ssh --repository=git@github.com:dagger/dagger.git --ref=196f232a4d6b2d1d3db5f5e040cf20b6a76a76c5 --sock $SSH_AUTH_SOCK terminal
```

### Copy a local or remote file to a container
### Mount or copy a local or remote file to a container

The following Dagger Function accepts a `File` argument, which could reference either a file from the local filesystem or from a [remote Git repository](../api/arguments.mdx#remote-repositories). It writes the specified file to a container in the `/src/` directory and returns the modified container.
The following Dagger Function accepts a `File` argument, which could reference either a file from the local filesystem or from a [remote Git repository](../api/arguments.mdx#remote-repositories). It mounts the specified file to a container in the `/src/` directory and returns the modified container.

<Tabs groupId="language">
<TabItem value="Go">

```go file=./snippets/mount-file/go/main.go
```

</TabItem>
<TabItem value="Python">

```python file=./snippets/mount-file/python/main.py
```

</TabItem>
<TabItem value="TypeScript">

```typescript file=./snippets/mount-file/typescript/index.ts
```

</TabItem>
</Tabs>

An alternative option is to copy the target file to the container. The difference between these two approaches is that mounts only take effect within your pipeline invocation; they are not copied to, or included, in the final image. In addition, any changes to mounted files and/or directories will only be reflected in the target directory and not in the mount sources.

:::tip
Besides helping with the final image size, mounts are more performant and resource-efficient. The rule of thumb should be to always use mounts where possible.
:::

<Tabs groupId="language">
<TabItem value="Go">
Expand All @@ -412,9 +557,77 @@ The following Dagger Function accepts a `File` argument, which could reference e
</TabItem>
</Tabs>


#### Example

- Copy the `/home/admin/archives.zip` file on the host to the `/src` directory in the container and return the modified container:
- Mount the `/home/admin/archives.zip` file on the host to the `/src` directory in the container and return the modified container:

<Tabs groupId="shell">
<TabItem value="System shell">
```shell
dagger -c 'mount-file /home/admin/archives.zip'
```
</TabItem>
<TabItem value="Dagger Shell">
```shell title="First type 'dagger' for interactive mode."
mount-file /home/admin/archives.zip
```
</TabItem>
<TabItem value="Dagger CLI">
```shell
dagger call mount-file --f=/home/admin/archives.zip
```
</TabItem>
</Tabs>

- Mount the `README.md` file from the public `dagger/dagger` GitHub repository to the `/src` directory in the container:

<Tabs groupId="shell">
<TabItem value="System shell">
```shell
dagger -c 'mount-file https://github.com/dagger/dagger.git#main:README.md'
```
</TabItem>
<TabItem value="Dagger Shell">
```shell title="First type 'dagger' for interactive mode."
mount-file https://github.com/dagger/dagger.git#main:README.md
```
</TabItem>
<TabItem value="Dagger CLI">
```shell
dagger call mount-file --f=https://github.com/dagger/dagger.git#main:README.md
```
</TabItem>
</Tabs>

- Mount the `README.md` file from the public `dagger/dagger` GitHub repository to the `/src` directory in the container and display its contents:

<Tabs groupId="shell">
<TabItem value="System shell">
```shell
dagger <<EOF
mount-file https://github.com/dagger/dagger.git#main:README.md |
file /src/README.md |
contents
EOF
```
</TabItem>
<TabItem value="Dagger Shell">
```shell title="First type 'dagger' for interactive mode."
mount-file https://github.com/dagger/dagger.git#main:README.md | file /src/README.md | contents
```
</TabItem>
<TabItem value="Dagger CLI">
```shell
dagger call \
mount-file --f=https://github.com/dagger/dagger.git#main:README.md \
file --path=/src/README.md \
contents
```
</TabItem>
</Tabs>

- Copy the `/home/admin/archives.zip` file on the host to the `/src` directory in the container and return the modified container:

<Tabs groupId="shell">
<TabItem value="System shell">
Expand All @@ -434,7 +647,7 @@ The following Dagger Function accepts a `File` argument, which could reference e
</TabItem>
</Tabs>

- Copy the `/home/admin/archives.zip` file on the host to the `/src` directory in the container and list the contents of the directory:
- Copy the `/home/admin/archives.zip` file on the host to the `/src` directory in the container and list the contents of the directory:

<Tabs groupId="shell">
<TabItem value="System shell">
Expand Down
4 changes: 4 additions & 0 deletions docs/current_docs/cookbook/snippets/mount-dir/go/.gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
/dagger.gen.go
/internal/dagger
/internal/querybuilder
/internal/telemetry
6 changes: 6 additions & 0 deletions docs/current_docs/cookbook/snippets/mount-dir/go/dagger.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
{
"name": "my-module",
"sdk": "go",
"source": ".",
"engineVersion": "v0.12.0"
}
40 changes: 40 additions & 0 deletions docs/current_docs/cookbook/snippets/mount-dir/go/go.mod
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,40 @@
module dagger/my-module

go 1.21.7

require (
github.com/99designs/gqlgen v0.17.49
github.com/Khan/genqlient v0.7.0
github.com/vektah/gqlparser/v2 v2.5.16
go.opentelemetry.io/otel v1.27.0
go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracegrpc v1.27.0
go.opentelemetry.io/otel/exporters/otlp/otlptrace/otlptracehttp v1.27.0
go.opentelemetry.io/otel/sdk v1.27.0
go.opentelemetry.io/otel/trace v1.27.0
golang.org/x/exp v0.0.0-20231110203233-9a3e6036ecaa
golang.org/x/sync v0.10.0
google.golang.org/grpc v1.64.0
)

require (
github.com/cenkalti/backoff/v4 v4.3.0 // indirect
github.com/go-logr/logr v1.4.1 // indirect
github.com/go-logr/stdr v1.2.2 // indirect
github.com/google/uuid v1.6.0 // indirect
github.com/grpc-ecosystem/grpc-gateway/v2 v2.20.0 // indirect
github.com/sergi/go-diff v1.3.2-0.20230802210424-5b0b94c5c0d3 // indirect
github.com/sosodev/duration v1.3.1 // indirect
go.opentelemetry.io/otel/exporters/otlp/otlplog/otlploggrpc v0.0.0-20240518090000-14441aefdf88
go.opentelemetry.io/otel/exporters/otlp/otlplog/otlploghttp v0.3.0
go.opentelemetry.io/otel/exporters/otlp/otlptrace v1.27.0 // indirect
go.opentelemetry.io/otel/log v0.3.0
go.opentelemetry.io/otel/metric v1.27.0 // indirect
go.opentelemetry.io/otel/sdk/log v0.3.0
go.opentelemetry.io/proto/otlp v1.3.1
golang.org/x/net v0.33.0 // indirect
golang.org/x/sys v0.28.0 // indirect
golang.org/x/text v0.21.0 // indirect
google.golang.org/genproto/googleapis/api v0.0.0-20240520151616-dc85e6b867a5 // indirect
google.golang.org/genproto/googleapis/rpc v0.0.0-20240515191416-fc5f0ca64291 // indirect
google.golang.org/protobuf v1.34.1 // indirect
)
Loading
Loading
0