Preparing any other Linux server

This page is for a Linux distribution the other installation pages do not name. It says what a hub needs rather than which packages to install, because those are the distribution's to name. The steps are the same as on every other system; only the package names and paths are yours to find. When this page has prepared the server, Installing the hub installs it.

If your distribution has no PHP 8.2 and no second source of it, run the hub in Docker instead: Preparing a server for FrankenPHP in Docker needs no PHP on the server at all.

What you need

• A Linux server, and an account on it that can use sudo.
• A name for the hub, such as hub.example.org, pointing at the server, and a TLS certificate for it. A hub has to be served over HTTPS: the administrator sign-in form always posts to an https:// address, so on plain HTTP the administrator can never sign in.

1. Install MariaDB, PHP and the tools

Install, from the distribution or a repository that packages them for it:

• MariaDB. The hub was installed against 10.11 and 11.8, with their default SQL mode. MySQL is expected to work but was not tried; its default SQL mode is stricter than MariaDB's and rejects the zero dates hub data carries, so on MySQL set sql_mode to MariaDB's default, given on Installing the hub.
• PHP 8.2, both its command line and PHP-FPM, with these extensions in whatever packages they come in: pdo_mysql, mbstring, curl, gd, zip, fileinfo, openssl, the XML family (dom, simplexml, xmlreader, xmlwriter), sockets and posix. If the distribution ships another version of PHP, look for a second repository that packages 8.2 for it, as Debian, Ubuntu and Enterprise Linux each have.
• git and unzip.

Start MariaDB and PHP-FPM, and have them start at boot.

Check PHP. This lists any extension the hub needs that is missing, and prints nothing when all of them are there:

php -r 'foreach (["pdo_mysql","mbstring","curl","gd","zip","fileinfo","openssl","dom","simplexml","xmlreader","xmlwriter","sockets","posix","json","ctype","iconv","zlib"] as $e) if (!extension_loaded($e)) echo "missing: $e\n";'

Then find three things the later steps depend on:

1. The account PHP-FPM runs as. It is the user line of PHP-FPM's pool configuration, usually a file named www.conf. The hub's files belong to that account. This page calls it the PHP-FPM account.
2. The socket PHP-FPM listens on. It is the listen line of the same file. The web server's configuration names it.
3. Where PHP keeps sessions. session.save_path, in PHP-FPM's php.ini or pool. It has to be a directory the PHP-FPM account can write to, outside the hub's directory: the installer keeps its secrets there, and stops at a page headed Server Configuration Required without one.

2. Install the web server

Choose Apache or nginx. Install one of them, not both.

Apache, with mod_proxy_fcgi, mod_setenvif and mod_ssl enabled.

Or nginx.

If the distribution starts with its firewall closed, open ports 80 and 443.

3. Get the code

The repository is the hub: its top directory is the web server's document root. Clone it, and give it to the PHP-FPM account:

sudo git clone --branch 2.4-main https://github.com/hubzero/hubzero-cms.git /var/www/hub
sudo chown -R <the PHP-FPM account>: /var/www/hub

The installer writes the hub's configuration into a new app/ directory inside it, and the hub later keeps its uploads, logs and cache there, so the PHP-FPM account has to be able to write to the whole tree.

Now the installer's own check covers everything else it needs, without changing anything:

cd /var/www/hub
sudo php core/bin/muse install check

If the distribution runs SELinux, turn it off: hubs run with it off and are not tested with it on. Enterprise Linux 9 shows how. AppArmor, as Debian and Ubuntu ship it, does not confine the web server or PHP, and the installs on Ubuntu were run with it as it ships.

4. Configure the web server

Every configuration for the hub does the same four things:

• serves /var/www/hub as the document root, over HTTPS;
• passes PHP files to PHP;
• sends every address that is not a file to index.php, which is how the hub's addresses work;
• refuses requests for the hub's configuration, logs, temporary files, command-line programs and hidden files.

The last of those matters: app/config/database.php holds the database password, and nothing else stops a browser from reading it.

Start from the configuration for your web server on Debian 12, and change only what is your distribution's:

• where the file goes, and whether it needs enabling;
• the PHP-FPM socket, in SetHandler for Apache or fastcgi_pass for nginx;
• the log locations, and the certificate paths.

Until the hub has a real certificate, or before its name reaches the server, use a self-signed one. The hub is always served over HTTPS, but it need not wait. Many distributions make one when their web server's TLS module is installed; if yours does not, openssl makes one with the hub's name:

sudo mkdir -p /etc/ssl/private /etc/ssl/certs
sudo openssl req -x509 -newkey rsa:2048 -nodes -days 365 \
    -subj "/CN=hub.example.org" -addext "subjectAltName=DNS:hub.example.org" \
    -keyout /etc/ssl/private/hub.key -out /etc/ssl/certs/hub.crt
sudo chmod 600 /etc/ssl/private/hub.key

Browsers warn about it; accept the warning to reach the installer, and put the real certificate's paths in when it arrives.

Keep the rest as it is: each of its rules is one of the four things above, and the hub needs all four. Under nginx, do not route PHP through a distribution snippet that answers 404 for a .php address with no file behind it: /administrator/index.php is answered by the hub's own index.php.

5. Next: install the hub

The server is ready. Go on to Installing the hub, which creates the database and runs the installer, the same way on every system.