NAME
Langertha::Holmgang::Sim::Linux::Docker - Docker Engine with Compose v2 on a simulated Linux server — projects, containers, derived state
VERSION
version 0.001
SYNOPSIS
# from the Linux simulator: docker on a device with docker state
my ( $out, $ok ) = Langertha::Holmgang::Sim::Linux::Docker::docker( $dev, \@argv, $ctx, $stdin );
DESCRIPTION
Docker Engine 26 with the Compose plugin v2 as state of a Linux device (cai-platform docs/entwurf-evals.md §3.3). The Compose files are ordinary files of the device (files); what runs is under docker:
docker:
projects:
shop: { dir: /srv/shop } # compose.yaml|compose.yml|docker-compose.y(a)ml and .env there
# running_files: { /srv/shop/compose.yaml: "…" } # what the running state was started with
# stopped: true # project is not running
images: # images present locally and their behaviour (simulation only)
"postgres:16.4":
listens: [5432]
user: "999" # uid of the process (write access to bind mounts)
data_path: /var/lib/postgresql/data # where data lives (data of the mount there)
warmup: true # accepts connections only after starting up
tools: [pg_isready, sh] # for healthchecks and exec
needs: # start conditions; the first one violated exits with 1
- env: POSTGRES_PASSWORD
log: [ "Error: Database is uninitialized and superuser password is not specified." ]
- connect: "${DB_HOST}:${DB_PORT:-5432}" # service name on the same network, running, listening
log: [ "…" ]
- equals: [ "${DB_PASSWORD}", "${peer:POSTGRES_PASSWORD}" ] # peer = target of the last connect
log: [ "…" ]
- writable: /data # mount there writable for user
- mount: /etc/app/app.yml # file present through a bind mount
logs: [ "…" ] # when it runs
http: { routes: [ … ] } # like Sim::Http (application on the first listens port)
registry: { "registry.example.com/shop/api:2.5.0": { … } } # pullable (behaviour like images)
host_ports: { "0.0.0.0:80": apache2 } # taken by the host
volumes: { shop_pgdata: { data: kunden-2026 } } # named volumes, content
# by the simulator (derived from the files on the first command, then carried on):
containers:
shop-db-1: { project, service, image, status: running|exited|restarting|created,
exit_code, health: healthy|unhealthy|starting, seq, restarts,
config (effective service configuration), data, error }
Bind mounts with content describe directories of the device (dirs: { /srv/shop/pgdata: { data: …, owner, group, mode } }). Docker creates a missing directory as root on start (as for real).
Effective configuration: interpolation like Compose (${VAR}, $VAR, ${VAR:-d}, ${VAR-d}, ${VAR:?e}, $$) from the project's .env (quotes like dotenv: single literal, double with substitution), env_file (values literal into the container's environment), environment (list or map), ports (short and long), volumes (short and long, project volumes with prefix), networks, depends_on (list or map with condition), healthcheck, restart, user, profiles, container_name. Errors like Compose: YAML errors with line, unknown keys (additional properties … not allowed), unknown services, networks, volumes.
up: order by depends_on; each service recreated when its effective configuration or the image has changed (otherwise "Running"); a missing image is pulled from registry (otherwise manifest unknown); port conflicts with the host or other containers; service_healthy waits for a healthy healthcheck; a service that does not meet its conditions on start ends (exited), or with a restart policy restarting; when it reaches a service with warmup that was started in the same round, without waiting for its health, its first start fails (with a restart policy it runs afterwards). restart restarts containers without taking over changes to the file; down -v deletes the project's volumes with their content.
Commands: docker compose (-f, -p, --project-directory, --env-file, --profile) up -d [--force-recreate] [--no-deps] [--remove-orphans] [service…], down [-v] [--remove-orphans], ps [-a] [--services], logs [--tail N] [service…], config [-q] [--services] [--volumes], restart|stop|start [service…], pull [service…], exec [-T] service command, images, ls, version; docker ps [-a], logs, inspect [--format], restart|stop|start, exec, volume ls|inspect, network ls, images, pull, version. In exec: env, printenv, cat (mounted files), id, curl/wget to other services, pg_isready. up without -d, docker run, build and anything interactive are gaps of the simulation.
ensure
ensure( $dev, $host, $state );
On the first command, derives the running containers from the files (or from running_files), as if every project had been started with up -d.
parse_env
my $vars = parse_env( $text, \%before, \@missing );
An .env like Compose (dotenv): KEY=VAL, export, single quotes literal, double and unquoted with substitution.
interpolate
my $r = interpolate( '${DB_HOST:-db}:5432', \%vars ); # { value, missing, error }
Substitution like Compose: ${VAR}, $VAR, ${VAR:-d}, ${VAR-d}, ${VAR:?e}, ${VAR:+x}, $$; ${peer:X} for the environment of the container reached last (only in conditions of the images).
model
my $m = model( $dev, dir => '/srv/shop', files => [ … ], project => 'shop', env_file => …, profiles => [ … ] );
The effective configuration of a project: name, dir, file, services (normalised per service), networks, volumes, warnings, error (text like Compose).
up
my ( $lines, $ok, $err ) = up( $dev, $model, \%opt, $state, $host );
docker compose up -d: services (list, otherwise all without a profile), force_recreate (only the chosen services), recreate_deps (their dependencies too), no_deps, remove_orphans.
lookup
my ( $name, $c ) = lookup( $docker, $from, 'db' );
The container behind a name as seen from a container: service name in the same project, container name or hostname, only over a shared network.
exec_line
my ( $out, $ok ) = exec_line( $dev, $docker, $container, $c, 'wget -qO- http://api:8080/health' );
A command line in the container (healthchecks, docker exec): chains with ||, &&, ;; curl, wget, pg_isready, env, printenv, cat, id, true/false/exit N. A program the image does not have (tools) is missing as for real.
container_request
my $res = container_request( $dev, $docker, $name, $c, $url );
HTTP from a container to a service (or itself), response like "respond" in Langertha::Holmgang::Sim::Linux::Http; undef when nobody listens there.
serve
Response of a container that publishes the port on the device, or undef (contract of "request" in Langertha::Holmgang::Sim::Linux::Http).
ss_lines
Lines for ss -tlnp: the published ports of running containers (docker-proxy).
docker
docker … on the device (see DESCRIPTION).
gofmt
my $text = gofmt( 'table {{.Names}}\t{{.Status}}', \@rows );
Go templates like docker's --format: {{.Field}}, {{.A.B}}, {{json .X}}, {{json .}}, prefix table (header line from the field names), \t. Unknown fields: <no value>.
SUPPORT
Issues
Please report bugs and feature requests at https://github.com/Getty/langertha-holmgang/issues.
IRC
Join #langertha on irc.perl.org or message Getty directly.
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) 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.