Services

What the image needs

php is in the image already; most programs are not. A service says what has to be installed for it in its image() method, and the call service docker command writes that into the Dockerfile.

Description ServiceImageCommand call service docker

What it is and why

What it is. ServiceImage — the list of what a service needs in the image: packages, folders.

The problem. The program has to be installed in the image. Writing apk add into the Dockerfile by hand, the service and the Dockerfile drift apart easily: a service removed — its package stays; a new one added — forgotten.

The solution. The service says what it needs itself. The command writes the Dockerfile part.

Example: Memcached

Memcached is a simple in-memory cache. It is not in the image; the memcached package installs it:

main/Services/Memcached.php
namespace Main\Services;

use Flytachi\Winter\Kernel\App\Component;
use Flytachi\Winter\Kernel\App\Priority;
use Flytachi\Winter\Kernel\App\Service;
use Flytachi\Winter\Kernel\App\ServiceImage;

final class Memcached implements Service
{
  public function component(): Component
  {
      return Component::command(['memcached', '-l', '127.0.0.1', '-p', '11211'], 'memcached',
          priority: Priority::High,
          ready: 'tcp://127.0.0.1:11211',
          alive: 'tcp://127.0.0.1:11211',
          retries: 3);
  }

  public function image(): ServiceImage
  {
      return new ServiceImage(packages: ['memcached']);
  }
}

All that differs from your own service is one line in image().

Writing it into the image

bash
php call service docker
docker compose up -d --build

The Dockerfile gets a block:

Dockerfile
# winter:services — written by `call service docker`; change the services, not this block
USER root
RUN apk add --no-cache memcached
USER winter
# winter:services end
  • The command changes only this block; the rest of the Dockerfile is left alone.
  • A service added, removed or changed — run it again.
  • To see what would be written, changing nothing: php call service docker --dry.

When the program keeps data

A cache has nothing to keep. A database needs a folder that outlives a rebuild of the container — two more parameters describe it:

php
new ServiceImage(
  packages: ['redis'],
  directories: ['/var/lib/redis' => 0755],         // created and given to winter
  volumes: ['redis-data' => '/var/lib/redis'],     // worth keeping in a volume
);

The command creates the folder in the Dockerfile. The volume it does not write — it shows it: compose is yours, and only you know whether the data must be kept, and where.

text
[i] Compose is yours: add to docker-compose.yml, service "server", what fits:
[ docker-compose.yml ]
services:
  server:
    stop_grace_period: 70s
    volumes:
      - redis-data:/var/lib/redis
volumes:
  redis-data:
[ docker-compose.yml ]

There too is stop_grace_period: how long the container waits for a stop. Add it always; the volume, as you need.

ServiceImage

Parameter Example What it means
packages ['memcached'] apk packages (the image is Alpine)
directories ['/var/lib/redis' => 0755] folders: created, owned by the winter user
volumes ['redis-data' => '/var/lib/redis'] where the data lives: volume name → path. For the compose hint
env ['TZ' => 'UTC'] the image’s environment variables
run ['…'] RUN commands of your own, when the rest is not enough. Rarely needed

With several services, their packages and folders merge into one block, each once. Two asking for the same thing differently (one folder with different modes) — the command says it is an error. Every option of the command is on the call service page.

Next

  • PostgreSQL — a ready-made service with data, a volume and checks.