class Container extends AbstractObject implements IdAble

An OCI-compatible container, also known as a Docker container.

Properties

$lastQuery from  AbstractObject

Methods

__construct(AbstractClient $client, QueryBuilderChain $queryBuilderChain)

No description

null|array|string|int|float|bool
queryLeaf(QueryBuilder $leafQueryBuilder, string $leafKey)

No description

asService(array|null $args = null, bool|null $useEntrypoint = false, bool|null $experimentalPrivilegedNesting = false, bool|null $insecureRootCapabilities = false, bool|null $expand = false, bool|null $noInit = false)

Turn the container into a Service.

asTarball(array|null $platformVariants = null, ImageLayerCompression|null $forcedCompression = null, ImageMediaTypes|null $mediaTypes = null)

Package the container state as an OCI image, and return it as a tar archive

build(Directory $context, string|null $dockerfile = 'Dockerfile', string|null $target = '', array|null $buildArgs = null, array|null $secrets = null, bool|null $noInit = false)

Initializes this container from a Dockerfile build.

array
defaultArgs()

Return the container's default arguments.

directory(string $path, bool|null $expand = false)

Retrieve a directory from the container's root filesystem

array
entrypoint()

Return the container's OCI entrypoint.

string
envVariable(string $name)

Retrieves the value of the specified environment variable.

array
envVariables()

Retrieves the list of environment variables passed to commands.

int
exitCode()

The exit code of the last executed command

experimentalWithAllGPUs()

EXPERIMENTAL API! Subject to change/removal at any time.

experimentalWithGPU(array $devices)

EXPERIMENTAL API! Subject to change/removal at any time.

string
export(string $path, array|null $platformVariants = null, ImageLayerCompression|null $forcedCompression = null, ImageMediaTypes|null $mediaTypes = null, bool|null $expand = false)

Writes the container as an OCI tarball to the destination file path on the host.

array
exposedPorts()

Retrieves the list of exposed ports.

file(string $path, bool|null $expand = false)

Retrieves a file at the given path.

from(string $address)

Download a container image, and apply it to the container state. All previous state will be lost.

id()

A unique identifier for this Container.

string
imageRef()

The unique image reference which can only be retrieved immediately after the 'Container.From' call.

import(File $source, string|null $tag = '')

Reads the container from an OCI tarball.

string
label(string $name)

Retrieves the value of the specified label.

array
labels()

Retrieves the list of labels passed to container.

array
mounts()

Retrieves the list of paths where a directory is mounted.

platform()

The platform this container executes and publishes as.

string
publish(string $address, array|null $platformVariants = null, ImageLayerCompression|null $forcedCompression = null, ImageMediaTypes|null $mediaTypes = null)

Package the container state as an OCI image, and publish it to a registry

rootfs()

Return a snapshot of the container's root filesystem. The snapshot can be modified then written back using withRootfs. Use that method for filesystem modifications.

string
stderr()

The buffered standard error stream of the last executed command

string
stdout()

The buffered standard output stream of the last executed command

sync()

Forces evaluation of the pipeline in the engine.

terminal(array|null $cmd = null, bool|null $experimentalPrivilegedNesting = false, bool|null $insecureRootCapabilities = false)

Opens an interactive terminal for this container using its configured default terminal command if not overridden by args (or sh as a fallback default).

void
up(array|null $ports = null, bool|null $random = false, array|null $args = null, bool|null $useEntrypoint = false, bool|null $experimentalPrivilegedNesting = false, bool|null $insecureRootCapabilities = false, bool|null $expand = false, bool|null $noInit = false)

Starts a Service and creates a tunnel that forwards traffic from the caller's network to that service.

string
user()

Retrieves the user to be set for all commands.

withAnnotation(string $name, string $value)

Retrieves this container plus the given OCI anotation.

withDefaultArgs(array $args)

Configures default arguments for future commands. Like CMD in Dockerfile.

withDefaultTerminalCmd(array $args, bool|null $experimentalPrivilegedNesting = false, bool|null $insecureRootCapabilities = false)

Set the default command to invoke for the container's terminal API.

withDirectory(string $path, Directory $directory, array|null $exclude = null, array|null $include = null, string|null $owner = '', bool|null $expand = false)

