Deploy

Keep per-deployment config in env.json, ship releases with Deployer, and back up what matters.

Updated
On this page

A deployment is two things: the code, which is rebuilt from git on every release, and your state (site/pages/ and site/data/: pages, collections, users and secrets), which stays on the server between releases.

PhlatPage runs on PHP 8.4 behind any web server whose document root is site/public/. The project ships a Deployer config for releases over SSH. If you already have a way to deploy PHP, use it: keep site/pages/ and site/data/ out of the release and back them up.

Build the CSS and JS before you deploy. The deploy does not run a build step.

Layout

A deployment is the site's repository with PhlatPage installed by Composer into vendor/, rebuilt from git on every release. site/pages/ is the content, a git repository of its own that History commits to. site/data/ is state: collections/, users/, git/ (the History deploy key), storage/ (the registry, locks and rate limits), cache/ (compiled views and the like, which can be deleted at any time) and env.json. State is never part of a release and survives redeploys, except cache/, which each release makes for itself.

Config

Config merges in order, later wins: phlat/config.json, site/config.json, site/data/env.json. Put secrets and per-host overrides in site/data/env.json, which is gitignored. site/data/env.cli.json merges on top for CLI runs only.

Deployer

deploy.php ships the code to a host over SSH. It imports two recipes from the framework: phlat/deploy/recipe.php (the release, shared paths, registry rebuild and PHP restart) and phlat/deploy/provision.php (the server). Import them from vendor/coheredigital/phlatpage/phlat/deploy/ and set the repository, host, its domain and the deploy user (remote_user). A site deploys to /var/www/{domain}; set sites_root to change the base folder. The deploy user owns the code and PHP-FPM runs as www-data (http_user), which can write only the shared state folders, so a compromised request cannot rewrite the code. PHP-FPM and the deployed phlat CLI both run with umask 002, so a file either one creates in those folders stays writable for the other. A project that checks out the framework itself and keeps site/ in a second repository sets phlat_cli to phlat/addons/cli/phlat and clones the site with its own deploy:site task, as the framework's own deploy.php does.

recipe.php expects site/pages to be a repository of its own, edited on the server, so it is shared and kept across releases. A site that keeps its pages in the same repository as its code imports phlat/deploy/recipe.simple.php instead of recipe.php. Every release then ships its own site/pages, so a change made to pages on the server is lost on the next deploy.

Provisioning a server

dep provision sets up a fresh Debian 13 server over SSH as root: Caddy, PHP-FPM on Debian's default www-data pool, composer and git, a firewall, the deploy user with its key, and a Caddyfile for the site in deploy_path. It prints the deploy user's public key, which you add as a read-only deploy key on the repositories. Run it again with another host to add a site to the same server.

