{dev_notes}

XAMPP

Published 3 years ago.
Last updated

XAMPP is a completely free, easy to install Apache distribution containing MariaDB, PHP, and Perl. The XAMPP open source package has been set up to be incredibly easy to install and to use.

Privileges

An account with admin access is required to install and configure XAMPP on Mac. This does not mean running as an administrator account, but it does mean having access to one so you can “elevate privileges” when needed. In UI situations Mac will ask for the admin account name and password. In the command line, you will need to switch users su <username> to an admin user temporarily for some tasks.

Install XAMPP

  • Download XAMPP from apachefriends.org.
  • Install the app. Be patient, it can take a little time.

  • Navigate to http://localhost/ to test the installation. If all went well you should see the XAMP start page.

Setup Virtual Hosts

Virtual host or vhost setup in XAMPP on Mac requires editing three files:

  • /Applications/XAMPP/xamppfiles/etc/httpd.conf
  • /Applications/XAMPP/xamppfiles/etc/extra/httpd-vhosts.conf
  • /etc/hosts

httpd.conf file

  • Open /Applications/XAMPP/xamppfiles/etc/httpd.conf for editing.
  • Search the file for Virtual hosts. We are looking for: #Include etc/extra/httpd-vhosts.conf.
  • Uncomment the line (remove the #) so the line reads: Include etc/extra/httpd-vhosts.conf. This tells Apache to load the custom httpd–vhosts.conf configuration file.
  • Save and close the file.

httpd-vhosts.conf file

All XAMPP virtual hosts are defined in the httpd-vhosts.conf file.

  • Open /Applications/XAMPP/xamppfiles/etc/extra/httpd–vhosts.conf for editing.
  • Remove or comment-out the example hosts entries.

Preserve localhost

The first step is to preserve the localhost domain. It will be setup to simply serve the default XAMPP start page.

  • Make a virtual host entry for localhost in the httpd-vhosts.conf file:
# Retain the XAMPP page at `localhost`.
<VirtualHost *:80>
    ServerName localhost
    DocumentRoot "/Applications/XAMPP/xamppfiles/htdocs"
</VirtualHost>

Add custom virtual hosts

Any number of custom virtual host definitions can be added under the localhost entry:

# My Custom Virtual Host
<VirtualHost *:80>
    ServerName local.myhost.com
    DocumentRoot "/Users/dwatts/Projects/myhost/repo/public_html"
    <Directory "/Users/dwatts/Projects/myhost/repo/public_html">
        Require all granted
    </Directory>
</VirtualHost>

# My Other Custom Virtual Host
<VirtualHost *:80>
    ServerName local.myotherhost.com
    DocumentRoot "/Users/dwatts/projects/myotherhost/repo/public_html"
    <Directory "/Users/dwatts/projects/myotherhost/repo/public_html">
        Require all granted
    </Directory>
</VirtualHost>

hosts file

Local virtual hosts must have their host name defined in the hosts file in the /etc directory.
/etc is a special hidden directory on Mac and can only be edited by users with admin permissions.

  • Open Terminal.
  • Switch to an account with admin permissions: su <my admin username>. You will be asked for the accounts password.
  • Now use sudo to open the hosts file with nano for editing: sudo nano /etc/hosts.

  • Add a line to the bottom of the file with the local IP address and the virtual host name: 127.0.0.1 local.myhost.com.

The complete file with the new line might look something like this:

##
# Host Database
#
# localhost is used to configure the loopback interface
# when the system is booting.  Do not change this entry.
##
127.0.0.1   localhost
255.255.255.255 broadcasthost
::1             localhost
127.0.0.1   local.myhost.com

To save and exit nano:

  • Press CTR + X to start the exit.
  • Press Y to save changes.
  • Press return to use the same file name and exit.

Restart XAMPP Apache

After editing any of the configuration files in XAMPP, XAMPP/Apache must be restarted. Use the XAMPP UI to restart.

You should now be able to visit the new virtual host in a browser at http://local.myhost.com.

MySQL

XAMPP installs MariaDB at /Applications/xampp/xamppfiles/bin/mysql.

CLI Access

Use the full path to the XAMPP mysql instance to login on the command line:

/Applications/xampp/xamppfiles/bin/mysql -u root -p

Enter the root users password at the prompt to enter mysql:

Enter password: 
Welcome to the MariaDB monitor.  Commands end with ; or \g.
Your MariaDB connection id is 464
Server version: 10.4.14-MariaDB Source distribution

Copyright (c) 2000, 2018, Oracle, MariaDB Corporation Ab and others.

Type 'help;' or '\h' for help. Type '\c' to clear the current input statement.

MariaDB [(none)]>

Root Access

Some commands require the user has root access. On MacOS, on the command line, the current account must have administrative rights to use the sudo command. If the current user does not have admin rights, then change to a different account with admin rights, temporarily, to access sudo, run the command, and then exit.

myuser$ su myadminuser
Password:
myadminuser$ sudo /Applications/xampp/xamppfiles/bin/mysql_upgrade -u root -p
myadminuser$ exit
myuser$

MySQL Configurations

XAMPP installs the MySQL my.cnf file by default at:

/Applications/XAMPP/xamppfiles/etc/my.cnf

HTTPS

Although security in the development environment can be unnecessary, working in an environment which closely matches the production environment is ideal. To enable secure encrypted traffic (HTTPS) on a local XAMPP installation, a few preparations need to be made.

Navigating to a website under HTTPS which does not have TLS/SSL enabled will throw an NET::ERR_CERT_COMMON_NAME_INVALID error in Chrome.

Prepare XAMPP for SSL

Check httpd.conf

  • Open /Applications/XAMPP/xamppfiles/etc/httpd.conf for editing.
  • Verify this line IS NOT commented out: LoadModule ssl_module modules/mod_ssl.so.
  • Verify you can find these settings blocks in the file:
<IfModule ssl_module>
<IfDefine SSL>
Include etc/extra/httpd-ssl.conf
</IfDefine>
</IfModule>
  • If all looks good, close and exit the file.
  • Run this command to test the config: sudo /Applications/XAMPP/xamppfiles/xampp enablessl. If all is well, the output should look something like this:
XAMPP:  XAMPP: Enable SSL...already enabled.

Update httpd-ssl.conf

  • Make a backup copy of /Applications/XAMPP/xamppfiles/etc/extra/httpd-ssl.conf in the same directory and name it something like httpd-ssl.conf.bak.
  • Open /Applications/XAMPP/xamppfiles/etc/extra/httpd-ssl.conf for editing.
  • Change the default port from 8443 to 443 if not already done. Look for Listen 8443 in the file and change it to Listen 443 if needed.
  • Next find the line ## SSL Virtual Host Context in the file and remove everything below it from the file.
  • Save and close the file.

Create and install a self-signed certificate for each vhost

A self-signed X.509 certificate must be created for each virtual host if it is to use HTTPS. Repeat the following process to secure each local virtual host.

Define a project config directory

  • Make or find a directory within your project to store environment-specific configuration files. For this example that directory will be /Users/dwatts/projects/myhost/local_assets.
  • Open Terminal and navigate (change directory) to that directory.

Generate the .key and .csr files with OpenSSL

  • Use the OpenSSL app to generate a private key file and a certificate signing request file for the host. From within the project config directory run:
openssl req -new -newkey rsa:2048 -nodes -keyout myhost.key -out myhost.csr

This should generate a new myhost.key file and a myhost.csr file in the project config directory.

Create a .ext file

  • Within the project config directory create a new file called myhost.ext with the command touch myhost.ext.
  • Open the myhost.ext file for editing and put-in the following code:
authorityKeyIdentifier=keyid,issuer
basicConstraints=CA:FALSE
keyUsage = digitalSignature, nonRepudiation, keyEncipherment, dataEncipherment
subjectAltName = @alt_names
[alt_names]
DNS.1 = local.myhost.com
  • Save and close the file.

Generate the .crt file with OpenSSL

  • Use the OpenSSL app to generate the self-signed certificate for the host. From within the project config directory run:
openssl x509 -req -sha256 -extfile myhost.ext -days 3650 -in myhost.csr -signkey myhost.key -out myhost.crt

This should generate a new myhost.crt file in the project config directory.

Install the .crt file on the host

  • Open /Applications/XAMPP/xamppfiles/etc/extra/httpd–vhosts.conf for editing.
  • Find the definition for the virtual host which is getting security and copy the definition directly below the original.
  • Edit the copied definition. Change the instance of *:80 to *:443.
  • Turn-on SSL and define the path to the .crt and .key files for the host. Add the following lines just after the DocumentRoot line:
SSLEngine on
SSLCertificateFile "/Users/dwatts/projects/myhost/local_assets/myhost.crt"
SSLCertificateKeyFile "/Users/dwatts/projects/myhost/local_assets/myhost.key"

The complete definition for the virtual host blocks should look like this:

# My Custom Virtual Host
<VirtualHost *:80>
    ServerName local.myhost.com
    DocumentRoot "/Users/dwatts/projects/myhost/repo/public_html"
    <Directory "/Users/dwatts/projects/myhost/repo/public_html">
        Require all granted
    </Directory>
</VirtualHost>

# My Secure Custom Virtual Host
<VirtualHost *:443>
    ServerName local.myhost.com
    DocumentRoot "/Users/dwatts/projects/myhost/repo/public_html"
    SSLEngine on
    SSLCertificateFile "/Users/dwatts/projects/myhost/local_assets/myhost.crt"
    SSLCertificateKeyFile "/Users/dwatts/projects/myhost/local_assets/myhost.key"
    <Directory "/Users/dwatts/projects/myhost/repo/public_html">
        Require all granted
    </Directory>
</VirtualHost>
  • Save and close the file.

Restart XAMPP Apache

Use the XAMPP UI to restart Apache.

Test the HTTPS URL

  • Visit the virtual host in a browser at its HTTPS URL: https://local.myhost.com.

You SHOULD see the NET::ERR_CERT_INVALID error message! Because the certificate is not signed by a valid CA, the browser rejects it (which is good). Mac OS needs to be told that this certificate can be trusted.

Trust the cert in Keychain

The easiest way to add a certificate file to the macOS Keychain is to go find the file in Finder and double click it.

  • Open Finder and navigate to the folder /Users/dwatts/projects/myhost/local_assets where the myhost.crt file for the vhost exists.
  • Double-click the myhost.crt file to open it in Keychain. Or right-click and choose Open With > Keychain.
  • Find the host name local.myhost.com in the list under the login keychain and click it. Details about the certificate will show with the message This certificate has not been verified by a third party.

  • Double-click the hostname in the list to open the certificates settings window.
  • Click the word Trust to open the certificate trust settings.
  • Set the When using this certificate drop-down to Always Trust.

  • Close the cert settings window. You will be asked for an admin password.
  • Now, visit or refresh the HTTPS URL: https://local.myhost.com. The page should load successfully and the lock icon should display in the URL bar to indicate HTTPS.

Redirect HTTP to HTTPS

Redirect all requests to non-secure URLs to HTTPS URLs.

  • Open /Applications/XAMPP/xamppfiles/etc/extra/httpd–vhosts.conf for editing.
  • Change the original port 80 virtual host definition to simply redirect everything to the HTTPS URLs.
<VirtualHost *:80>
    ServerName local.myhost.com
    Redirect 301 / https://local.myhost.com
</VirtualHost>
  • Restart Apache.
  • Now, try to visit the NON-HTTPS URL: http://local.myhost.com. You should immediately be redirected to the HTTPS URL. If you click the back button in the browser, it should not take you to the HTTP URL for the page.

More Resources