Suffixes in Heighliner

By default, Heighliner starts up an NGINX server on port 80 and 443 on your computer as a reverse proxy to all the applications started on it. It also uses the lvh.me suffix by default.

This means that if you start an app on Heighliner with the environment name foo then the URL on your computer will be http://foo.lvh.me

lvh.me is a domain that is set up in such a way that all of its subdomains also point to 127.0.0.1.

Reverse proxy

Why does it magically work?

By default heighliner sets up a reverse proxy that puts all your apps on a subdomain of (lvh.me)[lvh.me]. This means all your environments can be accessed like so: envname.lvh.me. Easy.

Read more about lvh.me

HTTPS

If you want to you can create a self-signed HTTPS certificate for lvh.me, trust it and use it to access your dev sites with HTTPS! (Cool! Now you can debug your websites in HTTPS!)

It is easy to do this: Simply run

heighliner set cert-folder /home/me/my-certificate-folder

As preparation you need to generate HTTPS certificates. You should have the following files:

/home/me/my-certificate-folder/lvh.me.crt
/home/me/my-certificate-folder/lvh.me.key
/home/me/my-certificate-folder/lvh.me.chain.pem

Hint: you can create the .chain.pem file by going

cat lvh.me.key lvh.me.crt > lvh.me.chain.pem

Remember to trust your certificates! Otherwise your browser will give you an error (if it isn't dodgy).

If you and your colleagues all want to sign using the same certificates, simply put the certificates on a webserver and go:

heighliner set cert-url https://internal-site.com/dev-certificates

and Heighliner will look for certificates at:

https://internal-site.com/dev-certificates/lvh.me.crt
https://internal-site.com/dev-certificates/lvh.me.key
https://internal-site.com/dev-certificates/lvh.me.chain.pem

1Password

If you store your certificates in 1Password, you can use the cert-1password option:

heighliner set cert-1password Vault/Item

This tells Heighliner to look for the certificate fields in the specified 1Password item. By default, the field names match the file extensions: key, crt and chain.pem. For example, if your item is Vault/Dev-Certs, Heighliner will read:

op read "op://Vault/Dev-Certs/key"       → lvh.me.key
op read "op://Vault/Dev-Certs/crt"       → lvh.me.crt
op read "op://Vault/Dev-Certs/chain.pem" → lvh.me.chain.pem

The op CLI must be installed and authenticated on your machine.

Custom field names

If your 1Password item uses different field names, set them one at a time:

heighliner set cert-1password-field key privkey
heighliner set cert-1password-field crt fullchain
heighliner set cert-1password-field chain.pem ca-bundle

The first word is Heighliner's name for the file (key, crt or chain.pem — note it is chain.pem, not chain), the second is the field name in your item. Fields you leave out keep their default name. A name that is not one of the three is rejected rather than silently ignored.

With the above, Heighliner reads:

op read "op://Vault/Dev-Certs/privkey"   → lvh.me.key
op read "op://Vault/Dev-Certs/fullchain" → lvh.me.crt
op read "op://Vault/Dev-Certs/ca-bundle" → lvh.me.chain.pem

There is nothing to quote here, which is the point: an earlier JSON form of this command was easy to mangle.

Setting all the fields at once

cert-1password-fields (plural) still takes every field as one JSON object:

heighliner set cert-1password-fields '{"key":"privkey","crt":"fullchain","chain.pem":"ca-bundle"}'

This works, but the JSON has to survive your shell, and on Heighliner 0.10.0 and older the Docker image's entrypoint re-parsed its arguments and stripped the quotes, producing:

JSON::ParserError: expected object key, got 'key:privkey,...'

If you hit that, either upgrade or use the singular cert-1password-field above, which has nothing for a shell to eat.

Docker mode

Use a service account token:

export OP_SERVICE_ACCOUNT_TOKEN=ops_...
docker run -e OP_SERVICE_ACCOUNT_TOKEN=$OP_SERVICE_ACCOUNT_TOKEN heighliner ...

Create the token in the 1Password web app: Integrations → Developer Tools → Service Accounts. The token starts with ops_ and grants the op CLI access to your vaults.

HTTP/HTTPS Your own domain

If you have a fancy setup where you have your own localhost domain (like local.aweso.me) and you can generate your own SSL certificates (yes, very fancy) then you can set the suffix of your domain like this:

heighliner set http-suffix local.aweso.me

And your apps will be all envname.local.aweso.me

If you change these settings

You will need to run

heighliner down
heighliner shutdown

And run

heighliner up

Again for changes to take effect.

Note: heighliner shutdown only stops the shared infrastructure containers (nginx, DNS, Chrome). It does not stop your app containers — use heighliner down for that.