After the first deploy, dep provision:admin creates the first admin user and asks for the password, hidden. A site served without a certificate, behind a proxy or on a private network, sets http to true on its host. Set proxy to the proxy's IP or network and the firewall opens the web port to that address only, and the site's Caddyfile reads the visitor's scheme and IP from the proxy's X-Forwarded-Proto and X-Forwarded-For, so the proxy must send both (Caddy's reverse_proxy does); dep provision:proxy applies both to a server that is already provisioned. dep provision:remove takes a site out of Caddy and leaves its files. dep provision:firewall:allow, :close and :status manage the firewall rules: pass the port with -o ufw_port=8080 (or 8080/udp, or a range such as 6000:6010/tcp) and limit it to one source with -o ufw_from=10.0.0.5.

A server that runs Docker imports phlat/deploy/provision.docker.php instead of provision.php. It installs Docker only when the server has none, adds the deploy user to the docker group and writes two compose stacks, php and proxy, to /home/{user}/stack/. Sites live in /home/{user}/websites/{domain}. PHP-FPM runs as www-data in the php stack, and Caddy runs in the proxy stack on the host's network, so the firewall applies to it. Composer and the phlat CLI run in the PHP image, so the server needs no PHP. Docker publishes its own ports around ufw, so the firewall tasks do not open or close those.

To monitor the server with a Beszel hub, import phlat/deploy/beszel.php beside provision.php, set beszel_key (the hub's public key) and beszel_hub (its IP or network) on the host and run dep provision:beszel. It installs the agent as the deploy user, with no root service, and the firewall lets only the hub reach its port (beszel_port, 45876 by default). If you leave either value unset, the task asks for it.

vendor/bin/dep deploy domain.com

Each release clones the site repository and installs the framework with composer install --no-dev. These paths are shared between releases and symlinked in:

  • site/data/env.json and site/data/env.cli.json
  • site/data/collections, site/data/users, site/data/git, site/data/storage
  • site/public
  • site/pages, when it is a repository of its own (see Deployer)

site/data/cache is not shared. Each release starts with its own, so a release never serves what an earlier one rendered.

Before a release goes live the deploy rebuilds the registry and runs phlat health:check, and a failed check stops it with the old release still serving. Skip it with dep deploy -o skip_health=1. A new env.json is seeded after composer install with url (the host's domain, https unless http is set with no proxy) and a generated app.key. Change a value later with phlat env:set <key> <value>.

To keep a host's env.json with the project, save it as site/data/env.{alias}.json on your machine, where {alias} is the name the host is declared with in deploy.php, such as env.phlat.json for host('phlat'). site/data is never in git, so the secrets stay off the repository, and the upload keeps them out of the deploy log. Each deploy uploads the file over that host's env.json as it is, with no merge, so it must hold everything, app.key included. A host with no such file keeps the server's own. dep env:pull saves the server's current env.json under that name, which is the way to start after a first deploy. Upload without a full deploy with dep env:push, or skip it with dep deploy -o skip_env=1.

A deploy never restarts PHP, so the deploy user needs no sudo. site/public/index.php reads the release from the current symlink with readlink(), which skips PHP's realpath cache, and opcache keys its scripts by the release's real path, so the new release is live the moment the symlink moves. Every release leaves its compiled scripts in opcache. With opcache.validate_timestamps=0 nothing is ever marked as wasted, so size opcache.memory_consumption for several releases and reload PHP now and then, which also picks up a changed index.php.

Backups

site/pages/ and site/data/ are the state to protect. One command backs up pages with their History, collections, users, git/ and the env files; restore with backup:restore. storage/ and cache/ are left out: restore rebuilds the registry from the pages and empties the cache.

vendor/bin/phlat backup:create

Behind a proxy

The visitor's IP is the web server's REMOTE_ADDR, and the login throttle counts attempts per IP. With a load balancer or CDN in front, set the server's trusted proxies so REMOTE_ADDR is the real client, not the proxy, or every visitor shares one address and five failed sign-ins lock everyone out. In Caddy 2.7 and later that is trusted_proxies in the global options. PhlatPage has no setting of its own for this.

Response headers

Every response carries X-Frame-Options: SAMEORIGIN and X-Content-Type-Options: nosniff. A site that must be embedded elsewhere removes the first in an app.request:before listener:

$app->on('app.request:before', fn() => Res::removeHeader('X-Frame-Options'));

PhlatPage sends no Content-Security-Policy on pages, because a policy has to match what a site loads: its fonts, images, embeds and scripts. A site that wants one sets it in the same listener, using nonce() to allow its own inline <script> and <style> tags:

$app->on('app.request:before', fn() => Res::header('Content-Security-Policy', "default-src 'self'; script-src 'self' 'nonce-{$app->request->nonce()}'"));

The built-in views use inline style attributes, and HTMX runs hx-on: handlers as code, so a policy that covers the dash needs style-src 'unsafe-inline' and 'unsafe-eval' in script-src. Open the dash with the policy on before deploying it.

Directory structure

my-site/
  phlat/          ← framework core (do not edit)
  site/           ← your site, its own git repo
    views/        ← templates, routers, and controllers (colocated per view)
    fields/       ← your field definitions
    fieldtypes/   ← custom field types
    addons/       ← site-specific addons
    public/       ← web document root
      index.php
    config.json   ← site config, merged over phlat/config.json
    pages/        ← your content, its own git repo (History commits here)
    data/         ← per-deployment state, survives redeploys
      collections/  ← collection items (gitignored)
      users/        ← user accounts
      git/          ← History's deploy key (gitignored)
      storage/      ← registry, locks, rate limits (gitignored)
      cache/        ← compiled views, fragments, thumbnails; delete any time (gitignored)
      env.json      ← deployment secrets and overrides (gitignored)

Switching branches

Because site/ is a repo of its own, switching its branch swaps the whole site: code, config and pages. The registry, cache and collections are not in git and stay behind, so after a switch run phlat registry:rebuild and phlat cache:clear.

Entry point

The web server's document root must be site/public/, whose index.php is the entry point:

<?php

// DOCUMENT_ROOT stays the logical path; __DIR__ resolves through a shared symlink on deploy
$public = $_SERVER['DOCUMENT_ROOT'];

require_once "{$public}/../../vendor/autoload.php";

Phlat::app(dirname($public))->execute();

Phlat::app() returns the singleton App for the site root. execute() resolves the URL to a page, runs the view's router and renders the response.