The Full-Stack Developers’ Setup for MacOS Monterey

The Full-Stack Developers’ Setup for macOS Monterey

Know the tools to configure your development environment

The main idea behind this article is to make a clear path for a developer that wants to install/configure all the needed tools for full-stack development. Some of the steps on this guide will be specific for Drupal development but these will be pointed out just in case anyone is interested.

1. Mandatory

As developers we will need to install the following tools; Xcode, brew, git, curl, vim, and nvm.

Xcode is a package that provides some very useful command-line tools for developers like git or gcc.

Homebrew is a package manager that makes the process of setting up much quicker and easier. With the use of HomeBrew we can install some other important tools like vim(to edit files), git(so that versions are correctly managed), and curl(for installing installed).

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

brew install vim
brew install git
brew install curl

All developers need a text editor so installing one is very important. Atom and sublime are good choices but I use Visual Studio Code. At the end of the article, I will write about some useful extensions for VSC. For the choice of the terminal, we have Hyper, iTerm2, or regular terminal, but in this guide, we will be using iTerm.

brew install --cask iterm2
brew install --cask visual-studio-code

After installing Visual Studio Code run the application and inside press CMD+SHIFT+P and search for install code command in path. By clicking on this option we enable the use of VSC through the terminal as we will be using on this guide.

2. Node

We will use nvm for the installation of Node, after installing nvm follow the information given my brew info to install Node.

brew install nvm 
brew info nvm
nvm install 12.11.1 #Node version of choice

3. Apache

We will start to use httpd from brew but first, we need to stop apachectl and unload it by using the following commands:

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

Then we use brew to install httpd, after installation there are some useful commands that we need to know like start, stop, restart, and getting error log.

brew install httpd
brew services start httpd
brew services stop httpd
brew services restart httpd
tail -f /usr/local/var/log/httpd/error_log

After installation we need to config some files, for this, we will use visual studio so we recommend having done the setup for that part. If not any text editor will do just fine.

code /usr/local/etc/httpd/httpd.conf

Find the line that says Listen 8080 and change it to Listen 80.

Next, we change the DocumentRoot from /usr/local/var/www to /Users/your_user/Sites and just the same change for the directory tag just below.

Then we change AllowOverride from None to All and uncomment rewrite_module enabling it.

We will change User and Group lines so that we don’t get permission problems in the future. Change User for your_user and Group for staff.

ServerName line also needs to be uncommented and the value should be localhost.

For the next steps, we will need to create a Sites folder where all of our sites will be stored. mkdir ~/Sites. After this, we will make an index.html file and write a simple line to test if everything works fine. Also, remember to restart httpd.

echo “<h1> Apache config works!</h1>” > ~/Sites/index.html
brew services stop httpd
brew services start httpd

Tip: if it does not work double-check the user.

4. Database

As our DB We are using MariaDB, which is basically MySQL but with an easier installation via brew. Run the following:

brew update
brew install mariadb
brew services start mariadb

Now we will change the MySQL server password, on the following process press enter for every option until it asks for a password where I would suggest using something easy like root.

sudo /usr/local/bin/mysql_secure_installation

After installing MySQL it is recommended to install an interface to interact with the databases, there are a couple of good choices like TablePlus or Sequel Pro. In this case, I will be using TablePlus.

brew install — cask tableplus
OR
brew install — cask sequel-pro

If Mac does not trust any of them go to system preferences>security and privacy and click the Open Anyway button in the General pane to confirm your intent to open or install the app.

When installed just create a new connection with any name and leave the settings as default changing the password to the one used on the previous process like for example root.

If we need to stop mariadb just run:

brew services stop mariadb

5. PHP

As brew has depreciated some versions of PHP we will use the tap from shivammathur for the PHP installation.

brew tap shivammathur/php

Installing different PHP versions so that we can switch between each one:

brew install shivammathur/php/php@7.1
brew install shivammathur/php/php@7.2
brew install shivammathur/php/php@7.3
brew install shivammathur/php/php@7.4
brew install shivammathur/php/php@8.0

At this moment it is recommended to shut down the terminal so that every configuration gets updated.

