Let's Learn About lcl.host

Welcome to the world of lcl.host!

Here we'll dive into the details about how lcl.host works within Anchor, the lcl.host domain and subdomains, and finally conclude with what's happening in your local trust store. Anchor supports personal and professional organizations, for both your personal projects and your team's development needs. Anchor is an expansion of a private Certificate Authority with its own hosted, private infrastructure.

For more information about when you might want to use lcl.host to setup TLS for your local development environment, read Why use lcl.host.

How lcl.host Works Within Anchor

First let's go over what Anchor does when you run anchor lcl.

When you run anchor lcl or register for an Anchor account, we create a localhost realm for your local development environment. This includes a CA for your personal development environment, which allows you to provision certificates for subdomains of lcl.host and localhost. These resources for your development environment are only useable by you in your development environments. They don't work outside of it.

For example, if another user gets a certificate for their Foo project with the subdomain foo.lcl.host, that certificate will work on their machine but it won't work in your development environment on your Foo project. Your machine wouldn't trust their certificate by design.

lcl.host Domain and Subdomains

lcl.host is a Fully Qualified Domain Name (FQDN) and combining a FQDN with HTTPS creates a secure context in your browser. Browsers handle the localhost domain (and subdomains, if they support them) as a special case: they act like a secure context in some ways, but not all, as discussed in the "Why use lcl.host" article.

Every subdomain that you setup with lcl.host maps to your loopback address (aka localhost or IP 127.0.0.1). If you examine the host of an lcl.host subdomain you will see that it resolves to:

$ host foo.lcl.host
foo.lcl.host has address 127.0.0.1
foo.lcl.host has IPv6 address ::1

As you can see, this subdomain has an address of 127.0.0.1 without you doing any local configuration or manipulating your /etc/hosts file.

Why is this great for you?

1. It's a drop-in replacement anywhere you would use the localhost domain.
2. You don't have to worry the gotchas of having edited /etc/hosts and overriding public DNS, avoiding future pain and getting burned by Past You.
3. You don't have to manage DNS records, you just use lcl.host which is already a FQDN, and works everywhere, all the time.

Your Local Trust Store

Finally, let's go through what is happening on your local system when you run anchor lcl. Running anchor lcl will install your personal CA certificates, built by Anchor for your development environment, into your operating systems (OS) and browser trust stores. Let's go over what a trust store is and how they work.

All OS and browsers ship with certificates from trusted sources that they trust implicitly. Anchor creates and adds certificates to all of these OS and browser trust stores so that they can be used to validate HTTPS/TLS connections.

Why is this setup necessary? Certificates issued by Anchor are not trusted by default in any browser or OS because they are signed by an Anchor managed private CA. Only certificates issued by a public CA (like LetsEncrypt) are trusted by default by browsers and OSes. Fortunately, it's possible to configure your OS and browsers to trust Anchor certificates by adding your personal CA certificates into the various trust stores. Unfortunately, we need sudo privileges to add the certificates to your trust stores which requires root-level access. Anchor will only add the certificates that have been provisioned for your Anchor account so that only those ones are trusted by your system.

Given that there are multiple trust stores you will need to enter your password multiple times to allow sudo access to each of the trust stores. Once that's complete, all of your certificates will be trusted seamlessly.

If you don't have sudo-level access, you will need to work with your IT team to get that level of access. Without this, your browser and system won't trust the certificates that are presented.