DEV Community: Yaroslav

Migrating from Caddy + PHP-FPM to FrankenPHP and Laravel Octane

Yaroslav — Tue, 13 Oct 2026 09:10:04 +0000

TL;DR: a production stack moved off Caddy and php-fpm onto FrankenPHP running under Laravel Octane's worker mode, cutting the framework's full per-request boot cost.

Laravel, like most PHP frameworks, carries real bootstrap overhead. Every single request builds the whole framework from a cold start. I ran into this myself in my own project - even small requests, like opening the homepage or the policy page, were taking noticeable time and eating CPU. It's something a user notices while using the app.

I'd heard about FrankenPHP before - a single Go binary with a PHP runtime built into Caddy. I decided to give it a try and rework my app to run on it, just to speed things up.

The stack: Laravel with an Inertia/Vue frontend, Postgres, and a Go binary for PDF generation - all on one small VM (2 vCPU, 2GB RAM), running entirely in Docker via docker compose.

Step 1: Replacing Caddy and php-fpm with FrankenPHP

Previously, this meant two images: caddy and php-fpm. Now both get replaced with a single frankenphp image, which handles TLS and PHP execution all on its own.

Dockerfile, before (two targets, two images):

FROM php:8.4-fpm-alpine AS php-fpm
RUN apk add --no-cache postgresql-libs libzip icu-libs oniguruma \
    && apk add --no-cache --virtual .build-deps $PHPIZE_DEPS postgresql-dev libzip-dev icu-dev oniguruma-dev \
    && docker-php-ext-install -j$(nproc) pdo pdo_pgsql mbstring bcmath zip intl opcache \
    && apk del .build-deps
# ...COPY app code, entrypoint, USER www-data...
CMD ["php-fpm"]

FROM caddy:2-alpine AS caddy
COPY Caddyfile /etc/caddy/Caddyfile
COPY --from=php-fpm /var/www/html/public /var/www/html/public

After (one target):

FROM dunglas/frankenphp:1-php8.4-alpine AS frankenphp
RUN apk add --no-cache postgresql-libs libzip icu-libs oniguruma \
    && apk add --no-cache --virtual .build-deps $PHPIZE_DEPS postgresql-dev libzip-dev icu-dev oniguruma-dev libcap \
    && docker-php-ext-install -j$(nproc) pdo pdo_pgsql mbstring bcmath zip intl opcache \
    && setcap cap_net_bind_service=+ep "$(readlink -f "$(which frankenphp)")" \
    && apk del .build-deps

WORKDIR /var/www/html
COPY --from=composer-deps /app/vendor ./vendor
COPY . .
COPY --from=node-build /app/public/build ./public/build
COPY Caddyfile /etc/frankenphp/Caddyfile
RUN php artisan storage:link && chown -R www-data:www-data /var/www/html /data /config

USER www-data
CMD ["frankenphp", "run", "--config", "/etc/frankenphp/Caddyfile"]

FrankenPHP's image runs as root by default, since binding ports 80/443 usually needs it. To keep the same www-data user the php-fpm image used, I grant the binary one narrow capability (cap_net_bind_service) instead of running the whole process as root.

Caddyfile, before:

{$DOMAIN} {
    root * /var/www/html/public
    encode gzip
    php_fastcgi php-fpm:9000
    file_server
}

After - one php_server directive replaces both php_fastcgi and file_server:

{$DOMAIN} {
    root * /var/www/html/public
    encode zstd gzip
    php_server
}

docker-compose.prod.yml shrank from two services down to one app service.

A production permissions issue

The caddy_data/caddy_config volumes already existed on the server, written by the old Caddy container running as root. The new app container runs as www-data - it couldn't read its own TLS certificate:

"error":"open /data/caddy/certificates/.../app.example.com.key: permission denied"

Cloudflare saw a failed TLS handshake and returned 525 to visitors. The container couldn't start until those permissions were fixed.

The fix: a one-time ownership correction and an explicit restart:

docker compose -f docker-compose.prod.yml --env-file .env.production run --rm --user root app \
    chown -R www-data:www-data /data /config

docker compose -f docker-compose.prod.yml --env-file .env.production restart app

Step 2: adding Laravel Octane worker mode

