Installing on Mac OS

Note

Note: these instructions have been tested on MacOS 10.14 (Mojave). They may or may not work on earlier versions of MacOS.

CollectiveAccess relies on a number of open-source software packages to run, such as MySQL (database server), PHP (programming lanaguage) and Apache or nginx (web server) to name just a few. The simplest way to install these required packages on Mac OS is to use the Homebrew package manager. Homebrew can be installed by opening a Mac OS Terminal window and pasting this command:

/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

Once installed most required software can be installed using the brew command.

Mac OS 10.14 comes with the Apache web server preinstalled. It’s tricky to get PHP installed by Homebrew to work with the preinstalled Apache though, so it’s best to use Homebrew-managed installation. Before we install Apache with Homebrew, first shutdown the preinstalled server and disable it from starting automatically in the future using these Terminal commands:

sudo apachectl stop
sudo launchctl unload -w /System/Library/LaunchDaemons/org.apache.httpd.plist 2>/dev/null

Now install Apache by typing in Terminal:

brew install httpd

Next, set Apache to start itself automatically every time you reboot the Mac:

sudo brew services start httpd

You should now be able to connect to the web server on port 8080 (the default when installing with Brew) by going to the URL http://localhost:8080 in a web browser running on the Mac. The message “It works!” should display.

Tip

If you want to run Apache on the standard port 80 you’ll need to open the Apache configuration file located at /usr/local/etc/httpd/httpd.conf, find the line Listen 8080 and change it to Listen 80. Then restart the server with the Terminal command sudo apachectl -k restart

Next install PHP version 7.4 running in the Terminal:

brew install php@7.4

Then edit the Apache configuration file located at /usr/local/etc/httpd/httpd.conf, adding the line:

LoadModule php7_module /opt/homebrew/opt/php@7.4/lib/httpd/modules/libphp7.so

where /opt/homebrew is the path to your Homebrew directory.

Tip

You can find your Homebrew directory path by running the command echo $(brew –prefix). It is often /opt/homebrew but may be different on some systems.

Next, look for this configuration in the Apache configuration file:

<IfModule dir_module>
    DirectoryIndex index.html
</IfModule>

and replace it with this:

<IfModule dir_module>
    DirectoryIndex index.php index.html
</IfModule>

<FilesMatch \.php$>
    SetHandler application/x-httpd-php
</FilesMatch>

Restart the server with the Terminal command sudo apachectl -k restart. You should now have PHP enabled within your Apache web server.

In order to use the PHP on the Terminal command line (which can be handy) you’ll need to add the Homebrew PHP installation directory into your command PATH. If you’re running the Bash shell enter in the Terminal:

echo 'export PATH="/usr/local/opt/php@7.4/bin:$PATH"' >> ~/.bash_profile
echo 'export PATH="/usr/local/opt/php@7.4/sbin:$PATH"' >> ~/.bash_profile

If you’re running the Zsh shell (the new default shell since Mac OS 10.14 aka. Catalina):

echo 'export PATH="/usr/local/opt/php@7.4/bin:$PATH"' >> ~/.zshrc
echo 'export PATH="/usr/local/opt/php@7.4/sbin:$PATH"' >> ~/.zshrc

Close the current Terminal window and open a new one. Typing php -v in the Terminal should return output similar to:

    PHP 7.4.21 (cli) (built: Jul 12 2021 03:04:54) ( NTS )
    Copyright (c) The PHP Group
    Zend Engine v3.4.0, Copyright (c) Zend Technologies
with Zend OPcache v7.4.21, Copyright (c), by Zend Technologies

Note that PHP 8 is not yet supported.

Now let’s install MySQL. CollectiveAccess works with version 5.7 or better. To install version 8.0:

brew install mysql

Then add the MySQL install to your command line path with (if you’re running Bash):

echo 'export PATH="/usr/local/opt/mysql/bin:$PATH"' >> ~/.bash_profile

If you’re running Zsh:

echo 'export PATH="/usr/local/opt/mysql/bin:$PATH"' >> ~/.zshrc

You will need to close the Terminal window and open a new one for the path changes to take effect. Next start up MySQL, and configure it to restart automatically on reboot:

brew services start mysql

If you don’t want MySQL starting up automatically every time you boot your machine you can start it up on demand using brew services run mysql

