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 has two halves. phlat/ and vendor/ are code from the framework repository, and site/ is the site's own repository (its views, config and content). All of it is 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). Start from phlat/examples/deploy.example.php 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. site_repository is the site's own repository. site_branch picks which branch of it is deployed.

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.

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 framework and installs it with composer install --no-dev. The deploy:site task then clones the site repository into the release's site/. It is a full clone, because History needs the repository. 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/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>.

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.