Return a new container snapshot, with a directory added to its filesystem

withEntrypoint(array $args, bool|null $keepDefaultArgs = false)

Set an OCI-style entrypoint. It will be included in the container's OCI configuration. Note, withExec ignores the entrypoint by default.

withEnvVariable(string $name, string $value, bool|null $expand = false)

Set a new environment variable in the container.

withExec(array $args, bool|null $useEntrypoint = false, string|null $stdin = '', string|null $redirectStdout = '', string|null $redirectStderr = '', ReturnType|null $expect = null, bool|null $experimentalPrivilegedNesting = false, bool|null $insecureRootCapabilities = false, bool|null $expand = false, bool|null $noInit = false)

Execute a command in the container, and return a new snapshot of the container state after execution.

withExposedPort(int $port, NetworkProtocol|null $protocol = null, string|null $description = null, bool|null $experimentalSkipHealthcheck = false)

Expose a network port. Like EXPOSE in Dockerfile (but with healthcheck support)

withFile(string $path, File $source, int|null $permissions = null, string|null $owner = '', bool|null $expand = false)

Return a container snapshot with a file added

withFiles(string $path, array $sources, int|null $permissions = null, string|null $owner = '', bool|null $expand = false)

Retrieves this container plus the contents of the given files copied to the given path.

withLabel(string $name, string $value)

Retrieves this container plus the given label.

withMountedCache(string $path, CacheVolume $cache, Directory|null $source = null, CacheSharingMode|null $sharing = null, string|null $owner = '', bool|null $expand = false)

Retrieves this container plus a cache volume mounted at the given path.

withMountedDirectory(string $path, Directory $source, string|null $owner = '', bool|null $expand = false)

Retrieves this container plus a directory mounted at the given path.

withMountedFile(string $path, File $source, string|null $owner = '', bool|null $expand = false)

Retrieves this container plus a file mounted at the given path.

withMountedSecret(string $path, Secret $source, string|null $owner = '', int|null $mode = 256, bool|null $expand = false)

Retrieves this container plus a secret mounted into a file at the given path.

withMountedTemp(string $path, int|null $size = null, bool|null $expand = false)

Retrieves this container plus a temporary directory mounted at the given path. Any writes will be ephemeral to a single withExec call; they will not be persisted to subsequent withExecs.

withNewFile(string $path, string $contents, int|null $permissions = 420, string|null $owner = '', bool|null $expand = false)

Return a new container snapshot, with a file added to its filesystem with text content

withRegistryAuth(string $address, string $username, Secret $secret)

Attach credentials for future publishing to a registry. Use in combination with publish

withRootfs(Directory $directory)

Change the container's root filesystem. The previous root filesystem will be lost.

withSecretVariable(string $name, Secret $secret)

Set a new environment variable, using a secret value

withServiceBinding(string $alias, Service $service)

Establish a runtime dependency on a from a container to a network service.

withUnixSocket(string $path, Socket $source, string|null $owner = '', bool|null $expand = false)

Retrieves this container plus a socket forwarded to the given Unix socket path.

withUser(string $name)

Retrieves this container with a different command user.

withWorkdir(string $path, bool|null $expand = false)

Change the container's working directory. Like WORKDIR in Dockerfile.

withoutAnnotation(string $name)

Retrieves this container minus the given OCI annotation.

withoutDefaultArgs()

Remove the container's default arguments.

withoutDirectory(string $path, bool|null $expand = false)

Return a new container snapshot, with a directory removed from its filesystem

withoutEntrypoint(bool|null $keepDefaultArgs = false)

Reset the container's OCI entrypoint.

withoutEnvVariable(string $name)

Retrieves this container minus the given environment variable.

withoutExposedPort(int $port, NetworkProtocol|null $protocol = null)

Unexpose a previously exposed port.

withoutFile(string $path, bool|null $expand = false)

Retrieves this container with the file at the given path removed.

withoutFiles(array $paths, bool|null $expand = false)

Return a new container spanshot with specified files removed

withoutLabel(string $name)

Retrieves this container minus the given environment label.

withoutMount(string $path, bool|null $expand = false)

