/ 
API-Docker-0.004
/ API::Docker::Role::Entity::Container

NAME

API::Docker::Role::Entity::Container - Container operations, on the generated container types

VERSION

version 0.004

SYNOPSIS

my $docker = API::Docker->new;

# from list: an API::Docker::Type::ContainerSummary
my ($container) = @{ $docker->containers->list };

say $container->id;
say $container->status;             # "Up 2 hours"
say $container->state;              # "running"

$container->start;
$container->stop(timeout => 10);
my $logs = $container->logs(tail => 100);
$container->remove(force => 1);

# from inspect: an API::Docker::Type::ContainerInspectResponse, where
# the same methods work and `state` is an object
my $full = $docker->containers->inspect($container->id);
say $full->state->status;
say $full->state->exit_code;

if ($full->is_running) { ... }

DESCRIPTION

The convenience methods of a container. This role is composed, at load time, into the two generated classes the daemon answers container requests with:

Every method here forwards to API::Docker::API::Containers with the container's own id and returns whatever that method returns; the options are that method's options, undocumented here on purpose so there is one place to correct when the engine's are found to be something else.

The fields differ between the two classes -- see "The two container shapes" in API::Docker::API::Containers for the differences that have bitten. "is_running" is the one method that reads both shapes.

Why the methods are a role applied to generated classes rather than a class of their own: "DESCRIPTION" in API::Docker::Role::Entity.

start

$container->start;

say 'was already running' unless $container->start;

Start the container. Returns 1 when it was started and 0 when it was already running. Delegates to "start" in API::Docker::API::Containers, which documents what that 0 replaces.

stop

$container->stop(timeout => 10);

Stop the container. Returns 1 when it was stopped and 0 when it was already stopped. Delegates to "stop" in API::Docker::API::Containers.

restart

$container->restart;

Restart the container. Returns 1/0 as "restart" in API::Docker::API::Containers does; no engine measured here answers a restart with 304, so it is 1.

kill

$container->kill(signal => 'SIGTERM');

Send a signal to the container.

remove

$container->remove(force => 1);

Remove the container.

logs

my $logs = $container->logs(tail => 100);

# or follow it, one frame at a time
$container->logs(follow => 1, tail => 0,
    on_frame => sub { print $_[0]{data} });

Get container logs. Every option goes to "logs" in API::Docker::API::Containers, follow and on_frame included; with a callback the return value is that method's summary HashRef rather than the frames.

attach

my $frames = $container->attach;

Attach to the container's output and return the frames, one-way. Every option goes to "attach" in API::Docker::API::Containers, on_frame included; with a callback the return value is that method's summary HashRef rather than the frames. Without options it replays what the container already wrote and returns; stream => 1 on a container that is not running never returns -- not even with a callback -- see "The defaults follow the engine" in API::Docker::API::Containers.

The container must be running. Attaching to one that has already exited destroys its exit status on Podman, so the call checks first and croaks rather than attaching; "logs" is how a finished container's output is read. require_running => 0 attaches anyway. The check is a pre-flight one and does not close the race against a container stopping underneath it -- see "This method refuses a container that is not running" in API::Docker::API::Containers.

inspect

my $updated = $container->inspect;

Get fresh container information. Returns an API::Docker::Type::ContainerInspectResponse whatever the invocant was, so this is also how a list entry is turned into the full shape.

pause

$container->pause;

Pause all processes in the container. Returns 1/0 as "pause" in API::Docker::API::Containers does; an already-paused container is an error there, not a 0.

unpause

$container->unpause;

Unpause the container. Returns 1/0 as "unpause" in API::Docker::API::Containers does.

top

my $processes = $container->top;

List running processes in the container.

stats

my $stats = $container->stats;

# or follow the readings
$container->stats(stream => 1, on_event => sub { ... });

Get resource usage statistics. Every option goes to "stats" in API::Docker::API::Containers, stream and on_event included; with a callback the return value is that method's summary HashRef rather than the readings.

changes

for my $change (@{ $container->changes }) { ... }

Paths that differ from the image, as { Path => ..., Kind => ... }. Delegates to "changes" in API::Docker::API::Containers, which documents what the three Kind numbers mean.

export

my $tar = $container->export;

The container's filesystem as raw tar bytes.

resize

$container->resize(h => 40, w => 120);

Resize the container's TTY.

get_archive

my $tar = $container->get_archive(path => '/etc/hostname');

Read a path out of the container as raw tar bytes.

put_archive

$container->put_archive($tar, path => '/opt/app');

Unpack a tar archive into a directory in the container.

stat_archive

my $stat = $container->stat_archive(path => '/etc/hostname');

Stat a path in the container without transferring it.

is_running

if ($container->is_running) { ... }

True when the container is running. Reads whichever shape it is on: the status string $summary->state from list, and $inspected->state->running from inspect.

SEE ALSO

SUPPORT

Issues

Please report bugs and feature requests on GitHub at https://github.com/Getty/p5-api-docker/issues.

CONTRIBUTING

Contributions are welcome! Please fork the repository and submit a pull request.

AUTHOR

Torsten Raudssus <getty@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2026 by Torsten Raudssus <torsten@raudssus.de> https://raudssus.de/.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.