Linux distribution packaging #

This page is for packagers who want Exponential installable with apt or dnf. It states what exists and what packagers must decide themselves. The project publishes no deb or rpm package of the Exponential CMS; it does publish deb and rpm packages of Velocity, its web server.

Contents #

1. What the project publishes
2. How the installation is laid out
3. Composer and distribution policy
4. The post-install step
5. Updates through the package manager
6. Before you publish

What the project publishes #

The Velocity packages are a working model of how the project packages: architecture-independent, "Nothing starts on install", a qbix system user, settings in /etc/default/exponential-velocity.

How the installation is laid out #

Exponential is "a directory of PHP files" whose document root is the installation root (Web server examples). It writes into its own tree:

Source: Writable directories and permissions.

What this means for a package:

• Install the tree in one place (for example under /usr/share/<name>/) and symlink or bind the writable parts to /var/lib/<name>/ and /etc/<name>/ only after testing that every writer follows the links. The documentation does not describe a split layout; you own that test.
• site.ini [FileSettings] VarDir is set per siteaccess by the installer (var/<package> or var/site), and extra extension roots can be added with [ExtensionSettings] AdditionalExtensionDirectories[] (Additional extension directories). Those are the settings a layout can lean on.
• The web server configuration you ship must keep the routing of .htaccess_root.
• .htaccess and config.php are installation files, not package files: ship the templates (.htaccess_root, .htaccess_root_static, config.php-RECOMMENDED) and let the administrator, or your post-install step, copy them with exp:setup:htaccess and exp:setup:config. An update then never overwrites a changed copy: the commands show the diff and refuse unless given --force (Setting up .htaccess and config.php from the console).

Composer and distribution policy #

Exponential depends on many Composer packages (vendor/) and on extensions installed by a Composer plugin into extension/. Distributions differ in whether they accept vendored dependencies. Decide with your distribution's policy, and note:

• the extension set is defined by composer.json require; leaving required extensions out changes the product (Adding and removing extensions);
• composer licenses gives the license of every Composer package for your copyright file (Third-party components).

The post-install step #

A distribution package should not install a site by itself:

• Do: create the system user, set ownership of the writable directories, install a disabled web server and cron configuration, regenerate autoloads, print where the documentation and the install command are. Putting .htaccess and config.php into place is safe here, because both commands leave an existing file alone and change nothing on a second run; run as root they need --allow-root-user and --owner=<user>:<group> for the site's user:

  php bin/php/console exp:setup:htaccess --apply --allow-root-user --owner=www-data:www-data
  php bin/php/console exp:setup:config --apply --allow-root-user --owner=www-data:www-data

• Do not: create a database, run exp:install with defaults, or start a web server. The administrator runs the install once, with their own URL, database and e-mail (Unattended install with exp:install).

Updates through the package manager #

A package update replaces code; Exponential updates have a second half, the database update files and the checklist of each period (Chapter 11.6). The package can:

• clear caches and regenerate autoloads after the update (Caches and autoloads);
• tell the administrator when .htaccess no longer matches the new .htaccess_root: exp:setup:htaccess without --apply exits 1 and prints the diff, and exp:config:list shows settings new in config.php-RECOMMENDED as (not set);
• tell the administrator that a database update may be due, with the link;
• never run database updates unattended on a site it does not know.

Before you publish #

• To do: Copyright file lists Exponential (GPL-2.0-or-later), every extension and every vendored package.
• To do: Source package available, as distributions require anyway.
• To do: The package name and description follow Naming and branding a bundle.
• To do: Installation, upgrade and removal tested on a clean system.
• To do: Security fixes have a path: you track releases and rebuild (Updates and upgrade paths).

Related pages #

• Operating system support
• Velocity packages, Docker images and binaries
• GPL obligations when you distribute
• Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.