TYPO3 v14

Configuration files

docker-compose.override.yml: local adjustments

Why the Keycloak host name is redirected inside the container and how override files work.

Why an override file?

If a docker-compose.override.yml sits next to docker-compose.yml, Compose loads it automatically and merges it on top. This applies as long as no file is given with -f. The main file thus stays the same for every installation, and the specifics of one machine live separately next to it.

The merge rules:

  • The override file replaces single values such as image or restart.
  • Mappings such as environment are merged key by key.
  • Lists such as ports or extra_hosts are extended, not replaced.

docker compose config shows the result.

Content 

services:
  php:
    extra_hosts:
      - "id.dev.sonia.de:host-gateway"

  scheduler:
    extra_hosts:
      - "id.dev.sonia.de:host-gateway"

extra_hosts adds entries to the container’s /etc/hosts file. The special value host-gateway stands for the IP address of the Docker host, that is your own machine. Inside the container, id.dev.sonia.de therefore resolves to the machine on which the Keycloak proxy listens on port 443.

Only php and scheduler are affected, because PHP code only runs there. nginx never talks to Keycloak itself.

Why this is necessary

Locally, the machine’s /etc/hosts points id.dev.sonia.de to 127.0.0.1. That is correct for the browser: it runs on the machine and reaches the Keycloak proxy there.

TYPO3, however, must also reach Keycloak itself. After login, it exchanges the code for tokens, fetches the userinfo and, for the back-channel logout, loads the signing keys. Inside a container, 127.0.0.1 means the container itself, and no Keycloak runs there. Without the override file, the login fails with a connection error.

The opposite direction needs no entry: Keycloak reaches TYPO3 for the back-channel logout via host.docker.internal:8088, which Docker Desktop provides itself.

On a server 

# Variante 1: Datei weglassen bzw. löschen
rm docker-compose.override.yml

# Variante 2: nur die Hauptdatei verwenden
docker compose -f docker-compose.yml up -d

# Variante 3: dauerhaft in der .env festlegen
COMPOSE_FILE=docker-compose.yml

On a server with real DNS, id.dev.sonia.de resolves correctly anyway. The entry would be wrong there, because it redirects requests to the server itself. That is why the override file is not used there.

Conversely, it is the right place for further local adjustments, for example a different context for detailed error messages:

services:
  php:
    environment:
      TYPO3_CONTEXT: Development