diff --git a/perl/content.md b/perl/content.md index 35b1c95fe4e49..20bd730d3d068 100644 --- a/perl/content.md +++ b/perl/content.md @@ -32,6 +32,32 @@ For many simple, single file projects, you may find it inconvenient to write a c $ docker run -it --rm --name my-running-script -v "$PWD":/usr/src/myapp -w /usr/src/myapp %%IMAGE%%:5.20 perl your-daemon-or-script.pl ``` +## Signal handling behavior notice + +As Perl will run as PID 1 by default in containers (unless an [ENTRYPOINT](https://docs.docker.com/engine/reference/builder/#entrypoint) is set,) special care needs to be considered when expecting to send signals (particularly SIGINT or SIGTERM) to it. For example, running + +```console +$ docker run -it --name kill-me-plz --rm %%IMAGE%%:5.20 perl -E 'sleep 300' +``` + +and doing on another terminal, + +```console +$ docker exec kill-me-plz kill 1 +``` + +will *not* stop the perl running on the `kill-me-plz` container (it will keep running until the `sleep 300` finishes.) To do so, one must set a signal handler like this: + +```console +$ docker run -it --name kill-me-now --rm %%IMAGE%%:5.20 perl -E '$SIG{TERM} = sub { say "recv TERM" }; sleep 300' +``` + +so doing `docker exec kill-me-now kill 1` (or the simpler `docker stop kill-me-now`) will immediately stop the container, and print `recv TERM` in the other terminal. + +If your Perl program is expected to handle signals and fork child processes, it is encouraged to use an init-like program for ENTRYPOINT, such as [dumb-init](https://github.com/Yelp/dumb-init) or [tini](https://github.com/krallin/tini) (the latter is available since Docker 1.13 via the `docker run --init` flag.) + +See also [Signals in perlipc](https://perldoc.pl/perlipc#Signals) as well as [Perl/docker-perl#44](https://github.com/Perl/docker-perl/issues/44). + ## Example: Creating a reusable Carton image for Perl projects Suppose you have a project that uses [Carton](https://metacpan.org/pod/Carton) to manage Perl dependencies. You can create a `%%IMAGE%%:carton` image that makes use of the [ONBUILD](https://docs.docker.com/engine/reference/builder/#onbuild) instruction in its `Dockerfile`, like this: