puppet-frankenphp/README.md

# Puppet FrankenPHP Module

## Overview

This Puppet module installs and manages **FrankenPHP** on Debian-based systems (Debian, Ubuntu) using the official `.deb` package.

It is designed for a **secure, multi-tenant architecture** by managing two distinct components:
1.  **FrankenPHP (Proxy)**: A main Caddy/FrankenPHP service, installed via `.deb` and managed by `systemd`, which acts as a reverse proxy.
2.  **Isolated Applications**: Individual PHP applications, each running in its own `frankenphp` process under a dedicated system user. These processes are managed by **Supervisor** for process and user isolation.

## Prerequisites

This module has external dependencies (see `metadata.json`):
* `puppetlabs/concat`: Used to assemble the main `Caddyfile` from fragments.
* `puppetlabs/stdlib`: For data types (`Stdlib::Absolutepath`).
* `ajcrowe/supervisord`: Used to manage the isolated application processes.

You **must** ensure that Supervisor is installed on the target node. This module only manages *configurations* for Supervisor, not its installation.

```puppet
# In your base profile or site.pp
include 'supervisor'
````

## Usage

The architecture is deployed in two steps for each website:

1.  Declare the isolated application (`frankenphp::app`).
2.  Declare the public-facing vhost that points to it (`frankenphp::vhost`).

### 1\. Base Installation

Simply include the main class. This installs the FrankenPHP binary and configures the proxy service (which is empty by default).

```puppet
include 'frankenphp'
```

### 2\. Defining an Isolated Application (`frankenphp::app`)

This defined type creates a dedicated user, a root directory, a specific Caddyfile for the app, and a Supervisor service to run it on a local port.

```puppet
# Declare a 'blog-app' application
frankenphp::app { 'blog-app':
  ensure      => present,
  root_dir    => '/var/www/blog',
  user        => 'bloguser',
  listen_port => '9010', # Ensure this port is free
}
```

This code will:

  * Create the `bloguser` user.
  * Create the `/var/www/blog` directory (owned by `bloguser`).
  * Create a Caddyfile for this app (listening on `localhost:9010`).
  * Create the `/etc/supervisor/conf.d/frankenphp-blog-app.conf` file to launch this process as the `bloguser`.

### 3\. Exposing the Application (`frankenphp::vhost`)

This adds an entry to the main proxy `Caddyfile` to route public traffic to the isolated application.

```puppet
# Create the public vhost for blog.example.com
frankenphp::vhost { 'blog.example.com':
  ensure       => present,
  mode         => 'proxy',
  proxy_target => 'localhost:9010', # Must match the app's listen_port
  extra_config => @(EOT)
    # Caddy will handle HTTPS automatically.
    # We add the Host header for the proxy.
    header_up Host {host}
  EOT
  ,
  # Ensure the proxy isn't defined until the app is managed
  require      => Frankenphp::App['blog-app'],
}
```

## Classes and Defines

### Class: `frankenphp`

The main class that orchestrates installation (`frankenphp::install`), proxy configuration (`frankenphp::config`), and the main service (`frankenphp::service`).

**Parameters:**

  * `version` (String): The FrankenPHP version to download (e.g., '1.9.1').
  * `service_ensure` (String): The state of the main service (default: 'running').
  * `service_enable` (Boolean): Enable the main service on boot (default: true).

### Define: `frankenphp::app`

Manages a single isolated PHP application.

**Parameters:**

  * `root_dir` (String): The application's document root under `/var/www/${user}/`
  * `user` (String): The username to create for this application.
  * `listen_port` (String): The local port the application will listen on (e.g., '9010').
  * `group` (String): The group for the user (default: `$user`).
  * `ensure` (Enum['present', 'absent']): Whether the application should exist (default: 'present').

### Define: `frankenphp::vhost`

Manages an entry (a "site") in the main proxy `Caddyfile`.

**Parameters:**

  * `server_name` (String): The vhost name (default: `$title`, e.g., 'https://www.google.com/url?sa=E\&source=gmail\&q=blog.example.com').
  * `mode` (Enum['proxy', 'fastcgi', 'php\_server']): How Caddy should handle this vhost. **For this architecture, always use 'proxy'**.
  * `proxy_target` (Optional[String]): The reverse proxy target (e.g., 'localhost:9010').
  * `fpm_socket` (Optional[String]): (For `fastcgi` mode) Path to the FPM socket.
  * `root_dir` (Stdlib::Absolutepath): (For `php_server`/`fastcgi` modes) Document root.
  * `extra_config` (String): A raw string of extra Caddy directives for this vhost (for logs, headers, etc.).
  * `ensure` (Enum['present', 'absent']): Whether the vhost should exist (default: 'present').

## Limitations

  * This module only installs FrankenPHP via the `.deb` package. It does not support other installation methods or operating systems.
  * The installation of the `supervisor` service itself is not handled. You must install it via another module or `package` resource.

## License

Apache 2.0

```