Chapter 03

Choosing an image

The image is the runtime your site gets. There are two, they layer on each other, and the choice is mostly whether you need PHP.

The two images

Static Website Laravel App

nginx serving files straight from your folder. Everything in the static image, plus PHP 8.3 via php-fpm, and supervisor for background work.

Docroot is the folder root. Docroot is public/ inside the folder's application/ subdirectory.

No settings to configure. One setting: PHP memory limit.

No background programs. Queue workers, scheduler, and boot tasks.

Good for: built front-ends, static exports, landing pages, anything you compile elsewhere. Good for: Laravel, and PHP applications generally — the layout convention is Laravel's, but nothing is Laravel-specific.

Static Website	Laravel App
nginx serving files straight from your folder.	Everything in the static image, plus PHP 8.3 via php-fpm, and supervisor for background work.
Docroot is the folder root.	Docroot is `public/` inside the folder's `application/` subdirectory.
No settings to configure.	One setting: PHP memory limit.
No background programs.	Queue workers, scheduler, and boot tasks.
Good for: built front-ends, static exports, landing pages, anything you compile elsewhere.	Good for: Laravel, and PHP applications generally — the layout convention is Laravel's, but nothing is Laravel-specific.

Despite the name, the Laravel image is a general PHP 8.3 runtime. If your PHP application serves from a public/ subdirectory and tolerates a front-controller rewrite, it will run.

What the PHP image includes

PHP 8.3 with these extensions compiled in and enabled:

fpm  cli  mysql  mbstring  xml  bcmath
curl  zip  gd  redis  opcache  intl

Composer is installed and on the path, as are git and unzip. That matters because there is no build step outside the container — if you need to install dependencies, you do it inside the container against the mounted folder.

Requests are served by nginx with a standard front-controller rewrite: anything that is not a real file falls through to index.php. Static assets — images, fonts, CSS and JS — get a one-year immutable cache header, so fingerprint your asset filenames if you expect to change them.

Dotfiles are not served

Requests for paths beginning with a dot are refused, so a stray .env or .git in the docroot is not exposed. The one exception is /.well-known/, which is allowed through for certificate validation and similar uses.

The setting you can change

Images declare which settings they accept. Today the Laravel image declares exactly one, and the static image declares none.

PHP memory: PHP_MEMORY_LIMIT — default 256M. Accepts any value PHP understands, such as 512M. Applied when the container starts.

You choose settings when creating a site and can change them afterwards. Changing a setting recreates the container. Your domain, folder, route, certificate and files all survive that — the site is briefly unavailable while the new container starts, and nothing else moves.

There is no way to add your own environment variables

Only settings declared by the image become environment variables in the container. Arbitrary keys are rejected rather than passed through, so you cannot inject DB_PASSWORD or an API key through the panel.

Your application's own configuration belongs in a file in your site folder — for Laravel, the usual .env. It sits outside the docroot and is not web-accessible. See chapter 06 for the connection details to put in it.

Changing image later

A site can move from one image to another. Settings that both images declare carry over if the value is still valid; settings only the new image declares take their default; settings only the old image had are dropped. The panel shows you exactly which of those three happens to each setting before you confirm.

What it does not do is move your files. Because the two images use different docroots, switching a site from static to PHP means your content needs to end up under application/public/ — that rearrangement is yours to do.

Adding a new runtime

The catalog is extensible — a new image is a Dockerfile plus a catalog entry, with no panel changes. But building and registering images is an operator task, not something you can do from the panel. Ask your operator if you need a runtime that is not listed.