Now we will link the PHP version required if there is already a version installed run:

brew unlink php && brew link — overwrite — force php@7.4

Otherwise:

brew link — overwrite — force php@7.4

When linking a message with two echo commands will pop up, copy and paste them. After that just use php -v to check the PHP version installed.

We already have PHP installed but we need to config apache too for PHP.

We edit again the httpd file with the same command.

code /usr/local/etc/httpd/httpd.conf

Find ‘mod_rewrite’ module and add the following modules below:

#LoadModule php7_module /opt/homebrew/opt/php@7.1/lib/httpd/modules/libphp7.so
#LoadModule php7_module /opt/homebrew/opt/php@7.2/lib/httpd/modules/libphp7.so
#LoadModule php7_module /opt/homebrew/opt/php@7.3/lib/httpd/modules/libphp7.so
LoadModule php7_module /opt/homebrew/opt/php@7.4/lib/httpd/modules/libphp7.so
#LoadModule php_module /opt/homebrew/opt/php@8.0/lib/httpd/modules/libphp.so

Leave uncommented just the module corresponding to the version of PHP currently used, in this case, we will use 7.4.

Directory indexes are currently just for HTML so we need to update them to PHP. Search for:

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

And change it for :

<IfModule dir_module>
DirectoryIndex index.php index.html
</IfModule>
<FilesMatch .php$>
SetHandler application/x-httpd-php
</FilesMatch>

Finally uncomment deflate module line.

LoadModule deflate_module lib/httpd/modules/mod_deflate.so

At this point restart httpd with brew. We will now check if everything is correct up until now. Using a PHP function, phpinfo(); we can check the PHP version apache is getting. After doing the echo command go to localhost/info.php and you will see the PHP version you are running.

echo “<?php phpinfo();” > ~/Sites/info.php

Some nice developer created a script to switch between PHP mandatory versions, this is not but will save some time if more than one PHP version is required:

curl -L https://gist.githubusercontent.com/rhukster/f4c04f1bf59e0b74e335ee5d186a98e2/raw/adc8c149876bff14a33e3ac351588fdbe8172c07/sphp.sh > /opt/homebrew/bin/sphp
chmod +x /opt/homebrew/bin/sphp

After downloading, it is very easy to use just run sphp and the PHP version needed. In the following example, we will change to PHP 7.3.

sphp 7.3

After everything do a brew update and brew updgrade . This should be it. If anything is not working it is probably because of the need for an httpd restart.

6. Virtual Hosts

In this part, we will configure an already existing functionality from apache called virtual hosting which allows having multiple sites to test at the same time. For this Dnsmasq will be used, which we will talk about later.

Start by editing the previous file by :

code /opt/homebrew/etc/httpd/httpd.conf

Find and uncomment the following lines :

LoadModule vhost_alias_module lib/httpd/modules/mod_vhost_alias.so
# Virtual hosts
Include /opt/homebrew/etc/httpd/extra/httpd-vhosts.conf

The next and final step is to configure the vhosts file:

code /opt/homebrew/etc/httpd/extra/httpd-vhosts.conf

In this file, we basically tell apache where to find the different index files as well as the server alias we will be using. I would suggest commenting on the previous configuration.

For my configuration, I use Drupal so it is a bit more complex but I will showcase both Drupal and regular configurations:

Drupal:

<VirtualHost *:80>
ServerName test
ServerAlias *.test
VirtualDocumentRoot /Users/your_user/Sites/site_directory/docroot
ErrorLog “/private/var/log/apache2/site_directory.local-error_log”
CustomLog “/private/var/log/apache2/site_directory.local-access_log” common
<Directory “/Users/your_user/Sites/site_directory/docroot”>
AllowOverride All
Require all granted
Options FollowSymLinks
</Directory>
</VirtualHost>

Other:

<VirtualHost *:80>
DocumentRoot “/Users/your_user/Sites/your_folder”
ServerName *.test
</VirtualHost>

Check you are using the same user we used before in the config file. Your_folder would be the folder where the index files will be stored.

7. Dnsmasq

Dnsmasq, as mentioned before, will help us change the host dynamically. For this guide, we will be using .test as the domain. Let’s start by installing it.