Classic FrankenPHP still boots the entire Laravel framework from zero on every request. It's a faster web server, since it skips the FastCGI hop to php-fpm, but the request lifecycle stays the same. Worker mode helps with that - it keeps one PHP process alive, working through many requests in a loop, instead of exiting and restarting for each one.

Laravel doesn't support that mode by default, so there's Laravel Octane - a package that lets the framework run as a long-living process, usable with FrankenPHP, Swoole, or RoadRunner.

composer require laravel/octane
php artisan octane:install --server=frankenphp

This generates config/octane.php and public/frankenphp-worker.php - the script FrankenPHP keeps running, handling request after request without rebooting the app in between.

Caddyfile, the final version:

{
    email {$LETSENCRYPT_EMAIL}

    frankenphp {
        worker {
            file /var/www/html/public/frankenphp-worker.php
        }
    }
}

{$DOMAIN} {
    root * /var/www/html/public
    encode zstd br gzip

    php_server {
        index frankenphp-worker.php
        try_files {path} frankenphp-worker.php
        resolve_root_symlink
    }
}

A shared state problem

Since the framework core and the project's code now load only once at startup, that same booted instance gets reused across thousands of requests, so any user state the code keeps won't get cleared between requests.

A short checklist for the code:

No mutable static properties anywhere in the application code.
No data stored in global variables ($GLOBALS).
Nothing calls config([...]) at runtime - the main way config leaks between requests under Octane.

After that, it's worth testing the app under concurrent use from different users, and confirm none of them ever saw another's session, auth state, or data.

Results

After deploy, I ran a PageSpeed Insights test on the live site. It came back with 100/100 performance on desktop, 0.5s LCP, 0ms total blocking time.

In production, the startup log confirms the worker is actually running:

{"logger":"frankenphp","msg":"FrankenPHP started 🐘","total_threads":5,"worker_threads":4,"max_threads":5}

Conclusion

By the end, the project got migrated to a single frankenphp container running in worker mode, one process that stays loaded instead of rebuilding itself on every request.

It made a difference to the site's performance, and feels quite satisfying.

You can see the project here: https://getyourcv.app.

Setting up nginx as a reverse proxy

Yaroslav — Tue, 01 Sep 2026 07:39:54 +0000

If you run more than one service on a server, you need a single entry point in front of them. Instead of setting up a web server and SSL inside every service, it gets handled once, in one place.

We will use jwilder/nginx-proxy. It watches the Docker socket and builds nginx config automatically, based on labels and env vars on your containers. No manual nginx.conf editing every time you add a service.

Prerequisites:

A server with Docker and the Docker Compose plugin installed.
A domain name pointed at the server (needed later for SSL).
Basic comfort with docker compose files.

Base setup: nginx-proxy

The core piece is the nginx-proxy container itself. It exposes ports 80 and 443, and reads the Docker socket to see which containers are running. When a container starts or stops, it updates the routing on its own.

services:
  nginx-proxy:
    image: nginxproxy/nginx-proxy
    container_name: nginx_proxy
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - html:/usr/share/nginx/html
      - certs_volume:/etc/nginx/certs:ro
      - /var/run/docker.sock:/tmp/docker.sock:ro
      - /srv/nginx-vhosts:/etc/nginx/vhost.d:ro
    networks:
      - webproxy

The docker socket mount lets nginx-proxy see new containers as they appear. The vhost.d mount is a folder for custom nginx snippets per domain, we will use this later to lock down some endpoints from public access.

Adding HTTPS with acme-companion

Plain HTTP is not enough for anything public, so we add acme-companion, which pairs with nginx-proxy and handles Let's Encrypt certificates.

  acme-companion:
    image: nginxproxy/acme-companion
    container_name: acme_companion
    environment:
      - DEFAULT_EMAIL=${EMAIL}
    volumes:
      - certs_volume:/etc/nginx/certs:rw
      - acme:/etc/acme.sh
      - /var/run/docker.sock:/var/run/docker.sock:ro
    volumes_from:
      - nginx-proxy
    networks:
      - webproxy
    restart: unless-stopped

It shares the certs volume with nginx-proxy through volumes_from, so both containers see the same certificate files.

Full docker-compose.yml

Let's put both containers, volumes, and networks together:

version: '3.8'

