diff --git a/docs/features/files_and_mounts.md b/docs/features/files_and_mounts.md index bae6caa6e1..fff2b06857 100644 --- a/docs/features/files_and_mounts.md +++ b/docs/features/files_and_mounts.md @@ -2,38 +2,6 @@ Copying data of any type into a container is a very common practice when working with containers. This section will show you how to do it using _Testcontainers for Go_. -## Volume mapping - -It is possible to map a Docker volume into the container using the `Mounts` attribute at the `ContainerRequest` struct. For that, please pass an instance of the `GenericVolumeMountSource` type, which allows you to specify the name of the volume to be mapped, and the path inside the container where it should be mounted: - - -[Volume mounts](../../mounts_test.go) inside_block:volumeMounts - - -!!!tip - This ability of creating volumes is also available for remote Docker hosts. - -!!!warning - Bind mounts are not supported, as it could not work with remote Docker hosts. - -!!!tip - It is recommended to copy data from your local host machine to a test container using the file copy API - described below, as it is much more portable. - -## Mounting images - -Since Docker v28, it is possible to mount the file system of an image into a container using the `Mounts` attribute at the `ContainerRequest` struct. For that, use the `DockerImageMountSource` type, which allows you to specify the name of the image to be mounted, and the subpath inside the container where it should be mounted, or simply call the `ImageMount` function, which does exactly that: - - -[Image mounts](../../lifecycle_test.go) inside_block:imageMounts - - -!!!warning - If the subpath is not a relative path, the creation of the container will fail. - -!!!info - Mounting images fails the creation of the container if the underlying container runtime does not support the `image mount` feature, which is available since Docker v28. - ## Copying files to a container If you would like to copy a file to a container, you can do it in two different manners: @@ -67,7 +35,7 @@ It's also possible to copy an entire directory to a container, and that can happ It's important to notice that, when copying the directory to the container, the container path must exist in the Docker image. And this is a strong requirement for files to be copied _before_ the container is started, as we cannot create the full path at that time. -You can leverage the very same mechanism used for copying files to a container, but for directories.: +You can leverage the very same mechanism used for copying files to a container, but for directories: 1. The first way is using the `Files` field in the `ContainerRequest` struct, as shown in the previous section, but using the path of a directory as `HostFilePath`. Like so: @@ -86,3 +54,46 @@ You can leverage the very same mechanism used for copying files to a container, [Copying a directory to a running container](../../docker_files_test.go) inside_block:copyDirectoryToRunningContainerAsDir + +## Copying files from a container + +It's also possible to copy files from a container to the host machine. This can be done by using the `CopyFileFromContainer` method on the `Container` type, which will return an error and an `io.ReadCloser` that you can use to read the file content. + + +[Copying a file from a container](../../examples_test.go) inside_block:copyFileFromContainer + + +In the above example, we previously copied the file `/tmp/file.txt` to the container, and then we copied it back to the host machine, reading the content of the file. + +## Volume mapping + +It is possible to map a Docker volume into the container using the `Mounts` attribute at the `ContainerRequest` struct. For that, please pass an instance of the `GenericVolumeMountSource` type, which allows you to specify the name of the volume to be mapped, and the path inside the container where it should be mounted: + + +[Volume mounts](../../mounts_test.go) inside_block:volumeMounts + + +!!!tip + This ability of creating volumes is also available for remote Docker hosts. + +!!!warning + Bind mounts are not supported, as it could not work with remote Docker hosts. + +!!!tip + It is recommended to copy data from your local host machine to a test container using the file copy API + described below, as it is much more portable. + +## Mounting images + +Since Docker v28, it is possible to mount the file system of an image into a container using the `Mounts` attribute at the `ContainerRequest` struct. For that, use the `DockerImageMountSource` type, which allows you to specify the name of the image to be mounted, and the subpath inside the container where it should be mounted, or simply call the `ImageMount` function, which does exactly that: + + +[Image mounts](../../lifecycle_test.go) inside_block:imageMounts + + +!!!warning + If the subpath is not a relative path, the creation of the container will fail. + +!!!info + Mounting images fails the creation of the container if the underlying container runtime does not support the `image mount` feature, which is available since Docker v28. + diff --git a/examples_test.go b/examples_test.go index 69611458e6..d5225222e2 100644 --- a/examples_test.go +++ b/examples_test.go @@ -103,7 +103,8 @@ func ExampleRun() { fmt.Println(ctrResp.Config.Labels["testcontainers.label"]) // files - f, err := ctr.CopyFileFromContainer(ctx, "/tmp/file.txt") + // copyFileFromContainer { + f, err := ctr.CopyFileFromContainer(context.Background(), "/tmp/file.txt") if err != nil { log.Printf("failed to copy file from container: %s", err) return @@ -114,6 +115,7 @@ func ExampleRun() { log.Printf("failed to read file: %s", err) return } + // } fmt.Println(string(content)) // Output: