One of the many little annoyances that I encounter while working on client sites, is when the client has a valid SSL certificate installed on their server, but the HTTPS redirection happens in code instead of at the server level.
This means that even if I export the database with the site urls replaced to match my local environment, or run a search or replace on the local database, the code execution will still try to redirect to the secure version of the domain, meaning I have to first find out where that redirection is taking place, and remove it.
Often it’s done inside the site config, which is pretty quick to comment out, but other times it’s done via a plugin which is harder to find. In the long run it would be infinitely quicker and easier to just have a trusted SSL certifcate installed for the local site. My previous attempts at this meant installing a self signed certificate, but this means it’s not ‘trusted’ by the browser, and you either have to configure your browser to trust the certificate, or get an annoying warning about the site’s certificate not being trusted or secure enough every time you browse to the local site.
Thankfully, after asking around, I was pointed to mkcert “a simple zero-config tool to make locally trusted development certificates with any names you’d like.” It creates a local certificate authority, installs the authority into your local and browser trust stores. It also includes a tool to make local, trusted certificates for any local domain name. All that I have to do is set those certificates up for each local domain.
Installing mkcert is pretty straightforward and the project readme contains instructions for the various operating systems.
Regular Apache Virtual Hosts for local development
Because I use Ubuntu as my OS and Apache as my local webserver, whenever I add a new client site, it’s usually a 4 step process:
I start by creating a new Apache VirtualHost config file, copied from an existing one, and change some site related values
cd /etc/apache2/sites-available/
sudo cp 000-default.conf localsite.conf
sudo nano localsite.conf
The values I change are ServerName, ServerAdmin, DocumentRoot and Directory values. I usually also set site specific log files
<VirtualHost *:80>
ServerName localsite.test
ServerAdmin webmaster@localsite.test
DocumentRoot /home/jonathan/development/websites/localsite
<Directory "/home/jonathan/development/websites/localsite">
#Require local
Order allow,deny
Allow from all
AllowOverride all
# New directive needed in Apache 2.4.3:
Require all granted
</Directory>
ErrorLog ${APACHE_LOG_DIR}/localsite-error.log
CustomLog ${APACHE_LOG_DIR}/localsite-access.log combined
</VirtualHost>
Once the config is saved, I enable the new site, and restart Apache
sudo a2ensite localsite.conf
sudo service apache2 restart
The last step is to let my local machine know what IP address to resolve the VirtualHost ServerName value to, in this case localsite.test
sudo nano /etc/hosts
127.0.0.1 localsite.test
Once this is all done, I can browse to http://localhost.test and it will serve the files in the /home/jonathan/development/websites/localsite directory.
Note, if you get a ‘permission denied error’ doing this, the quick way to fix this is to change the user and group that Apache runs as, to your local user.
sudo nano /etc/apache2/apache2.conf
# These need to be set in /etc/apache2/envvars
#User ${APACHE_RUN_USER}
#Group ${APACHE_RUN_GROUP}
User jonathan
Group jonathan
Save that file, restart Apache, and you’ll be good to go.
Adding a SSL layer to a local site
I wasnt sure if the set up of a local, trusted certificate would be any different, and I was pleased to find out this was indeed the case.
Creating the new local Certificate Authority
Once mkcert is installed, the first thing I needed was to create and install the new local certificate authority. Fortunately this only needs to be done once.
mkcert -install
Once you’ve installed the CA, you can issue site certificates against it. I like to place all my site certificates on one place like ssl-certs
mkdir ssl-certs
cd ssl-certs
Then it’s time to create the certificates.
mkcert localsite.test
This creates a localsite.test.pem certificate and a localsite.test-key.pem key, which is used in the Apache SSL config for the site.
Side note, I’ve started using .test for my local domains, because Chrome doesn’t seem to like my use of .local domains until I tell it to. Earlier this year I discovered this is because it’s reserved for link-local host names that can be resolved via the Multicast DNS name resolution protocol. So I switched to .test. Thanks to Andrey Savchenko for pointing this out to me.
Setting up the certs for a local site
First step was to enable the SSL module for Apache. This also needs to only be done once.
sudo a2enmod ssl
Next, I needed to create an SSL version of the local site virtual host config. I started by copying the existing default-ssl.conf and making my changes
cd /etc/apache2/sites-available/
sudo cp default-ssl.conf localsite-ssl.conf
sudo nano localsite-ssl.conf
It’s actually pretty similar to a standard VirtualHost config, except for the checking if the SSL module is installed, the VirtualHost domain and port, and stuff from SSLEngine down. As you can see the certificate and key are specified in the SSLCertificateFile and SSLCertificateKeyFile entries respectively
<IfModule mod_ssl.c>
<VirtualHost _default_:443>
ServerName localsite.test
ServerAdmin webmaster@localsite.test
DocumentRoot /home/jonathan/development/websites/localsite
<Directory "/home/jonathan/development/websites/localsite">
#Require local
Order allow,deny
Allow from all
AllowOverride all
# New directive needed in Apache 2.4.3:
Require all granted
</Directory>
ErrorLog ${APACHE_LOG_DIR}/localsite-error.log
CustomLog ${APACHE_LOG_DIR}/localsite-access.log combined
SSLEngine on
SSLCertificateFile /home/jonathan/ssl-certs/localsite.test.pem
SSLCertificateKeyFile /home/jonathan/ssl-certs/localsite.test-key.pem
<FilesMatch "\.(cgi|shtml|phtml|php)$">
SSLOptions +StdEnvVars
</FilesMatch>
<Directory /usr/lib/cgi-bin>
SSLOptions +StdEnvVars
</Directory>
</VirtualHost>
</IfModule>
Once the SSL config is created, I enable it.
sudo a2ensite localsite-ssl.conf
I can then restart Apache, and the SSL secured version of the local site is enabled.
This is something I’ve wanted to get set up for the longest time, so a massive thanks to Filippo Valsorda for creating mkcert.
Leave a Reply