Operating System BSD

How to Install Backdrop CMS on FreeBSD 15 with Apache, MariaDB and PHP

Install Backdrop CMS on a FreeBSD 15 server with Apache 2.4, MariaDB and PHP 8.4, from packages to a working site with safe file permissions.

By the end of this guide you will have Backdrop CMS running on a FreeBSD server with Apache 2.4, MariaDB and PHP (a FAMP stack), with clean URLs and sensible file permissions. The steps are written for FreeBSD 15.1, the current production release, and work the same way on the 14.5 legacy release. FreeBSD 11 reached end of life in 2021 and no longer receives packages.

Backdrop is a maintained fork of Drupal 7 aimed at small and medium sites. It needs PHP 7.1 or newer, MySQL or MariaDB 5.5 or newer, and Apache (recommended) or Nginx.

Requirements

  • A FreeBSD 15.1 or 14.5 server with root access over SSH. Commands below are run as root; if you use sudo or doas, prefix them accordingly.
  • A domain name such as example.com pointing to the server.
  • At least 50 MB of free disk space for Backdrop itself, plus room for uploads and the database.

Update the package catalogue and installed packages first, and apply pending base system updates with the method your installation uses:

pkg update
pkg upgrade

Install Apache, MariaDB and PHP

FreeBSD's default PHP is now 8.5. Backdrop's release notes confirm support up to PHP 8.4, so this guide installs the 8.4 packages explicitly; they sit alongside the default in the package repository.

pkg install apache24 mariadb118-server mariadb118-client \
  php84 mod_php84 php84-dom php84-filter php84-gd php84-session \
  php84-simplexml php84-xml php84-pdo php84-pdo_mysql php84-mbstring \
  php84-curl php84-zip php84-opcache

That list covers every extension the Backdrop installer checks for that is not already compiled into PHP (dom, filter, gd, session, SimpleXML, xml, pdo) plus the MySQL driver. OpenSSL support, which Backdrop needs for its update manager, is built into the base php84 package.

Create a PHP configuration file from the production template:

cp /usr/local/etc/php.ini-production /usr/local/etc/php.ini

Create the database

Enable and start MariaDB, then run the hardening script and accept its suggestions:

sysrc mysql_enable=YES
service mysql-server start
mariadb-secure-installation

Open the MariaDB shell as root:

mariadb -u root

Create a database and a dedicated user. Use your own strong password:

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

Download Backdrop

Releases are published on GitHub and linked from backdropcms.org. At the time of writing the current release is 1.35.2; check the download page for a newer one and adjust the version in the URL.

cd /tmp
fetch https://github.com/backdrop/backdrop/releases/download/1.35.2/backdrop.zip
unzip backdrop.zip -d /usr/local/www/

The archive unpacks into /usr/local/www/backdrop. Apache runs as the www user on FreeBSD. Keep the code owned by root and give the web server write access only where Backdrop needs it: the files directory, and settings.php while the installer runs.

chown -R root:wheel /usr/local/www/backdrop
chown -R www:www /usr/local/www/backdrop/files
chown www:www /usr/local/www/backdrop/settings.php

Configure Apache

Backdrop uses mod_rewrite for clean URLs, and the module is disabled in FreeBSD's default configuration. Open /usr/local/etc/apache24/httpd.conf and remove the leading # from this line:

LoadModule rewrite_module libexec/apache24/mod_rewrite.so

Files in /usr/local/etc/apache24/Includes/ ending in .conf are loaded automatically. Create /usr/local/etc/apache24/Includes/php.conf to hand PHP files to mod_php:

DirectoryIndex index.php index.html
<FilesMatch "\.php$">
    SetHandler application/x-httpd-php
</FilesMatch>

Then create /usr/local/etc/apache24/Includes/backdrop.conf for the site. AllowOverride All is required so that Backdrop's own .htaccess file is applied:

<VirtualHost *:80>
    ServerName example.com
    DocumentRoot "/usr/local/www/backdrop"
    <Directory "/usr/local/www/backdrop">
        AllowOverride All
        Require all granted
    </Directory>
</VirtualHost>

Check the syntax, enable Apache at boot and start it:

service apache24 configtest
sysrc apache24_enable=YES
service apache24 start

Run the installer

Browse to http://example.com/. If the installer does not appear, open http://example.com/install.php. It walks through these steps:

  1. Choose a language.
  2. Requirements check. A missing PHP extension is reported here by name.
  3. Database: enter the database name backdrop, the user backdrop and its password.
  4. Site information: site name and the first administrator account.

When it finishes you are logged in to the new site.

Lock down settings.php

The installer has written the database credentials to settings.php. Leaving that file writable by the web server is a security risk, so make it read-only for Apache:

chown root:www /usr/local/www/backdrop/settings.php
chmod 440 /usr/local/www/backdrop/settings.php

Also open settings.php as root and set trusted_host_patterns so that Backdrop only answers for your own host name:

$settings['trusted_host_patterns'] = array('^example\.com$', '^www\.example\.com$');

Verify and maintain

  • In the admin menu open Reports → Status report. It lists the PHP and database versions and flags anything that still needs attention.
  • Open any content page and confirm the address has no ?q= in it. If clean URLs fail, mod_rewrite is not loaded or AllowOverride All is missing.
  • Add HTTPS before you put real accounts on the site, for example with a Let's Encrypt certificate and Apache's mod_ssl.
  • Keep the stack patched with pkg upgrade, and watch Backdrop's security announcements. Core updates can be installed from the admin interface or by replacing the core directory with the one from a new release.

The official installation instructions and system requirements cover further options.

Frequently asked questions

Why PHP 8.4 instead of FreeBSD's default 8.5?

Backdrop announced PHP 8.4 support with version 1.31. Support for 8.5 was not confirmed in the project's documentation when this was written. Once it is, switch by installing the matching php85 and mod_php85 packages in place of the 8.4 ones.

Where does Backdrop store its configuration?

Configuration is kept as JSON files, by default in a config_…/active directory under files. The comments in settings.php recommend moving the config directories to a location that is not reachable through the web server and updating $config_directories to match.

Can I use Nginx or MySQL instead?

Yes. Backdrop supports Nginx with PHP-FPM, and MySQL 5.5 or newer works in place of MariaDB. With Nginx you must translate the rewrite rules yourself because .htaccess files are not read; the system requirements page includes a sample configuration.

Can I migrate a Drupal 7 site to Backdrop?

Backdrop includes an upgrade path from Drupal 7: you point a fresh Backdrop code base at a copy of the Drupal 7 database and run the update script. Contributed modules need Backdrop versions, so check each one before you start.

Share story:

Continue reading other guides on How VPS.