Retrieves this container after unmounting everything at the given path.

withoutRegistryAuth(string $address)

Retrieves this container without the registry authentication of a given address.

withoutSecretVariable(string $name)

Retrieves this container minus the given environment variable containing the secret.

withoutUnixSocket(string $path, bool|null $expand = false)

Retrieves this container with a previously added Unix socket removed.

withoutUser()

Retrieves this container with an unset command user.

withoutWorkdir()

Unset the container's working directory.

string
workdir()

Retrieves the working directory for all commands.

Details

in AbstractObject at line 13
__construct(AbstractClient $client, QueryBuilderChain $queryBuilderChain)

No description

Parameters

AbstractClient $client
QueryBuilderChain $queryBuilderChain

in AbstractObject at line 19
protected null|array|string|int|float|bool queryLeaf(QueryBuilder $leafQueryBuilder, string $leafKey)

No description

Parameters

QueryBuilder $leafQueryBuilder
string $leafKey

Return Value

null|array|string|int|float|bool

at line 21
Service asService(array|null $args = null, bool|null $useEntrypoint = false, bool|null $experimentalPrivilegedNesting = false, bool|null $insecureRootCapabilities = false, bool|null $expand = false, bool|null $noInit = false)

Turn the container into a Service.

Be sure to set any exposed ports before this conversion.

Parameters

array|null $args
bool|null $useEntrypoint
bool|null $experimentalPrivilegedNesting
bool|null $insecureRootCapabilities
bool|null $expand
bool|null $noInit

Return Value

Service

at line 54
File asTarball(array|null $platformVariants = null, ImageLayerCompression|null $forcedCompression = null, ImageMediaTypes|null $mediaTypes = null)

Package the container state as an OCI image, and return it as a tar archive

Parameters

array|null $platformVariants
ImageLayerCompression|null $forcedCompression
ImageMediaTypes|null $mediaTypes

Return Value

File

at line 75
Container build(Directory $context, string|null $dockerfile = 'Dockerfile', string|null $target = '', array|null $buildArgs = null, array|null $secrets = null, bool|null $noInit = false)

Initializes this container from a Dockerfile build.

Parameters

Directory $context
string|null $dockerfile
string|null $target
array|null $buildArgs
array|null $secrets
bool|null $noInit

Return Value

Container

at line 106
array defaultArgs()

Return the container's default arguments.

Return Value

array

at line 117
Directory directory(string $path, bool|null $expand = false)

Retrieve a directory from the container's root filesystem

Mounts are included.

Parameters

string $path
bool|null $expand

Return Value

Directory

at line 130
array entrypoint()

Return the container's OCI entrypoint.

Return Value

array

at line 139
string envVariable(string $name)

Retrieves the value of the specified environment variable.

Parameters

string $name

Return Value

string

at line 149
array envVariables()

Retrieves the list of environment variables passed to commands.

Return Value

array

at line 160
int exitCode()

The exit code of the last executed command

Returns an error if no command was executed

Return Value

int

at line 173
Container experimentalWithAllGPUs()

EXPERIMENTAL API! Subject to change/removal at any time.

Configures all available GPUs on the host to be accessible to this container.

This currently works for Nvidia devices only.

Return Value

Container

at line 186
Container experimentalWithGPU(array $devices)

EXPERIMENTAL API! Subject to change/removal at any time.

Configures the provided list of devices to be accessible to this container.

This currently works for Nvidia devices only.

Parameters

array $devices

Return Value

Container

at line 198
string export(string $path, array|null $platformVariants = null, ImageLayerCompression|null $forcedCompression = null, ImageMediaTypes|null $mediaTypes = null, bool|null $expand = false)

Writes the container as an OCI tarball to the destination file path on the host.

It can also export platform variants.

Parameters

string $path
array|null $platformVariants
ImageLayerCompression|null $forcedCompression
ImageMediaTypes|null $mediaTypes
bool|null $expand

Return Value

string

at line 227
array exposedPorts()

Retrieves the list of exposed ports.

This includes ports already exposed by the image, even if not explicitly added with dagger.

Return Value

array

at line 238
File file(string $path, bool|null $expand = false)

