Operating System CentOS

How to Install Elgg 7 on AlmaLinux 9 or Rocky Linux 9 with Nginx

Set up Elgg 7 on AlmaLinux 9 or Rocky Linux 9 with Composer, Nginx, PHP 8.3 and MariaDB 10.11, then add the SELinux contexts and cron job it needs.

Elgg is an open source social networking engine written in PHP: member profiles, groups, activity streams, messaging, blogs and file sharing, extended through plugins. This guide installs the current Elgg 7 release with Composer on AlmaLinux 9 or Rocky Linux 9, served by Nginx and PHP-FPM with MariaDB as the database. At the end you have a working site, an administrator account and the cron job Elgg needs for background tasks.

CentOS 7 reached end of life in June 2024 and its PHP and MySQL packages are far too old for Elgg today. AlmaLinux 9 and Rocky Linux 9 are the drop-in replacements from the same RHEL family, and the commands below also apply to CentOS Stream 9 and RHEL 9.

Requirements

Elgg 7 needs PHP 8.3 or newer, MariaDB 10.6 or newer (or MySQL 8.4 or newer), a web server with URL rewriting and a working mail transfer agent. The Elgg project officially supports two web server setups: Apache with PHP as a module, and Nginx with PHP-FPM. RHEL 9 family systems run PHP through PHP-FPM, so this guide uses Nginx.

  • A server running AlmaLinux 9 or Rocky Linux 9, release 9.6 or later (the PHP 8.3 module stream was added in 9.6). Run sudo dnf upgrade first if you are on an older point release.
  • A user with sudo rights; the examples use deploy.
  • A domain name pointing at the server; the examples use example.com.

Step 1: Install Nginx, MariaDB and PHP 8.3

The default PHP (8.0) and MariaDB (10.5) packages on these systems are below Elgg's minimums. Enable the newer module streams before installing anything:

sudo dnf module enable -y php:8.3 mariadb:10.11

Install the web server, the database server and PHP with the extensions Elgg requires (GD, intl, mbstring, PDO with the MySQL driver, XML), plus Git and the zip tools Composer uses:

sudo dnf install -y nginx mariadb-server php-fpm php-cli php-gd php-intl php-mbstring php-xml php-pdo php-mysqlnd php-opcache php-pecl-zip unzip git policycoreutils-python-utils

Start the three services and enable them at boot:

sudo systemctl enable --now nginx mariadb php-fpm

Open the web ports in firewalld:

sudo firewall-cmd --permanent --add-service=http --add-service=https
sudo firewall-cmd --reload

Confirm the PHP version before continuing:

php -v

Step 2: Create the database

Run the hardening script and answer its questions (remove anonymous users, disallow remote root login, remove the test database):

sudo mariadb-secure-installation

Open the MariaDB shell as root:

sudo mariadb

Create a database and a dedicated user. Replace the password with your own:

CREATE DATABASE elgg CHARACTER SET utf8mb4;
CREATE USER 'elgg'@'localhost' IDENTIFIED BY 'change-this-password';
GRANT ALL PRIVILEGES ON elgg.* TO 'elgg'@'localhost';
EXIT;

Step 3: Install Composer

The Elgg project recommends installing with Composer. Download the installer, run it and place the binary in /usr/local/bin:

cd ~
php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
sudo php composer-setup.php --install-dir=/usr/local/bin --filename=composer
php -r "unlink('composer-setup.php');"

The Composer download page publishes a SHA-384 checksum for the installer and a one-line command to verify it; run that check between the first and second command if you want to confirm the file is intact.

Step 4: Download Elgg

Elgg needs two directories: the project root that Nginx serves, and a data directory for uploads and caches that must sit outside the document root. Create both, with the code owned by your own user and the data directory owned by apache, the account PHP-FPM runs as on these systems:

sudo mkdir -p /var/www/elgg /var/www/elgg-data
sudo chown deploy:deploy /var/www/elgg
sudo chown apache:apache /var/www/elgg-data
sudo chmod 750 /var/www/elgg-data

Create the project from Elgg's starter project. Its composer.json pulls in the Elgg 7 series. The Elgg documentation notes that composer install currently has to be run twice:

composer create-project elgg/starter-project:dev-master /var/www/elgg
cd /var/www/elgg
composer install
composer install

SELinux is enforcing by default. Elgg's documentation asks for the httpd_sys_rw_content_t context on the project root and the data directory, and for two booleans that let PHP open network and database connections:

sudo semanage fcontext -a -t httpd_sys_rw_content_t "/var/www/elgg(/.*)?"
sudo semanage fcontext -a -t httpd_sys_rw_content_t "/var/www/elgg-data(/.*)?"
sudo restorecon -R /var/www/elgg /var/www/elgg-data
sudo setsebool -P httpd_can_network_connect 1
sudo setsebool -P httpd_can_network_connect_db 1

Step 5: Configure Nginx

Elgg ships a sample Nginx configuration in vendor/elgg/elgg/install/config/nginx.dist. The server block below is that sample adjusted for the PHP-FPM socket used on AlmaLinux and Rocky Linux. Create the file:

