Improvement of Timezone Handling and Caddy Log Formatting

[K2ouMais]

Description:

It has been possible to set container timezones via the TZ environment variable without installing tzdata. To improve visibility and usability, I have explicitly added this ENV variable to all Dockerfiles and updated the documentation.

FrankenPHP & Caddy Logging:

Currently, the FrankenPHP images (using Caddy) output logs in UTC by default, which can complicate debugging. I have adjusted the Caddy configuration to:

1. Respect the timezone set via the TZ variable in log outputs.
2. Introduce a new variable, CADDY_LOG_DATETIME_FORMAT, allowing for custom timestamp formats supported by Caddy.

Backward Compatibility:

These changes are fully backward compatible. Default values are in place, ensuring that if TZ or CADDY_LOG_DATETIME_FORMAT are not set, the behavior remains exactly as it is now.

Examples

docker-compose.yml

services:
  app:
    image: serversideup/php:8.5-frankenphp
    environment:
      TZ: Europe/Berlin
      CADDY_LOG_DATETIME_FORMAT: "wall"
...

Running directly in your terminal:

docker run --rm -it \
  -e TZ=Europe/Berlin \
  -e CADDY_LOG_DATETIME_FORMAT=wall \
  serversideup/php:8.5-frankenphp

[K2ouMais]

Please take a look at the following file:

https://github.com/serversideup/docker-php/blob/main/src/variations/frankenphp/etc/frankenphp/log-level/global/debug.caddyfile#L1C1-L1C6

There is on line one the word "debug". I just let it the way it was and didnt find any reference in the caddy logs for that.
It could be a possible bug?

[jaydrogers]

Whoops, I should have commented here 😃

Thanks for opening a PR! I will review for the next release.

Sorry for the delay. I was working on serversideup/php today but I had another bug take many hours longer than expected 🙃

I'll circle back and take a look at this soon.

[K2ouMais]

@jaydrogers I made a mistake on this one.

I declared TZ to be available on all images, but that is not true 🤦‍♂️

You can use TZ only on debian based images. On alpine images, tzdata would have to be installed.

Let me know, how should I progress on this one.

[K2ouMais]

I reverted recent changes to Dockerfiles that attempted to set the timezone via the TZ environment variable.

Reason for Revert

The TZ environment variable relies on the presence of timezone data, which is not included in Alpine based images. Consequently, this configuration does not work on images built on Alpine.

Impact & New Standard

Alpine Images:

• Alpine-based images will continue to default to the UTC timezone.

• Changing the timezone on these images now explicitly requires installing the tzdata package (the standard Alpine method).

• This typically requires building your own custom image based on the serversideup image and including the tzdata installation step.

• Caddy logs within these Alpine images will still use UTC timestamps.

Debian Images:

• The TZ environment variable remains functional for changing the timezone on Debian-based images (which have been the default for some time). This behavior is now explicitly documented.

New Feature for Log Clarity

To improve log readability, especially for users remaining on UTC, we have introduced a new environment variable:

CADDY_LOG_DATETIME_FORMAT: Allows users to customize the timestamp format of the Caddy access logs, providing better clarity and integration with external logging tools.

[jaydrogers]

How much space gets added to Alpine if we include tzdata by default?

[K2ouMais]

To be honest I didnt try, because you said you didnt want any packages installed, that would possibly make the images bigger, wich is understandable.

[jaydrogers]

No problem. I can take a look if needed. I appreciate your efforts on this 👍

[K2ouMais]

Please also take a look at this file:

https://github.com/serversideup/docker-php/blob/main/src/variations/frankenphp/etc/frankenphp/log-level/global/debug.caddyfile#L1C1-L1C6

On the first line there is the word debug wich isnt in any other files and I couldnt find anything on the caddy documentation about it. It might be a typo.

[jaydrogers]

I finally had some more time to review this. Here's some thoughts:

TZ variable requires tzdata to be installed

I ran this test:

# Build without tzdata
cat <<EOF | docker build -t tz-test-debian-no-tz -
FROM serversideup/php:frankenphp-debian
EOF

cat <<EOF | docker build -t tz-test-alpine-no-tz -
FROM serversideup/php:frankenphp-alpine
EOF

# Build with tzdata
cat <<EOF | docker build -t tz-test-debian-with-tz -
FROM serversideup/php:frankenphp-debian
USER root
RUN apt-get update && apt-get install -y --no-install-recommends tzdata && rm -rf /var/lib/apt/lists/*
EOF

cat <<EOF | docker build -t tz-test-alpine-with-tz -
FROM serversideup/php:frankenphp-alpine
USER root
RUN apk add --no-cache tzdata
EOF

# Compare sizes
docker images | grep tz-test

And it confirmed it had pretty negligible increases:

tz-test-alpine-no-tz:latest      83813a46230c        207MB             0B
tz-test-alpine-with-tz:latest    5731931c6cea        208MB             0B
tz-test-debian-no-tz:latest      45906a09dfe7        621MB             0B
tz-test-debian-with-tz:latest    e0ee4959f24a        621MB             0B

We also have PHP_DATE_TIMEZONE, which should be changed to use TZ

Since TZ is such a common standard, we should come up with a way to have PHP_DATE_TIMEZONE be deprecated and use TZonly. We'll have to think of a clever way to use TZ in the PHP configs, but also accept PHP_DATE_TIMEZONE and show a deprecation warning if they have that variable set.

If we use TZ, I wonder if it will simplify our Caddy configs even more

Since we learned the size is very negligible to install tzdata, I wonder if we set that timezone at the system, all other applications will automatically configure themselves based off the TZ variable as well (could save a lot of config)

Apply to all variations & clearly document

We need to make sure this experience is standardized across all variations too. We'll also want to make sure we are including docs that explain it works for all variations too.

Timing for release

I was hoping to get this in 4.3, but since I think this requires a little more thought -- we'll keep this on the radar for 4.4

[K2ouMais]

Oh I almost forgot this PR I made 😂

It has been a long time...

I’d advise against removing the ability to set the timezone within PHP itself. In many organizations, development teams (who manage PHP settings) and platform/SRE teams (who manage container environments) are separate; they may need to control timezones at different levels.

Having worked in both roles, I’ve seen the need for this flexibility firsthand. Before I transition over to FrankenPHP, I’d really like to see this merged. Beyond the timezone fix, this PR also improves log readability and reduces unnecessary noise.