Retrieves a file at the given path.

Mounts are included.

Parameters

string $path
bool|null $expand

Return Value

File

at line 251
Container from(string $address)

Download a container image, and apply it to the container state. All previous state will be lost.

Parameters

string $address

Return Value

Container

at line 261
AbstractId id()

A unique identifier for this Container.

Return Value

AbstractId

at line 270
string imageRef()

The unique image reference which can only be retrieved immediately after the 'Container.From' call.

Return Value

string

at line 279
Container import(File $source, string|null $tag = '')

Reads the container from an OCI tarball.

Parameters

File $source
string|null $tag

Return Value

Container

at line 292
string label(string $name)

Retrieves the value of the specified label.

Parameters

string $name

Return Value

string

at line 302
array labels()

Retrieves the list of labels passed to container.

Return Value

array

at line 311
array mounts()

Retrieves the list of paths where a directory is mounted.

Return Value

array

at line 320
Platform platform()

The platform this container executes and publishes as.

Return Value

Platform

at line 331
string publish(string $address, array|null $platformVariants = null, ImageLayerCompression|null $forcedCompression = null, ImageMediaTypes|null $mediaTypes = null)

Package the container state as an OCI image, and publish it to a registry

Returns the fully qualified address of the published image, with digest

Parameters

string $address
array|null $platformVariants
ImageLayerCompression|null $forcedCompression
ImageMediaTypes|null $mediaTypes

Return Value

string

at line 354
Directory rootfs()

Return a snapshot of the container's root filesystem. The snapshot can be modified then written back using withRootfs. Use that method for filesystem modifications.

Return Value

Directory

at line 365
string stderr()

The buffered standard error stream of the last executed command

Returns an error if no command was executed

Return Value

string

at line 376
string stdout()

The buffered standard output stream of the last executed command

Returns an error if no command was executed

Return Value

string

at line 387
ContainerId sync()

Forces evaluation of the pipeline in the engine.

It doesn't run the default command if no exec has been set.

Return Value

ContainerId

at line 396
Container terminal(array|null $cmd = null, bool|null $experimentalPrivilegedNesting = false, bool|null $insecureRootCapabilities = false)

Opens an interactive terminal for this container using its configured default terminal command if not overridden by args (or sh as a fallback default).

Parameters

array|null $cmd
bool|null $experimentalPrivilegedNesting
bool|null $insecureRootCapabilities

Return Value

Container

at line 419
void up(array|null $ports = null, bool|null $random = false, array|null $args = null, bool|null $useEntrypoint = false, bool|null $experimentalPrivilegedNesting = false, bool|null $insecureRootCapabilities = false, bool|null $expand = false, bool|null $noInit = false)

Starts a Service and creates a tunnel that forwards traffic from the caller's network to that service.

Be sure to set any exposed ports before calling this api.

Parameters

array|null $ports
bool|null $random
array|null $args
bool|null $useEntrypoint
bool|null $experimentalPrivilegedNesting
bool|null $insecureRootCapabilities
bool|null $expand
bool|null $noInit

Return Value

void

at line 460
string user()

Retrieves the user to be set for all commands.

Return Value

string

at line 469
Container withAnnotation(string $name, string $value)

Retrieves this container plus the given OCI anotation.

Parameters

string $name
string $value

Return Value

Container

at line 480
Container withDefaultArgs(array $args)

Configures default arguments for future commands. Like CMD in Dockerfile.

Parameters

array $args

Return Value

Container

at line 490
Container withDefaultTerminalCmd(array $args, bool|null $experimentalPrivilegedNesting = false, bool|null $insecureRootCapabilities = false)

Set the default command to invoke for the container's terminal API.

Parameters

array $args
bool|null $experimentalPrivilegedNesting
bool|null $insecureRootCapabilities

Return Value

Container

at line 509
Container withDirectory(string $path, Directory $directory, array|null $exclude = null, array|null $include = null, string|null $owner = '', bool|null $expand = false)

Return a new container snapshot, with a directory added to its filesystem

Parameters

string $path
Directory $directory
array|null $exclude
array|null $include
string|null $owner
bool|null $expand

Return Value

Container

