Local Development with SSL

The design and implementation of new web APIs and applications require security to be built-in from the start rather somehow being engineered in later as an afterthought. Yet, when one starts development, is not always that straightforward to set up your local environment such that you can be confident that what 'works on my machine' will be translated to when the application is deployed in an environment.

Local Development Security Pitfalls

Most developers typically start off by simply running up a non-secure application against "localhost:8080". What could possibly go wrong? Well, as it turns out, quite a few things.

Modern web browsers (such as Chrome) do not always regard traffic from localhost and/or private networks the same. Not to mention the subtle differences that come into play with regards to Cross-Origin Resource Sharing (CORS) when not using a 'proper' domain name.

In addition, developing against a non-secure server could potentially expose you to a number of issues once you deploy the application to the an environment where SSL is enabled. Typical problems here include certificate trust issues, mixed-content (SSL/non-SSL) warnings and all sorts of 'hidden' broken link and websocket/back-channel bugs that could suddenly appear when you switch over to a 'real' domain name .

Making and Managing Local Self-Signed Certificates?

A solution advocated by many is the creation of self-signed certificates for localhost. With a bit of toil this is something that you may be able to set up. However, in practice I found this approach to have a number of shortcomings:

  • The solution involves meddling with the certificate store and/or trusted root certificate authorities on the machine. While this in of itself should already give you a reason to hesitate - you need to repeat this somewhat unintuitive series of steps for every member of the team.

  • You still end up using localhost for your development. Hence all of the idiosyncrasies of not working against a 'real' domain still applies.

  • Want to quickly share a link with someone to show off something you have running locally? Not really possible to do - everything is geared for localhost so they will just end up seeing certificate issues and broken links.

The Solution: Local Development Domains

For TeraHelix development, we have opted for a solution where we use a 'real' certificate and domain - albeit scoped to each individual team member’s workstation. It works like this:

1) Purchase a domain from your favorite registrar

Select a domain that will solely be used for local development that has a memorable name and a cost effective price tag. From our favorite domain registrar (we use GoDaddy), we purchased - terahelix-local.com - for less than a £1.

2) Obtain a SSL certificate for that domain

Let’s Encrypt is an excellent free service that you can use to obtain a proper certificate. Simply follow the instructions on their website for your environment and obtain the the certificate keys (typically these files are: cert1.pem, chain1.pem, fullchain1.pem, privkey1.pem).

Stuck behind a corporate firewall and unable to set up a machine connected to the internet? Well, quickly set up a temporary Amazon Spot Instance (Ubuntu works best) on which you can install the CertBot software and obtain your certificates.

You can keep these certificates (public and private keys) wherever convenient for use by locally running software. For instance, a file share or even inside your source code repository. However, be careful if this location is available to public (such as on GitHub) - this will require certificate authorities to revoke this certificate.

3) Edit your host file with the new domain name

Finally, you need to make sure that when you enter your domain name in your browser, that is resolves to your local machine. To do this you have to edit your host file. Although the location of this file may differ depending on your operating system, the format is broadly similar:

  • On Linux and MacOS: /etc/hosts

  • On Windows: c:\Windows\System32\Drivers\etc\hosts	localhost	jackdevbox	terahelix-local.com

And if you want to share a 'terahelix-local.com' with a colleague to look at something you have deployed locally, simply ask them to update their own host file temporarily to point to your IP address. For instance:	terahelix-local.com

(the above assumes you are all working on the same private network)

With all this in place, you should be able to run up your application:

local browser screenshot


Local development should include security and SSL consideration right from the start. Leaving this as an afterthought invariably exposes you to a whole slew of browser inconsistencies and potential security vulnerabilities at a later stage in your software development life cycle.

Any thoughts, queries and comments are, as always, welcome. Feel free to let us know at https://terahelix.io/contact