FW System Setup - Mac OS

This documentation is old, it was updated in some aspects to account for changes to PHP 8.2, but I personally haven't used Mac or tested this, nor have we had any Mac developers in several years, so it may have some steps that are outdated. It will hopefully get you generally in the ballpark, however. It is recommended that you use Windows to develop the FW System, as much of our other documentation is made for Windows

Install NVM, NPM, Yarn, Gulp, Box, and Configure Git

Open up a terminal window. The terminal program can be found in the "Utilities" folder in applications
Make sure you have NVM installed. Run curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.33.11/install.sh | bash
Run nvm install node
Run npm i -g yarn gulp gulp-cli
Run the following commands and replace bracketed items with the appropriate information

git config --global user.name "[firstname] [lastname]"
git config --global user.email "[email]"
git config --global credential.helper 'store'

Navigate to where you want to place the folder for all this in the terminal and run mkdir webroot webroot/fw-dev webroot/bin
Download the most recent Box version's box.phar file, from here, and put it in your webroot/bin folder.

Install and Configure PHP and Composer

Run /usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)" to install homebrew
Use Homebrew to install PHP 8.2 (as PHP does not come installed by default on Mac Systems anymore), by running brew install php@8.2
Determine where your php.ini file is being run from, by using the following command: php -r "phpinfo()" | grep php.ini. It will give output like the following:

Configuration File (php.ini) Path => /usr/local/etc/php/8.2
Loaded Configuration File => /usr/local/etc/php/8.2/php.ini

Note where your Configuration File is loaded from (in case it is different from the default /usr/local/etc/php/8.2)

You will need to edit the php.ini file by using the command sudo nano /etc/php/8.2/php.ini (skip the usr/local/ part of the path, but this hasn't been tested, if this doesn't work, try the full path sudo nano /usr/local/etc/php/8.2). (Note: Additionally, you can use any terminal editor, such as vim, but many prefer nano). Edit the following things:
- Press control W (yes, control, not command) and search for readonly. Delete the semi-colon in front of the line phar.readonly = On and change it to phar.readonly = Off
- Search for intl, and ensure that the line extension=intl is uncommented (no semi-colon)
- Search for zip, and ensure that the line extension=zip is uncommented.
- Press control O and then return to save and then press control X to exist
Use Homebrew to install Composer, by running brew install composer
Edit your paths to include the bin folder you created a few steps ago by running sudo nano /etc/paths and add a new line with the path to the bin folder.
- Note: the path to the bin folder will be different depending on where you have placed your webroot and bin folders, but in our example the path would be Users/jddocea/Documents/devProjects/webroot/bin.
- Also Note: You may need to also add the php path you found earlier as well, since in the past couple of years Mac stopped automatic install of php. (you can test if php works by running php --version in the terminal. If it is not recognized, also add the php path to this document as well)

Setup Bitbucket and FW System

Download the fw.phar file here, and place it in the webroot/bin folder.
Make a Bitbucket account here and make sure you have access to the Library Informatics Workspace from a Informatics Admin.
Bitbucket is no longer allowing users to use their Atlassian passwords for Git authentication, which means you need to create an app password for this. Create an App Password by Clicking your picture in Bitbucket, clicking Personal Settings, then click App Passwords. When you Add a Password, use the following settings:

Note: Make sure to copy the password before you close the box because you won't see the password again. If you need it again, just make another Git Password the same way.

Now that you have a Bitbucket account, go into your fw-dev folder by typing cd fw-dev and login to your Bitbucket account with fw login bitbucket, using your username and App Password you just created.
Setup the FW System by running fw setup.
Install Group Control by using fw install gc. Note: If you get Task 'Download' Failed, it means your Bitbucket credentials did not work. Ensure you used your correct username and app password.
For the first two prompts press enter. For the third prompt, also press enter, and then after hitting enter, you will need to find the Passwords entry with the credentials for your personal database. It should be called bennerlib_[yourOlivetUsername], if you don't have this take to an Informatics Administrator for them to make you a database. Enter the correct database credentials from the Passwords entry as prompted.

Note: If you get a Database migration failed, you did not correctly enter your database credentials, and you will need to double check that you didn't mistype anything for your database credentials by checking the file webroot/fw-dev/config/local.php.

Configure Apache

Mac comes with Apache 2.4 preinstalled, so all you need to do is configure it, rather than to install it.

Run sudo nano /etc/apache2/httpd.conf to edit some lines needed for setup (this may have been moved to etc/httpd/httpd)
- Press control W and search for php. Then make sure to uncomment the line which begins with LoadModule php_module (it could be called LoadModule php8_module as well, this step has adjusted since we changed from PHP 7, and hasn't been tested).
- Press control W again and search for vhosts. Uncomment the line Include /private/etc/apache2/extra/httpd-vhosts.conf (by removing # in front of the line)
- Add a new line underneath the line you just uncommented: Include /private/etc/apache2/vhosts/*.conf. (This is going to be a reference folder we will make so that the vhosts for the FW Apps are separate and easier to read)
- Press control W again and search for user_www. Comment out the lines User_www and Group_www by adding a # in front of each line.
- Add 2 new lines: User [yourMacUserName] and Group staff
- Press Control O and enter to save and Control X to exit.
Run sudo mkdir /etc/apache2/vhosts to add the folder alluded to above.
Run sudo nano /etc/apache2/vhosts/fwApps.conf to create a file where we will store our vhosts. Then add the following chunk of code. Notes: the path will be different depending on where you place the webroot folder. The ServerName can be changed to whatever is convenient for you (This is the web address you will be typing in to see your current development environment and changes to the apps).

<VirtualHost *:80>
        ServerName fw.localhost.com
             DocumentRoot "/Users/[macUserName]/webroot/fw-dev/public"
                    <Directory "/Users/[macUserName]/webroot/fw-dev/public">
                           Options Indexes FollowSymLinks
                           AllowOverride None
                           Require all granted
                   </Directory>
</VirtualHost>

Press control O and enter to save and control X to exit the file

Run sudo nano /etc/hosts to edit this file. Add the line: 127.0.0.1 fw.localhost.com (or whatever you put as the ServerName in fwApps.conf). Press control O and enter to save and control X to exit the file.
Run sudo apachectl restart (this is the command that you use to start your apache server, and it is a good idea to run this at the beginning of every dev shift).
Open your web browser and go to address fw.localhost.com (or whatever you put down as the ServerName). Click GC and login to GC with username "admin" and password "password". If you successfully login, you have done everything successfully!

Installing Other Apps

You have successfully completed the FW Installation process. Make sure to follow our other guides to install apps for development or for production.