at line 538
Container withEntrypoint(array $args, bool|null $keepDefaultArgs = false)

Set an OCI-style entrypoint. It will be included in the container's OCI configuration. Note, withExec ignores the entrypoint by default.

Parameters

array $args
bool|null $keepDefaultArgs

Return Value

Container

at line 551
Container withEnvVariable(string $name, string $value, bool|null $expand = false)

Set a new environment variable in the container.

Parameters

string $name
string $value
bool|null $expand

Return Value

Container

at line 565
Container withExec(array $args, bool|null $useEntrypoint = false, string|null $stdin = '', string|null $redirectStdout = '', string|null $redirectStderr = '', ReturnType|null $expect = null, bool|null $experimentalPrivilegedNesting = false, bool|null $insecureRootCapabilities = false, bool|null $expand = false, bool|null $noInit = false)

Execute a command in the container, and return a new snapshot of the container state after execution.

Parameters

array $args
bool|null $useEntrypoint
string|null $stdin
string|null $redirectStdout
string|null $redirectStderr
ReturnType|null $expect
bool|null $experimentalPrivilegedNesting
bool|null $insecureRootCapabilities
bool|null $expand
bool|null $noInit

Return Value

Container

at line 618
Container withExposedPort(int $port, NetworkProtocol|null $protocol = null, string|null $description = null, bool|null $experimentalSkipHealthcheck = false)

Expose a network port. Like EXPOSE in Dockerfile (but with healthcheck support)

Exposed ports serve two purposes:

  • For health checks and introspection, when running services

  • For setting the EXPOSE OCI field when publishing the container

Parameters

int $port
NetworkProtocol|null $protocol
string|null $description
bool|null $experimentalSkipHealthcheck

Return Value

Container

at line 641
Container withFile(string $path, File $source, int|null $permissions = null, string|null $owner = '', bool|null $expand = false)

Return a container snapshot with a file added

Parameters

string $path
File $source
int|null $permissions
string|null $owner
bool|null $expand

Return Value

Container

at line 666
Container withFiles(string $path, array $sources, int|null $permissions = null, string|null $owner = '', bool|null $expand = false)

Retrieves this container plus the contents of the given files copied to the given path.

Parameters

string $path
array $sources
int|null $permissions
string|null $owner
bool|null $expand

Return Value

Container

at line 691
Container withLabel(string $name, string $value)

Retrieves this container plus the given label.

Parameters

string $name
string $value

Return Value

Container

at line 702
Container withMountedCache(string $path, CacheVolume $cache, Directory|null $source = null, CacheSharingMode|null $sharing = null, string|null $owner = '', bool|null $expand = false)

Retrieves this container plus a cache volume mounted at the given path.

Parameters

string $path
CacheVolume $cache
Directory|null $source
CacheSharingMode|null $sharing
string|null $owner
bool|null $expand

Return Value

Container

at line 731
Container withMountedDirectory(string $path, Directory $source, string|null $owner = '', bool|null $expand = false)

Retrieves this container plus a directory mounted at the given path.

Parameters

string $path
Directory $source
string|null $owner
bool|null $expand

Return Value

Container

at line 752
Container withMountedFile(string $path, File $source, string|null $owner = '', bool|null $expand = false)

Retrieves this container plus a file mounted at the given path.

Parameters

string $path
File $source
string|null $owner
bool|null $expand

Return Value

Container

at line 773
Container withMountedSecret(string $path, Secret $source, string|null $owner = '', int|null $mode = 256, bool|null $expand = false)

Retrieves this container plus a secret mounted into a file at the given path.

Parameters

string $path
Secret $source
string|null $owner
int|null $mode
bool|null $expand

Return Value

Container

at line 798
Container withMountedTemp(string $path, int|null $size = null, bool|null $expand = false)

Retrieves this container plus a temporary directory mounted at the given path. Any writes will be ephemeral to a single withExec call; they will not be persisted to subsequent withExecs.

Parameters

string $path
int|null $size
bool|null $expand

Return Value

Container

at line 814
Container withNewFile(string $path, string $contents, int|null $permissions = 420, string|null $owner = '', bool|null $expand = false)