sudo nano /etc/nginx/conf.d/elgg.conf

Add:

server {
    listen 80;
    server_name example.com;

    root /var/www/elgg;
    index index.php index.html;

    client_max_body_size 8M;

    location ~ /.well-known {
        allow all;
    }

    location ~ (^\.|/\.) {
        return 403;
    }

    location = /rewrite.php {
        rewrite ^(.*)$ /install.php;
    }

    location / {
        try_files $uri $uri/ @elgg;
    }

    location /cache/ {
        disable_symlinks off;
        expires 1y;
        try_files $uri $uri/ @elgg;
    }

    location ~ \.php$ {
        try_files $uri @elgg;
        fastcgi_index index.php;
        fastcgi_pass unix:/run/php-fpm/www.sock;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include /etc/nginx/fastcgi_params;
    }

    location @elgg {
        fastcgi_pass unix:/run/php-fpm/www.sock;
        include /etc/nginx/fastcgi_params;
        fastcgi_param SCRIPT_FILENAME $document_root/index.php;
        fastcgi_param SCRIPT_NAME /index.php;
    }
}

Test the configuration and reload Nginx:

sudo nginx -t
sudo systemctl reload nginx

If the site will be served over HTTPS, obtain the certificate and add the TLS server block now, before running the installer, so that you can give the installer the final https:// address. Certificate setup is the same as for any other Nginx site.

Step 6: Run the Elgg installer

The installer writes elgg-config/settings.php and fills the data directory, so run it as the apache user. Give that user temporary ownership of the configuration directory first:

sudo chown apache /var/www/elgg/elgg-config
cd /var/www/elgg
sudo -u apache php vendor/bin/elgg-cli install

The installer asks a series of questions. Answer them as follows:

  • Admin username, password, email: the first account, which becomes the site administrator.
  • Database host and port: accept localhost and 3306.
  • Database username, password, name: elgg, the password from step 2, elgg.
  • Database prefix: for example elgg_.
  • Site name and site email: shown on the site and used as the sender of notifications.
  • Site URL: the full address with protocol and a trailing slash, for example https://example.com/.
  • Data directory path: /var/www/elgg-data/.

When it finishes it prints a line such as Elgg 7.x.x install successful followed by the site URL and data paths. Hand the configuration directory back to your user and keep the settings file, which contains the database password, readable only by you and PHP-FPM:

sudo chown deploy /var/www/elgg/elgg-config
sudo chown deploy:apache /var/www/elgg/elgg-config/settings.php
sudo chmod 640 /var/www/elgg/elgg-config/settings.php

If you prefer a browser, skip elgg-cli install and open http://example.com/ instead: the same questions appear as a web wizard.

Step 7: Set up cron

Elgg relies on cron for notifications, cleanup and other timed jobs. Edit the crontab of the apache user:

sudo crontab -u apache -e

Add one line that runs Elgg's cron handler every minute; Elgg decides which jobs are due:

* * * * * /usr/bin/php /var/www/elgg/vendor/bin/elgg-cli cron -q

Verify the installation

Open your site URL and log in with the administrator account. The dashboard under Administration lists warnings if something is missing, such as cron not having run yet. Give cron a few minutes, then reload the page.

Elgg sends registration and notification mail through the local MTA using PHP's mail function. Install and configure an MTA such as Postfix, or point it at an SMTP relay, before you open registration; without one, new members never receive their validation email.

Updating Elgg

Back up the database, the data directory and the project directory first. Then update the code with Composer as your own user and run the upgrade as the PHP-FPM user:

cd /var/www/elgg
composer update
sudo -u apache php vendor/bin/elgg-cli upgrade async -v

Within one major series you can go straight to the newest release. Read the upgrade notes in the Elgg upgrade documentation before moving to a new major version, because plugins often need updating at the same time.

Frequently asked questions

Can I use Apache instead of Nginx?

Yes. Elgg supports Apache with mod_rewrite, and the starter project already contains the .htaccess file it needs; the virtual host must set AllowOverride All for the project directory. Note that the configuration Elgg tests against is PHP running as an Apache module, while the RHEL 9 family runs PHP through PHP-FPM for Apache as well.

Why does the installer say it cannot write the settings file?

The user running the installer has no write access to elgg-config. Either give the apache user temporary ownership of that directory as in step 6, or copy elgg-config/settings.example.php to elgg-config/settings.php and fill in the database details by hand.

Is there a long-term support release?

Yes. Alongside the current 7.x series, the Elgg project maintains the 6.3 series as an LTS release with bug and security fixes. New sites should start on 7.x; the starter project has a 6.x branch if a plugin you depend on has not been updated yet.

I get a 403 or a blank page after installing. What should I check?

Look at /var/log/nginx/error.log and /var/log/php-fpm/www-error.log first. On these systems the usual cause is SELinux: check that the contexts from step 4 were applied with ls -Zd /var/www/elgg /var/www/elgg-data and that the data directory is owned by apache.

Share story:

Continue reading other guides on How VPS.