Platform as a service
This page is for hosting companies that run a platform as a service (PaaS), or resell one, and want Exponential on it. A PaaS fixes the runtime: the customer pushes code, the platform builds and runs it, and the file system the application sees may be read-only or lost at every restart. The page answers what the project's sources say about such platforms, which directories Exponential writes and how they can be moved, and which questions to ask a platform before you offer Exponential on it.
Warning
.htaccess slows down every request. When .htaccess files are enabled (AllowOverride anything but None), let alone
used, Apache looks for them and reads and evaluates them on every request, in every directory of the path, and
page loading times go up drastically (measured). The only real fix is to switch the feature off for
the virtual host: AllowOverride None in the HTTPS virtual host, and the rules in the virtual host's own
configuration as mod_rewrite rules. That is far faster in production speed tests and well worth the time it takes
to optimize a production configuration. Switch over right away: copy the rules of the
example HTTPS virtual host into your virtual host (with the static cache, also
staticcache_offload.conf), set AllowOverride None, run apachectl configtest, reload Apache and
test the site. The same rules for other servers: nginx, LiteSpeed,
Caddy, IIS, Velocity (built in); where virtual host rules go in a control
panel: Plesk, cPanel, DirectAdmin, ISPConfig.
On LiteSpeed or OpenLiteSpeed, the server's own page cache can also answer anonymous visitors and crawlers without PHP: Page caching with LiteSpeed and OpenLiteSpeed.
Contents
- What the sources say
- What Exponential writes at run time
- Read-only or ephemeral file systems
- The database
- Processes: web, cron and long-running servers
- Build and release
- Questions to ask a platform
What the sources say
"Platform as a service offerings that run PHP 8 with a writable persistent disk are expected to work (tier 3).
Offerings with a read-only or ephemeral file system need var/ moved to persistent storage and a database server."
(Containers, cloud and hosting panels)
Tier 3 means "a reasoned expectation, not a test result" (The four tiers): no specific PaaS product is named or tested in the sources. Run a full test installation on the platform before you offer it.
What Exponential writes at run time
The setup wizard's directory_permissions test lists the directories that must be writable: design, extension,
settings, settings/override, settings/siteaccess, settings/siteaccess/admin, var, var/cache and its
subdirectories, var/log, var/storage and its subdirectories, var/autoload
(2.4 The setup wizard's system check).
| Path | Written when | Must persist? |
|---|---|---|
var/storage | every upload and image variation; the SQLite database in var/storage/sqlite3/ | yes |
var/cache, var/<site>/cache | on every request that fills a cache | no, but losing it costs a cold start |
var/log, var/<site>/log | errors, request logs, cron logs | collect or keep |
var/autoload | when autoloads are generated (also by composer install) | rebuilt at build time |
settings/override, settings/siteaccess | by the installer and when administrators save settings in the browser | yes |
design/, extension/ | only while packages are installed from the administration | no, if nothing installs packages at run time |
"After installation you can take write access to design/ and extension/ away again if nothing installs packages
from the administration; settings/ stays writable when administrators change settings in the browser"
(8.7.1).
Tip
On a PaaS, settings belong in the code repository. The switch [ConfigurationSettings] ManagedByDeployment=enabled
makes "the configuration of that siteaccess come from the deployment (version control) only": the administration
no longer writes *.ini.append.php or .tpl files on the server
(Configuration managed by the deployment).
Read-only or ephemeral file systems
The var directory is set by site.ini [FileSettings] VarDir (shipped var). The comment in settings/site.ini
is clear: "Only directories relative to the Exponential root are supported. Absolute directories are NOT
SUPPORTED." So mount the persistent storage at var/ inside the installation, rather than pointing VarDir
somewhere else.
Within var/ the sources offer finer control (site.ini [FileSettings],
Logs, INI cache and expiry timestamps per site):
| Setting | What it allows |
|---|---|
LogDir | an absolute path is supported: "the logs are never served" |
CacheDir | an absolute path "will be accepted, but won't work with some features and is NOT SUPPORTED": the public caches in it are not served. "To keep the cache on another file system, mount that at VarDir/CacheDir" |
LogVarDir, CacheVarDir | one tree for the logs or caches of every site |
ExpiryDir | keeps expiry.php, whose timestamps decide whether caches and image aliases are valid, when the cache directory is emptied at a restart |
Warning
If the cache directory is on storage that is emptied at a restart, set ExpiryDir to a directory on the persistent
volume. Otherwise the expiry timestamps are lost with the cache.
The database
In the official order: 1. SQLite 3 (the default) · 2. PostgreSQL · 3. MongoDB · 4. MariaDB · 5. Oracle · 6. MySQL. Microsoft SQL Server is known to be possible with additional work at this time.
With a read-only or ephemeral file system the sources require a database server. Even with a persistent disk, a platform that may run more than one instance of the application cannot share one SQLite file between them. Use the platform's managed database, 2. PostgreSQL first if it offers several (Database support).
Processes: web, cron and long-running servers
- Web. If the platform runs PHP behind its own web server (PHP-FPM style), it needs the rewrite rules of
.htaccess_roottranslated to that server: "only a fixed list of asset paths is served as files; everything else is passed toindex.php" (13.2). A generic "serve the file if it exists" configuration would hand outsettings/*.ini. - Velocity needs a long-running process and PHP 8.0 or later with
sockets. A platform that runs one process per container and routes HTTP to a port can run it; one that only runs PHP per request cannot. - Cron.
runcronjobs.phpmust run on a schedule, once per site, with the same code and settings (Cron jobs). Ask whether the platform has a scheduler. - Sessions. With more than one instance, sessions must be shared; see Kubernetes, Sessions.
Build and release
- Build:
composer install(which also runsbin/php/ezpgenerateautoloads.phpthrough thelegacy-scriptsscript) (2.7 Composer). - Install once, against the managed database, with
exp:installand secrets from the environment (EXP_INSTALL_DB_PASSWORD) (4.6). - Every later release: new code, the same persistent
var/and database, the schema update files when an upgrade calls for them, then a cache clear (Deploying changes). .htaccessandconfig.phpin the build or at start, unattended:./console exp:setup:htaccess --apply,./console exp:setup:config --apply, then./console exp:config:set <NAME> <value> --applywith values from the platform's environment variables (--value="$CLUSTER_DB_PASS"for a secret). Each command asks nothing, ends withPASS:orFAIL:, exits 0, 1 or 2 and changes nothing on a second run. A build step that runs as root needs--allow-root-userand, so the files do not belong to root,--owner=www-data:www-data(In scripts, containers and CI).
Questions to ask a platform
| Question | Why |
|---|---|
Which PHP versions and extensions, and can I add intl, xsl and a database extension? | the required set (2.3) |
Is there a persistent disk, and can it be mounted at var/ inside the application? | VarDir must be relative |
| How many instances may run at once? | one writer for SQLite; shared sessions and storage otherwise |
| Is there a scheduler? | runcronjobs.php |
| May a long-running process listen on a port? | Velocity |
| Can I configure the web server's rewrite rules? | the asset list of .htaccess_root |
| Which databases are offered as managed services? | the official order |
| How are backups of the disk and the database taken and restored? | the backup set: database, var/storage, settings/override, settings/siteaccess |
Related pages
- Choosing a hosting model, Containers: Docker and Podman
- Writable directories and permissions
- Storage layout
- Setting up .htaccess and config.php from the console
- Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.
Become an Exponential Partner
Partners share their information, provide funding, contribute back and develop the products with us, and that is how Exponential grows. A partner website and dashboard are planned for mid-2027: please become a partner today to speed up our growth rate and land new features faster.