Return a new container snapshot, with a file added to its filesystem with text content

Parameters

string $path
string $contents
int|null $permissions
string|null $owner
bool|null $expand

Return Value

Container

at line 839
Container withRegistryAuth(string $address, string $username, Secret $secret)

Attach credentials for future publishing to a registry. Use in combination with publish

Parameters

string $address
string $username
Secret $secret

Return Value

Container

at line 851
Container withRootfs(Directory $directory)

Change the container's root filesystem. The previous root filesystem will be lost.

Parameters

Directory $directory

Return Value

Container

at line 861
Container withSecretVariable(string $name, Secret $secret)

Set a new environment variable, using a secret value

Parameters

string $name
Secret $secret

Return Value

Container

at line 878
Container withServiceBinding(string $alias, Service $service)

Establish a runtime dependency on a from a container to a network service.

The service will be started automatically when needed and detached when it is no longer needed, executing the default command if none is set.

The service will be reachable from the container via the provided hostname alias.

The service dependency will also convey to any files or directories produced by the container.

Parameters

string $alias
Service $service

Return Value

Container

at line 889
Container withUnixSocket(string $path, Socket $source, string|null $owner = '', bool|null $expand = false)

Retrieves this container plus a socket forwarded to the given Unix socket path.

Parameters

string $path
Socket $source
string|null $owner
bool|null $expand

Return Value

Container

at line 910
Container withUser(string $name)

Retrieves this container with a different command user.

Parameters

string $name

Return Value

Container

at line 920
Container withWorkdir(string $path, bool|null $expand = false)

Change the container's working directory. Like WORKDIR in Dockerfile.

Parameters

string $path
bool|null $expand

Return Value

Container

at line 933
Container withoutAnnotation(string $name)

Retrieves this container minus the given OCI annotation.

Parameters

string $name

Return Value

Container

at line 943
Container withoutDefaultArgs()

Remove the container's default arguments.

Return Value

Container

at line 952
Container withoutDirectory(string $path, bool|null $expand = false)

Return a new container snapshot, with a directory removed from its filesystem

Parameters

string $path
bool|null $expand

Return Value

Container

at line 965
Container withoutEntrypoint(bool|null $keepDefaultArgs = false)

Reset the container's OCI entrypoint.

Parameters

bool|null $keepDefaultArgs

Return Value

Container

at line 977
Container withoutEnvVariable(string $name)

Retrieves this container minus the given environment variable.

Parameters

string $name

Return Value

Container

at line 987
Container withoutExposedPort(int $port, NetworkProtocol|null $protocol = null)

Unexpose a previously exposed port.

Parameters

int $port
NetworkProtocol|null $protocol

Return Value

Container

at line 1000
Container withoutFile(string $path, bool|null $expand = false)

Retrieves this container with the file at the given path removed.

Parameters

string $path
bool|null $expand

Return Value

Container

at line 1013
Container withoutFiles(array $paths, bool|null $expand = false)

Return a new container spanshot with specified files removed

Parameters

array $paths
bool|null $expand

Return Value

Container

at line 1026
Container withoutLabel(string $name)

Retrieves this container minus the given environment label.

Parameters

string $name

Return Value

Container

at line 1036
Container withoutMount(string $path, bool|null $expand = false)

Retrieves this container after unmounting everything at the given path.

Parameters

string $path
bool|null $expand

Return Value

Container

at line 1049
Container withoutRegistryAuth(string $address)

Retrieves this container without the registry authentication of a given address.

Parameters

string $address

Return Value

Container

at line 1059
Container withoutSecretVariable(string $name)

Retrieves this container minus the given environment variable containing the secret.

Parameters

string $name

Return Value

Container

at line 1069
Container withoutUnixSocket(string $path, bool|null $expand = false)

Retrieves this container with a previously added Unix socket removed.

Parameters

string $path
bool|null $expand

Return Value

Container

at line 1084
Container withoutUser()

Retrieves this container with an unset command user.

Should default to root.

Return Value

Container

at line 1095
Container withoutWorkdir()

Unset the container's working directory.

Should default to "/".

Return Value

Container

at line 1104
string workdir()

Retrieves the working directory for all commands.

Return Value

string