services:
  nginx-proxy:
    image: nginxproxy/nginx-proxy
    container_name: nginx_proxy
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - html:/usr/share/nginx/html
      - certs_volume:/etc/nginx/certs:ro
      - /var/run/docker.sock:/tmp/docker.sock:ro
      - /srv/nginx-vhosts:/etc/nginx/vhost.d:ro
    networks:
      - webproxy

  acme-companion:
    image: nginxproxy/acme-companion
    container_name: acme_companion
    environment:
      - DEFAULT_EMAIL=${EMAIL}
    volumes:
      - certs_volume:/etc/nginx/certs:rw
      - acme:/etc/acme.sh
      - /var/run/docker.sock:/var/run/docker.sock:ro
    volumes_from:
      - nginx-proxy
    networks:
      - webproxy
    restart: unless-stopped

volumes:
  certs_volume:
  acme:
  html:

networks:
  webproxy:
    external: true

The webproxy network is marked external, meaning it is not created by this compose file. We create it once by hand, and every service that wants to sit behind the proxy joins this same network.

Environment variables

.env:

EMAIL=admin@example.com

EMAIL is used by acme-companion as the default contact address for Let's Encrypt. Fill it in with a real address, because Let's Encrypt sends expiry warnings there.

Creating the network

Since the network is external, create it before the first deploy:

docker network create webproxy

Run this once per server. Every stack that needs to be reachable through the proxy connects to this network.

Creating the vhost directory

nginx-proxy mounts /srv/nginx-vhosts as a read only folder for per-domain nginx snippets. Services publish their own config fragments here, e.g. to restrict access to internal routes. Create the folder and give your user ownership:

sudo mkdir -p /srv/nginx-vhosts
sudo chown $USER:$USER /srv/nginx-vhosts

Connecting a service to the proxy

Any container can join the proxy without touching nginx directly. Add a few env vars and put the container on the webproxy network.

version: '3.8'

services:
  myapp:
    build: .
    container_name: myapp
    restart: unless-stopped
    environment:
      - VIRTUAL_HOST=${DOMAIN}
      - VIRTUAL_PORT=8000
      - LETSENCRYPT_HOST=${DOMAIN}
      - LETSENCRYPT_EMAIL=${EMAIL}
    networks:
      - webproxy

networks:
  webproxy:
    external: true

VIRTUAL_HOST tells nginx-proxy which domain routes to this container. VIRTUAL_PORT is the port your app listens on inside the container. LETSENCRYPT_HOST and LETSENCRYPT_EMAIL tell acme-companion to request a certificate for that domain.

.env for the service:

DOMAIN=localhost
EMAIL=admin@example.com

Replace localhost with your real domain before deploying.

Custom nginx config for a service

Sometimes the default routing is not enough. A route needs an IP allow list, custom headers, or something else nginx-proxy does not expose through env vars. For this, place a config snippet into /srv/nginx-vhosts/${DOMAIN}, and nginx-proxy loads it automatically for that domain.

A generic template, filled in by a deploy script using envsubst:

location /internal/ {
    allow 10.0.0.0/8;
    deny all;

    proxy_pass         http://${DOMAIN};
    proxy_set_header   Host              $http_host;
    proxy_set_header   X-Real-IP         $remote_addr;
    proxy_set_header   X-Forwarded-For   $proxy_add_x_forwarded_for;
    proxy_set_header   X-Forwarded-Proto $scheme;
    proxy_set_header   X-Forwarded-Port  $server_port;
    proxy_http_version 1.1;
}

Now, only requests from the allowed range reach the route, everything else gets a 403. For a full example of a deploy script that fills in a template like this, see this article.

Conclusion

We now have one nginx-proxy container in front of everything, and it picks up new services on its own, no manual nginx edits needed. Certificates renew automatically through acme-companion, and any route that needs special rules gets its own config. From here, any service just joins the webproxy network and gets a domain and SSL for free.

Setting up Keycloak as a central identity provider

Yaroslav — Tue, 25 Aug 2026 06:22:50 +0000

This is the first article in a series about Keycloak. We will set up Keycloak as an authentication provider and later connect it to internal services. In the end we get a single entry point and a single user provider for all of them.

In this article we set up Keycloak itself, get the admin console running, and lock it down properly.

Installation