Next we install various packages to support processing of media: ffmpeg (audio/video), Ghostscript (PDFs), GraphicsMagick (images), mediainfo (metadata extraction and xpdf (content extraction from PDFs):

brew install ffmpeg ghostscript GraphicsMagick mediainfo xpdf

Finally, we are ready to install the CollectiveAccess Providence back-end cataloguing application. The web server we installed earlier uses /opt/homebrew/var/www for documents by default (the “web server root” directory). We are going to place CollectiveAccess in this directory, in a subdirectory named ca. A URL for this directory will be http://localhost:8080/ca (assuming that you’re still running on port 8080). If you’re running on port 80, the URL will be http://localhost/ca.

Tip

Some systems may use a directory other than /opt/homebrew. You can verify the Homebrew directory path on your system by running the command echo $(brew –prefix).

Tip

You can use a different directory for the application by editing /usr/local/etc/httpd/httpd.conf. Edit the line DocumentRoot “/usr/local/var/www” to point to your chosen directory.

You can download a release from https://github.com/collectiveaccess/providence/releases, or install is with Git. Using a release in somewhat simpler to install, while using Git allows you to easily update files and switch to development versions of CollectiveAccess.

To install with Git, in the Terminal change directory into the web server root directory.

cd /opt/homebrew/var/www

(Assuming your Homebrew path is /opt/homebrew) Then “clone” the Providence application code from GitHub:

git clone https://github.com/collectiveaccess/providence.git ca

If you prefer to download a release, place the release ZIP or tgz file downloaded from https://github.com/collectiveaccess/providence/releases into /usr/local/var/www and uncompress it. Then rename the resulting directory (named something like providence-1.7.12) to ca.

In the Terminal change directory into the ca application directory and copy the setup.php-dist file to setup.php. This file contains basic configuration for Providence. The “-dist” version is simply a template. The setup.php copy will need to be customized for your installation:

cd  /usr/local/var/www/ca
cp setup.php-dist setup.php

Edit setup.php, changing settings to suit. At a minimum you will need to edit the database login settings __CA_DB_USER__, __CA_DB_PASSWORD__, __CA_DB_DATABASE__. You may want to edit other settings, which are described in setup.php. You should also edit the __CA_STACKTRACE_ON_EXCEPTION__ to be true. This will allow you to receive full error messages on screen if something goes wrong.

By default brew installs the MySQL database with an all-access, password-less administrative account named root. It’s generally insecure to leave this account password-less, but in a testing environment this may not matter. If you decide to use the root account, set __CA_DB_USER__ to “root”, leave __CA_DB_PASSWORD__ blank and set __CA_DB_DATABASE__ to the name you’ll use for your database. For this example, we’ll assume the database is to be named my_archive.

MySQL can support multiple databases in a single installation, so the my_archive database must be created explicitly. Log into mysql in the Terminal using the mysql command (assuming you haven’t set a password for the root account):

mysql -uroot

At the mysql> prompt enter:

CREATE DATABASE my_archive;

If you want to use a MySQL login specific to the newly created database, while still at the mysql> prompt enter:

GRANT ALL on my_archive.* to my_user@localhost identified by 'my_password';

where my_user is your preferred MySQL user name and my_password is your preferred password for the MySQL login. MySQL logins are specific to MySQL and have nothing to do with your server login. You can set the user name and password to whatever you want, independent of all other login credentials.

Go back to setup.php and enter your MySQL login credentials into the __CA_DB_USER__, __CA_DB_PASSWORD__ and __CA_DB_DATABASE__ settings.

Restart the server with the Terminal command:

sudo apachectl -k restart

Certain directories in the installation need to be writeable by the web server, within which CA runs. On MacOS, the web server typically runs as the user www. Change the permissions on the app/tmp, app/log, media and vendor directories to be writeable by www in Terminal:

cd  /usr/local/var/www/ca
sudo chown -R www app/tmp app/log media vendor
sudo chmod -R 755 app/tmp app/log media vendor

The first sudo command will require entry of your MacOS login password.

Navigate in a web browser to http://localhost:8080/ca (adjusting the port to whatever you have configured, if necessary). You should see:

Click on the installer link and you should see:

Select a profile, enter your email address and click on Begin installation. A profile is a preset template with record types, fields and other cataloguing settings that the installer uses to define a new working system. The standard profiles Providence ships with include implementations of widely used standards:

You can add your own profiles, or use profiles from other users by dropping profile files in the /usr/local/var/www/ca/install/profiles/xml directory.

If you want to experiment with different profiles you may wish to set the __CA_ALLOW_INSTALLER_TO_OVERWRITE_EXISTING_INSTALLS__ option in setup.php. By default the installer will refuse to install over an existing installation. With __CA_ALLOW_INSTALLER_TO_OVERWRITE_EXISTING_INSTALLS__ set the installer will include an option to overwrite existing data. In a real system this is extremely dangerous – any one with access to the installer can delete the entire system – but is very handy for testing and evaluation.