brew install dnsmasq

We edit the configuration file by using:

echo ‘address=/.test/127.0.0.1’ > /opt/homebrew/etc/dnsmasq.conf

Now we only have to start it and add it to the resolvers:

sudo brew services start dnsmasq
sudo mkdir -v /etc/resolver
sudo bash -c ‘echo “nameserver 127.0.0.1” > /etc/resolver/test’

You can try if it is correctly setup by pinging any .test domain like test.test

ping test.test
Correct ping result

If the ping works congrats, you have finished configuring your environment!

8. Xdebug

Xdebug is a really useful tool used to debug PHP code which we will be using with Visual Studio Code to make web development a lot easier. The only problem is that there is no universal version of Xdebug for PHP, there are a couple of versions depending on the PHP version. Considering PHP 7.1+ there are two Xdebug versions available.

For PHP 7.1:

sphp 7.1
pecl uninstall -r xdebug
pecl install xdebug-2.9.8

For PHP 7.2+:

sphp 7.2
pecl uninstall -r xdebug
pecl install xdebug

Now let’s configure xdebug so it works properly. Firstly we will remove the zend_extension=”xdebug.so” line in php.ini file. I will use php version 7.4 but it is the same for every. Just remember if you change versions in the future this step will need to be repeated.

code /opt/homebrew/etc/php/7.4/php.ini

Create a new config file to config xdebug:

code /opt/homebrew/etc/php/7.4/conf.d/ext-xdebug.ini

Paste the following configuration depending on the PHP version.

Previous to 7.2:

[xdebug]
zend_extension=”xdebug.so”
xdebug.remote_enable=1
xdebug.remote_host=localhost
xdebug.remote_handler=dbgp
xdebug.remote_port=9000

Post 7.2

[xdebug]
zend_extension="xdebug.so"
xdebug.mode=debug
xdebug.start_with_request = yes
xdebug.client_port = 9003 #Depending on the VSC configuration
xdebug.idekey = VSCODE #Only needed if you are using VSC

Restart httpd and check again php.info page, you should find Xdebug in the correct version on the info page.

To finish the VSC configuration go to the VSC part where we will see all of the different steps to setup the application.

9. Key generation (ssh)

If you want to work with git repos or any other ssh key tool demanding to create a public and private key following the next steps.

Create the key with ssh-keygen -t rsa . In the generation process, it will ask for a location, press enter to use the default location

For the paraphrase you can press enter or type something depending on the security you want to have, I usually leave it empty.

The private key will be stored in the .ssh folder under id_rsa while the public one will be named id_rsa.pub. This last one is the one we are going to copy and use.

Use the following command to copy the public key to your clipboard and paste it where needed.

pbcopy < ~/.ssh/id_rsa.pub

10. Custom Tweaks

1. Visual Studio Code

For VSC there are some useful customisations as well as some mandatory steps if you want to follow the Xdebug guide.

  • Xdebug — First of all, to make Xdebug work on VSC you need to install the PHP Debug extension. After this go to the run and debug part in VSC and click on generate a new launch.json. You should check the port is the same as the one configured in Xdebug. This file should look something like this:

To make it possible to add breakpoints everywhere go to Code>Prerences>Settings and type breakpoints. Check Allow setting breakpoints in any file.

  • Useful extensions: Beautify, Bracket Pair Colorizer, Drupal Syntax Highlighting (Only if using Drupal), ESLint, Git history, GitLens, Highlight Matching Tag, Prettier — Code formatter, Rainbow Brackets, Stylelint

2. Shell

Use the following command to show hidden files in the finder and terminal.

defaults write com.apple.Finder AppleShowAllFiles true

Go to Iterm2>Install Shell Integration

After this, the only thing left would be to make the terminal more appealing. The following links are different ways of achieving this, choose your favorite.

  • https://github.com/mathiasbynens/dotfiles
  • https://github.com/ohmyzsh/ohmyzsh


The Full-Stack Developers’ Setup for MacOS Monterey was originally published in Better Programming on Medium, where people are continuing the conversation by highlighting and responding to this story.

Leave a Comment