/ 
WWW-Docker-0.001
River stage zero No dependents
/ WWW::Docker::API::Containers

NAME

WWW::Docker::API::Containers - Docker Engine Containers API

VERSION

version 0.001

SYNOPSIS

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

# List containers
my $containers = $docker->containers->list(all => 1);
for my $container (@$containers) {
    say $container->Id;
    say $container->Status;
}

# Create and start a container
my $result = $docker->containers->create(
    Image => 'nginx:latest',
    name  => 'my-nginx',
    ExposedPorts => { '80/tcp' => {} },
);
$docker->containers->start($result->{Id});

# Inspect container details
my $container = $docker->containers->inspect($result->{Id});
say $container->Name;

# Stop and remove
$docker->containers->stop($result->{Id}, timeout => 10);
$docker->containers->remove($result->{Id});

# View logs
my $logs = $docker->containers->logs($result->{Id}, tail => 100);

DESCRIPTION

This module provides methods for managing Docker containers including creation, lifecycle operations (start, stop, restart), inspection, logs, and more.

All list and inspect methods return WWW::Docker::Container objects for convenient access to container properties and operations.

Accessed via $docker->containers.

client

Reference to WWW::Docker client. Weak reference to avoid circular dependencies.

list

my $containers = $containers->list(%opts);

List containers. Returns ArrayRef of WWW::Docker::Container objects.

Options:

  • all - Show all containers (default shows just running)

  • limit - Limit results to N most recently created containers

  • size - Include size information

  • filters - Hashref of filters

create

my $result = $containers->create(
    Image => 'nginx:latest',
    name  => 'my-nginx',
    Cmd   => ['/bin/sh'],
    Env   => ['FOO=bar'],
);

Create a new container. Returns hashref with Id and Warnings.

The name parameter is extracted and passed as query parameter. All other parameters are Docker container configuration (see Docker API documentation).

Common config keys: Image, Cmd, Env, ExposedPorts, HostConfig.

inspect

my $container = $containers->inspect($id);

Get detailed information about a container. Returns WWW::Docker::Container object.

start

$containers->start($id);

Start a container.

stop

$containers->stop($id, timeout => 10);

Stop a container.

Options:

  • timeout - Seconds to wait before killing (default 10)

  • signal - Signal to send (default SIGTERM)

restart

$containers->restart($id, timeout => 10);

Restart a container. Optionally specify timeout in seconds.

kill

$containers->kill($id, signal => 'SIGKILL');

Send a signal to a container. Default signal is SIGKILL.

remove

$containers->remove($id, force => 1, volumes => 1);

Remove a container.

Options:

  • force - Force removal (kill if running)

  • volumes - Remove associated volumes

  • link - Remove specified link

logs

my $logs = $containers->logs($id, tail => 100, timestamps => 1);

Get container logs.

Options:

  • stdout - Include stdout (default 1)

  • stderr - Include stderr (default 1)

  • since - Show logs since timestamp

  • until - Show logs before timestamp

  • timestamps - Include timestamps

  • tail - Number of lines from end (e.g., 100 or all)

top

my $processes = $containers->top($id, ps_args => 'aux');

List running processes in a container. Returns hashref with Titles and Processes arrays.

stats

my $stats = $containers->stats($id);

Get container resource usage statistics (CPU, memory, network, I/O). Returns one-shot statistics.

wait

my $result = $containers->wait($id, condition => 'not-running');

Block until container stops, then return exit code. Optional condition parameter.

pause

$containers->pause($id);

Pause all processes in a container.

unpause

$containers->unpause($id);

Unpause all processes in a container.

rename

$containers->rename($id, 'new-name');

Rename a container.

update

$containers->update($id, Memory => 314572800);

Update container resource limits and configuration.

prune

my $result = $containers->prune(filters => { until => ['24h'] });

Delete stopped containers. Returns hashref with ContainersDeleted and SpaceReclaimed.

SEE ALSO

SUPPORT

Issues

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

CONTRIBUTING

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

AUTHOR

Torsten Raudssus <torsten@raudssus.de>

COPYRIGHT AND LICENSE

This software is copyright (c) 2025 by Torsten Raudssus.

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