FW System Setup - Mac OS

This documentation may be incomplete, but it is now in a much better state than it used to be. Windows is still what most developers use for developing in the FW System, but MacOS should also be doable.

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 nvm --version to check). If it's not installed go to the nvm GitHub repository install instructions and run either the cURL or wget command listed.
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 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" to install homebrew
- Note: This guide will refer to the default install location for software installed with Homebrew. This guide specifically will always use the location used on M1 or later Macs, which is /opt/homebrew. If you are on an older Intel Mac, the instructions shouldn't change except that the default location should be /usr/local.
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
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)
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 (since you installed using brew, it will likely be in /opt/homebrew).

You will need to edit the php.ini file by using the command sudo nano /etc/php/8.2/php.ini (replace the path wth the "Loaded Configuration File" from the previous step). (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 error_reporting= and ensure that the line reads error_reporting=E_ALL & ~E_DEPRECATED & ~E_STRICT.
- Note: The following 2 lines (intl and zip extensions) may not need to be uncommented. Try re-commenting them if you are running into PHP errors.
- 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
Install Composer. Go to the Composer download page, scroll down to version 2.5.4 and download it.
- Note: It is possible in the future that you can download the latest version. For now, the latest version can cause issues with our setup so it's best to use 2.5.4 which we know for certain works.
- You will need to make the file executable, move it somewhere in your path, and ensure that it is just called composer. An example of this would look like: chmod +x ~/Downloads/composer.phar && sudo mv ~/Downloads/composer.phar /usr/local/bin/composer.

Setup Bitbucket and FW System

Download the fw.phar file here, and place it in the webroot/bin folder.
- Rename the file to just fw and make it executable (chmod +x fw 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.

Remove Built-in Apache and Install with Homebrew

We have run into issues using the built-in version of Apache, possibly due to needing to sign PHP when used in conjunction with Apache. To mitigate this issue, we will disable the built-in version of Apache and install it with Homebrew instead.

Stop Apache by running sudo launchctl unload -w /System/Library/LaunchDaemons/org.apache.httpd.plist.
- You may need to restart your computer for this change to take place. Test if Apache is running by running sudo lsof -i:80. If there is no output, that means Apache was successfully disabled.
Next, install httpd (Apache) with Homebrew: brew install httpd.
- Run brew services start httpd to start the service. You will use this command, along with brew services stop httpd and brew services restart httpd to control the Apache service.
- To test that it is running, run sudo lsof -i:8080. As long as there is some output you should be good.
- Make sure that you are using the correct httpd. Run which httpd to check:
  - If the output is /usr/sbin/httpd, you are still using the default installed version. Restart your computer and see if that resolves.
Configure httpd (nano /opt/homebrew/etc/httpd/httpd.conf):
- Near the top of the file, change Listen 8080 to Listen 80.
- Press control W and search for php. Then make sure to uncomment the line which begins with LoadModule php_module, if it exists.
  - Note: It is very likely (maybe certain?) that no such line exists. If that is the case, you'll just need to add it pointing to the correct file. This will be /opt/homebrew/opt/php@8.2/lib/httpd/modules/libphp.so for ARM Macs.
- 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)
  - Note: The path listed above is probably not what you will see.
- Add a new line underneath the line you just uncommented: Include /private/etc/apache2/vhosts/*.conf.
  - Note: Replace the path so that it lines up with the one that you just uncommented.
  - 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 (take note that there is a space there). 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 (right below the lines you just commented out).
- 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 (once again, the path listed here is just a placeholder).
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 brew services restart httpd (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.