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.