We run Keycloak with Docker, behind an existing nginx reverse proxy. This guide assumes such a proxy (e.g. jwilder/nginx-proxy with an ACME companion for SSL) is already running on the host and shared across services, listening on the webproxy docker network.

Make sure Docker and the Docker Compose plugin are installed on the server first:

docker --version
docker compose version

If these commands fail, install Docker using the official instructions for your OS. Once Docker is ready, create a folder on the server for the project, e.g. /opt/docker.keycloak. We will place the files there step by step: docker-compose.yml, .env, nginx/vhost.conf, and deploy.sh.

Configuration

docker-compose.yml:

version: '3.8'

services:
  keycloak:
    image: quay.io/keycloak/keycloak:26.2
    container_name: keycloak
    environment:
      KC_DB: postgres
      KC_DB_URL: jdbc:postgresql://postgres:5432/keycloak
      KC_DB_USERNAME: ${KC_DB_USERNAME:-keycloak}
      KC_DB_PASSWORD: ${KC_DB_PASSWORD}
      KC_BOOTSTRAP_ADMIN_USERNAME: ${KEYCLOAK_ADMIN:-admin}
      KC_BOOTSTRAP_ADMIN_PASSWORD: ${KEYCLOAK_ADMIN_PASSWORD}
      KC_HOSTNAME: ${DOMAIN}
      KC_HTTP_ENABLED: "true"
      KC_PROXY_HEADERS: xforwarded
      KC_HOSTNAME_STRICT: "false"
      KC_HEALTH_ENABLED: "true"
      JAVA_OPTS_APPEND: ${KC_JAVA_OPTS:--Xms512m -Xmx512m}
      VIRTUAL_HOST: ${DOMAIN}
      VIRTUAL_PORT: 8080
      LETSENCRYPT_HOST: ${DOMAIN}
      LETSENCRYPT_EMAIL: ${EMAIL}
    depends_on:
      postgres:
        condition: service_healthy
    networks:
      - keycloak
      - webproxy
    healthcheck:
      test: [ "CMD-SHELL", "exec 3<>/dev/tcp/127.0.0.1/9000 && printf 'GET /health/ready HTTP/1.1\r\nHost: localhost\r\nConnection: close\r\n\r\n' >&3 && cat <&3 | grep -q '\"status\": \"UP\"'" ]
      interval: 30s
      timeout: 10s
      retries: 5
      start_period: 90s
    deploy:
      resources:
        limits:
          memory: 1g
    restart: unless-stopped

  postgres:
    image: postgres:17
    container_name: keycloak_postgres
    environment:
      POSTGRES_DB: keycloak
      POSTGRES_USER: ${KC_DB_USERNAME:-keycloak}
      POSTGRES_PASSWORD: ${KC_DB_PASSWORD}
    volumes:
      - keycloak_data:/var/lib/postgresql/data
    networks:
      - keycloak
    healthcheck:
      test: [ "CMD-SHELL", "pg_isready -U $$POSTGRES_USER -d $$POSTGRES_DB" ]
      interval: 10s
      timeout: 5s
      retries: 5
    deploy:
      resources:
        limits:
          memory: 512m
    restart: unless-stopped

networks:
  keycloak:
    driver: bridge
  webproxy:
    external: true

volumes:
  keycloak_data:

The setup has two containers: Keycloak and Postgres. Keycloak stores realm and user data in Postgres, so the database needs to be healthy before Keycloak starts. The webproxy network connects Keycloak to an external nginx reverse proxy.

Environment variables

.env:

DOMAIN=localhost
EMAIL=admin@example.com

KEYCLOAK_ADMIN=admin
KEYCLOAK_ADMIN_PASSWORD=

KC_DB_USERNAME=keycloak
KC_DB_PASSWORD=

DOMAIN: the domain for Keycloak (e.g. auth.example.com)
EMAIL: email for the Let's Encrypt SSL certificate
KEYCLOAK_ADMIN: Keycloak admin username
KEYCLOAK_ADMIN_PASSWORD: admin password
KC_DB_USERNAME: Postgres username (default keycloak)
KC_DB_PASSWORD: Postgres password

Fill in DOMAIN, EMAIL, and both passwords before the first run.

Restricting admin access

