view release on metacpan or  search on metacpan

lib/API/Docker/Role/Entity/Container.pm  view on Meta::CPAN

does; no engine measured here answers a restart with 304, so it is 1.

=head2 kill

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

Send a signal to the container.

=head2 remove

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

Remove the container.

=head2 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
L<API::Docker::API::Containers/logs>, C<follow> and C<on_frame> included; with
a callback the return value is that method's summary HashRef rather than the
frames.

=head2 attach

    my $frames = $container->attach;

Attach to the container's output and return the frames, one-way. Every option
goes to L<API::Docker::API::Containers/attach>, C<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; C<< stream => 1 >> on a container that is not running never
returns -- not even with a callback -- see
L<API::Docker::API::Containers/"The defaults follow the engine">.

B<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; L</logs> is how a finished container's output is read.
C<< 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
L<API::Docker::API::Containers/"This method refuses a container that is not running">.

=head2 inspect

    my $updated = $container->inspect;

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

=head2 pause

    $container->pause;

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

=head2 unpause

    $container->unpause;

Unpause the container. Returns 1/0 as
L<API::Docker::API::Containers/unpause> does.

=head2 top

    my $processes = $container->top;

List running processes in the container.

=head2 stats

    my $stats = $container->stats;

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

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

=head2 changes

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

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

=head2 export

    my $tar = $container->export;

The container's filesystem as raw tar bytes.

=head2 resize

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

Resize the container's TTY.

=head2 get_archive

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

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

=head2 put_archive

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

Unpack a tar archive into a directory in the container.

=head2 stat_archive

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

Stat a path in the container without transferring it.

=head2 is_running

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

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

=head1 SEE ALSO

=over

=item * L<API::Docker::API::Containers> - the operations these forward to

=item * L<API::Docker::Type::ContainerSummary> - the fields C<list> returns

=item * L<API::Docker::Type::ContainerInspectResponse> - the fields
C<inspect> returns

=item * L<API::Docker::Role::Entity> - why the methods live in a role

=back

=head1 SUPPORT

=head2 Issues

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

=head1 CONTRIBUTING

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

=head1 AUTHOR

Torsten Raudssus <getty@cpan.org>

=head1 COPYRIGHT AND LICENSE

This software is copyright (c) 2026 by Torsten Raudssus <torsten@raudssus.de> L<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.

=cut