Install Specify 6 on macOS

Specify 6 requires Amazon Corretto 8 as a Java Runtime Environment and MariaDB as database management software to operate. This guide will walk you through how to install these to use Specify 6 on macOS.

This installation walkthrough documentation is intended for standalone macOS workstations ‐ desktop computers which are managed by the Specify user and which are not intended to be used as a database server to provide shared collection data access to additional computers running Specify. To install the necessary software, one must have a macOS administrator‐level account or have been granted software installation privileges on the target computer. If your campus or organization’s IT or network services group manages security and accounts for individual workstations, your user account on your Mac may not have admin level privileges, which are required to complete this installation. Check with your local IT or network support staff if you need to have your admin level status verified for your Mac workstation or laptop.

If your building, administrative unit, or campus manages MySQL or MariaDB for shared access on a server computer, the stand-alone workstation MariaDB installation steps described below are not suitable for your situation. For multi‐user, shared‐server access to a MySQL/MariaDB Specify 6 database, talk to your technical support staff, database or network administrator about MySQL installation and configuration options. Contact the Specify Collections Consortium (support@specifysoftware.org) if you would like to know more about institutional installation and configuration options for shared access to Specify collection databases.

This guide was written with macOS Monterey 12.1, however these instructions should work on all recent macOS installations.

macOS Installation Checklist

  1. Confirm that your Mac user account is a member of the Mac Admin User Group.
  2. Install Homebrew using the Terminal application.
  3. Install Mariadb from the command line interface in Terminal.
  4. Reboot.
  5. Install Amazon Corretto 8 (if you are using an M1+ (Apple Silicon), you need to use the x64 version with Specify)
  6. Download the Specify installer package for macOS from the Specify Collections Consortium web site (https://www.specifysoftware.org/join/download/).
  7. Run the Specify Installer.
  8. Run the Specify Collection Setup Wizard.
  9. Run Specify with the Specify user account which was created while running the Setup Wizard.
  10. Modify your SpBackupRestore program to include the proper paths.

Step 1: Install Homebrew

Open the Terminal Application.

Type in the terminal

xcode-select --install

Then press enter. You’ll be prompted to enter the admin password to start the installation, then to accept the software license to install Xcode’s Command Line Developer Tools. This process will happen automatically.

This will install the necessary components to install Homebrew, and finally MariaDB.

In your web browser, navigate to brew.sh. Copy and paste the following command from their website into your Terminal application:


/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

Press Enter. You will be prompted to enter your password during this installation; however, your keystrokes will not appear in the terminal. This is an intended security feature. Type your password as normal and press enter.

Type the letter y for yes when prompted and press enter.

Homebrew is now installed on your machine!

Step 2: Install MariaDB

Continue using the Terminal Application.

Type in the terminal

brew install mariadb

Then press enter. This process will install mariadb on your system.

Follow MariaDB’s instructions to install.

For the most recent instructions, go to MariaDB’s website: Installing MariaDB Server on macOS Using Homebrew - MariaDB Knowledge Base

Start your server by using the command:

mysql.server start

To have your server auto-start when the machine boots up, use the command:

brew services start mariadb

After MariaDB has been started, just use the command:

mysql or mariadb

The MariaDB monitor should appear in your terminal:

MariaDB [(none)]>

Once you see the interface, use this command to create your new IT user. Use the command:

ALTER USER 'root'@'localhost' IDENTIFIED BY 'new_password';

In this case, root is the IT username and new_password would be your IT password. Only modify the password portion to create your own.

Note: MariaDB is a drop-in replacement for MySQL, meaning that mysql commands are symbolically linked. In other documentation, any reference to MySQL should be directed to your installation of MariaDB.

Step 3: Reboot

Reboot your system! Your MariaDB database should automatically start up if configured to in Step 2, otherwise start it with this command in terminal:

mysql.server start

Step 4: Install Amazon Corretto 8

Specify requires the Java Runtime Environment from Amazon known as Amazon “Corretto”. Amazon Corretto 8 is a 100% compatible JRE package based on the same source code as Oracle’s JRE, and Amazon has committed to licensing Corretto at no cost and to keep it updated, indefinitely.

If you are using an M1+ (Apple Silicon), you need to use the Intel/x64 version with Specify

Navigate to this URL to download the latest version of Corretto 8:

https://corretto.aws/downloads/latest/amazon-corretto-8-x64-macos-jdk.pkg

Follow the standard installation path until you are finished. Once it tells you that the installation was successful, you are ready to go.

Step 5: Download & Install Specify

Download and run the Specify installer for macOS. See the Specify Software Project web site Download page for the Specify installers and additional documentation:

http://specifysoftware.org/content/download

Step 6: Run the Specify Setup Wizard

Run the Specify Collection Setup Wizard to set up your collection. Put MariaDB root user or “IT User” account credentials in the “IT User” and “IT Password” fields. By default, username and password are “root”. Specify Wizard would use this account to set up an empty Specify database for your collection.

It is very important that you read the Specify Wizard documentation before running the Wizard. There are several options during collection database setup which require informed decisions about how your collection and institution are organized administratively.

See the step‐by‐step guide for using the Specify Wizard is available here:

Use the Specify user account name and password you created in the Setup Wizard, not the MariaDB account credentials. See additional documentation on setting up a Specify account user encryption key using the Specify Master user, account name and password. Please email or call the Specify Project if you get stuck, this is a complex process the first time through, we would be glad to help.

The above screenshot is the correct configuration.

SpBackupRestore needs to know the location of your mysql and mysqldump executables. The default paths point to MySQL executables. If, instead, you installed MariaDB using Homebrew, replace the default paths with the following two:

mysqldump:

/opt/homebrew/opt/mariadb/bin/mariadb-dump

mysql:

/opt/homebrew/opt/mariadb/bin/mariadb

Now you should be ready to backup and restore your database without issue.

Troubleshooting

If you are having trouble setting the root password on macOS, you can use the following command to reset your password:

sudo $(brew --prefix mariadb)/bin/mysqladmin -u root NEWPASS

You will need to enter your admin password and change NEWPASS to your chosen root password.


Legacy Instructions: Installing MySQL and Specify 6 on Mac OS X