The admin console and the master realm give full control over Keycloak. If this is open to the web, it becomes a direct target for brute force and credential stuffing. The safe option is to close it from the outside and allow access only from 127.0.0.1, then reach it through an SSH tunnel when needed.

nginx/vhost.conf:

# Keycloak admin access restriction.
# Template: ${DOMAIN} is substituted by deploy.sh via envsubst.
#
# Admin interface is accessible only via SSH tunnel from localhost.

location /auth/admin/ {
    allow 127.0.0.1;
    deny all;

    proxy_pass         http://${DOMAIN};
    proxy_set_header   Host              $http_host;
    proxy_set_header   X-Real-IP         $remote_addr;
    proxy_set_header   X-Forwarded-For   $proxy_add_x_forwarded_for;
    proxy_set_header   X-Forwarded-Proto $scheme;
    proxy_set_header   X-Forwarded-Port  $server_port;
    proxy_set_header   Proxy             "";
    proxy_http_version 1.1;
}

location /auth/realms/master/ {
    allow 127.0.0.1;
    deny all;

    proxy_pass         http://${DOMAIN};
    proxy_set_header   Host              $http_host;
    proxy_set_header   X-Real-IP         $remote_addr;
    proxy_set_header   X-Forwarded-For   $proxy_add_x_forwarded_for;
    proxy_set_header   X-Forwarded-Proto $scheme;
    proxy_set_header   X-Forwarded-Port  $server_port;
    proxy_set_header   Proxy             "";
    proxy_http_version 1.1;
}

This config blocks the admin console and the master realm from the public internet. Only requests from 127.0.0.1 get through. This means the admin panel is reachable only through an SSH tunnel, which we set up below.

Deployment

With the config files ready, one script publishes the nginx vhost and starts Keycloak.

deploy.sh:

#!/bin/bash
set -euo pipefail

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
VHOSTS_DIR="/srv/nginx-vhosts"

# Load .env
set -a
source "${SCRIPT_DIR}/.env"
set +a

if [[ -z "${DOMAIN:-}" ]]; then
    echo "Error: DOMAIN is not set in .env" >&2
    exit 1
fi

# Publish nginx vhost config
echo "Publishing nginx config for ${DOMAIN}..."
mkdir -p "${VHOSTS_DIR}"
envsubst '${DOMAIN}' < "${SCRIPT_DIR}/nginx/vhost.conf" > "${VHOSTS_DIR}/${DOMAIN}"

# Reload nginx
if docker inspect nginx_proxy &>/dev/null; then
    docker exec nginx_proxy nginx -s reload
    echo "nginx reloaded."
else
    echo "Warning: nginx_proxy container not found, skipping reload."
fi

# Start Keycloak
echo "Starting Keycloak..."
docker compose -f "${SCRIPT_DIR}/docker-compose.yml" up -d

Run it with:

./deploy.sh

The script does three things:

Fills DOMAIN from .env into nginx/vhost.conf and writes the result to /srv/nginx-vhosts/${DOMAIN}.
Reloads nginx_proxy.
Starts Keycloak with docker compose up -d.

Admin console access

/auth/admin/ and /auth/realms/master/ are closed to the outside world. Only 127.0.0.1 can reach them.

Open an SSH tunnel from your local machine:

ssh -L 8443:127.0.0.1:443 user@server -N

Add this line to /etc/hosts:

127.0.0.1 auth.example.com

Open in the browser:

https://auth.example.com:8443/auth/admin/

Log in with the credentials from KEYCLOAK_ADMIN and KEYCLOAK_ADMIN_PASSWORD. Close the tunnel with Ctrl+C when done.

Testing

After Keycloak starts, open the admin console through the SSH tunnel. You will see the Keycloak login screen.

After logging in, you start in the master realm. Do not use it for your applications and users: master controls Keycloak itself, including the admin account, and a leaked token from your applications should never reach it.

Create a separate realm for your organization instead. Click Create realm, give it a name (e.g. your company name), and save.

From this point, the realm is ready for clients, users, and roles. Everything you connect to Keycloak goes into this realm, not into master.

Conclusion

We now have a working Keycloak instance with a Postgres database and a locked down admin console. It can create realms, manage users, and issue tokens, which is everything a service needs to delegate its login screen to Keycloak.