Operating System BSD

How to Install Omeka Classic 3.2 on FreeBSD 15 with Apache, MariaDB and PHP

Set up Omeka Classic 3.2 on a FreeBSD 15 FAMP stack, from packages and database to the web installer, ImageMagick thumbnails and upgrades.

Omeka Classic is an open-source publishing platform for digital collections and exhibits, used by libraries, museums and archives. This guide installs the current release, Omeka Classic 3.2.2, on FreeBSD 15.1 with Apache 2.4, MariaDB and PHP 8.5 (a FAMP stack). The same steps work on the FreeBSD 14.5 legacy release. FreeBSD 11 is long past end of life and no longer receives packages.

Omeka's documentation lists Linux as the operating system requirement, so FreeBSD is not a platform the project tests. The application itself is plain PHP and needs only Apache with mod_rewrite, MySQL 5.5.5 or newer (MariaDB works), PHP 7.1 or newer with the mysqli and exif extensions, and ImageMagick for thumbnails. All of that is available as FreeBSD packages. There is no Omeka package, so the application is installed from the official zip archive.

Requirements

  • A FreeBSD 15.1 or 14.5 server with root access over SSH. Commands are run as root; prefix them with sudo or doas if you use one of those.
  • A domain name such as example.com pointing to the server.

Bring the package catalogue and installed packages up to date first:

pkg update
pkg upgrade

Install Apache, MariaDB, PHP and ImageMagick

PHP 8.5 is the default PHP version in the FreeBSD ports tree, and Omeka Classic supports it since version 3.2.1. Install the web server, the database, PHP with the extensions Omeka uses, and the ImageMagick build without X11 dependencies:

pkg install apache24 mariadb118-server mariadb118-client \
  php85 mod_php85 php85-mysqli php85-exif php85-fileinfo php85-dom \
  php85-filter php85-ctype php85-iconv php85-mbstring php85-session \
  php85-simplexml php85-xml php85-zlib \
  ImageMagick7-nox11 unzip

The installer refuses to continue without mysqli, dom and filter, and warns when exif or fileinfo is missing: without them Omeka cannot read image metadata or validate the type of uploaded files.

Create a PHP configuration from the production template:

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

Collections usually contain large images and PDFs. Raise the upload limits in /usr/local/etc/php.ini to a size that suits your material, for example:

upload_max_filesize = 64M
post_max_size = 64M

Create the database

Enable and start MariaDB, then run the hardening script:

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

Open the MariaDB shell and create a database and a dedicated user. Omeka's installation notes ask for the utf8 character set with the utf8_unicode_ci collation. Use your own strong password:

mariadb -u root
CREATE DATABASE omeka CHARACTER SET utf8 COLLATE utf8_unicode_ci;
CREATE USER 'omeka'@'localhost' IDENTIFIED BY 'change-this-password';
GRANT ALL ON omeka.* TO 'omeka'@'localhost';
FLUSH PRIVILEGES;
EXIT;

Download Omeka Classic

Releases are published on omeka.org and on GitHub. Version 3.2.2 is a security and bug-fix release; check the download page for a newer one and adjust the version number:

cd /tmp
fetch https://github.com/omeka/Omeka/releases/download/v3.2.2/omeka-3.2.2.zip
unzip omeka-3.2.2.zip
mv omeka-3.2.2 /usr/local/www/omeka

Confirm that the hidden .htaccess file came along; Omeka's URL routing depends on it:

ls -la /usr/local/www/omeka/.htaccess

Edit /usr/local/www/omeka/db.ini and replace the XXXXXXX placeholders with your database settings. Leave prefix, charset and the commented port line as they are:

[database]
host     = "localhost"
username = "omeka"
password = "change-this-password"
dbname   = "omeka"
prefix   = "omeka_"
charset  = "utf8"
;port     = ""

Apache runs as the www user on FreeBSD. Keep the code owned by root and give the web server write access only to the files directory, where Omeka stores uploads and generated thumbnails. Restrict db.ini, since it holds the database password:

chown -R root:wheel /usr/local/www/omeka
chown -R www:www /usr/local/www/omeka/files
chown root:www /usr/local/www/omeka/db.ini
chmod 640 /usr/local/www/omeka/db.ini

Configure Apache

mod_rewrite is disabled in FreeBSD's default Apache configuration. Open /usr/local/etc/apache24/httpd.conf and remove the leading # from this line:

LoadModule rewrite_module libexec/apache24/mod_rewrite.so

Files ending in .conf in /usr/local/etc/apache24/Includes/ are loaded automatically. Create /usr/local/etc/apache24/Includes/php.conf so that Apache hands 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/omeka.conf. AllowOverride All is required so that Omeka's .htaccess rules, including the one that blocks web access to .ini files, take effect:

<VirtualHost *:80>
    ServerName example.com
    DocumentRoot "/usr/local/www/omeka"
    <Directory "/usr/local/www/omeka">
        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/. Omeka redirects to its installer at /install/ and first checks the requirements; a missing PHP extension or an unwritable files directory is reported there by name. Fill in the form:

  1. Username, password and email address of the superuser account.
  2. Site title and administrator email address.
  3. Optional settings such as the thumbnail sizes, which can be changed later.

Click Install. When it finishes, the page links to the public site and to the admin dashboard at http://example.com/admin.

Verify and finish the setup

  • Log in at /admin and open Settings. In the general settings, set ImageMagick Directory Path to /usr/local/bin and click Test; Omeka confirms that it can run ImageMagick.
  • Add an item with an image file. If thumbnails appear on the item page, uploads, file permissions and ImageMagick all work.
  • Confirm that the database settings are not reachable from the web: fetch -o /dev/null http://example.com/db.ini must fail with a 403 error.
  • Add HTTPS before you create real user accounts, for example with a Let's Encrypt certificate and Apache's mod_ssl, then update the Server URL value in the general settings if it does not match.

The basic package already contains the Exhibit Builder, Simple Pages and COinS plugins and three themes. Further plugins and themes are unpacked into the plugins and themes directories and activated in the admin dashboard.

Maintenance

Keep the stack patched with pkg upgrade. To upgrade Omeka itself, back up the database and the files directory, replace the application files with those of the new release while keeping your db.ini, files, plugins and themes, then log in to the admin dashboard and run the database upgrade it offers. Omeka's installation and system requirements pages describe the details.

mariadb-dump -u root omeka > /root/omeka-backup.sql
tar -czf /root/omeka-files.tar.gz -C /usr/local/www/omeka files

Frequently asked questions

What is the difference between Omeka Classic and Omeka S?

Omeka Classic runs one site per installation and is aimed at individual projects and exhibits. Omeka S is a separate application from the same team for institutions that manage many sites sharing one pool of items and linked-data vocabularies. They have different code bases, plugins (modules in Omeka S) and themes.

The admin pages return "File not found" errors. What is wrong?

The rewrite rules are not being applied. Check that mod_rewrite is loaded, that the virtual host has AllowOverride All and that .htaccess exists in the Omeka directory. If Omeka lives in a subdirectory next to another application, enabling the RewriteBase line in .htaccess can resolve the conflict.

Uploads fail or no thumbnails are created. Where do I look?

Make sure files and all of its subdirectories are owned by www, that the ImageMagick path test in the settings succeeds, and that the file is smaller than upload_max_filesize and post_max_size in php.ini. Restart Apache after changing PHP settings.

Can I use MySQL instead of MariaDB?

Yes. Omeka Classic 3.2 and later require MySQL 5.5.5 or newer, and FreeBSD packages current MySQL releases as well. The db.ini settings are the same.

Share story:

Continue reading other guides on How VPS.