GitHub - peterldowns/localias: custom local domain aliases for local dev servers

Localias

Localias is a tool for developers to securely manage local aliases for development servers.

Use Localias to redirect https://server.test → http://localhost:3000 in your browser and on your command line.

This is commonly useful for web developers or teams for the following reasons:

Use convenient names, without ports, in your URLs
Serve your development website behind TLS, minimizing differences between development and production.
- No more CORS problems!
- Set secure cookies!

Major Features

Works on MacOS, Linux, and even WSL2 (!)
Automatically provisions and installs TLS certificates for all of your aliases by default.
Automatically updates /etc/hosts as you add and remove aliases, so that they work with all of your tools.
Runs in the foreground or as a background daemon process, your choice.
Supports shared configuration files so your whole team can use the same aliases for your development services.
Proxies requests and generates TLS certs with caddy so it's fast and secure by default.

Install

Homebrew:

# install it
brew install peterldowns/tap/localias

Golang:

# run it
go run github.com/peterldowns/localias/cmd/localias@latest --help
# install it
go install github.com/peterldowns/localias/cmd/localias@latest

Nix (flakes):

# run it
nix run github:peterldowns/localias -- --help
# install it
nix profile install --refresh github:peterldowns/localias

Manually download binaries

Visit the latest Github release and pick the appropriate binary. Or, click one of the shortcuts here:

How does it work?

Localias has two parts:

the configuration file
the proxy server

The configuration file is where Localias keeps track of your aliases, and to which local ports they should be pointing. The proxy server then runs and actually proxies requests based on the configuration.

configuration file

Every time you run localias, it looks for a config file in the following places, using the first one that it finds:

If you pass an explicit --configfile <path>, it will attempt to use <path>
If you set an environment variable LOCALIAS_CONFIGFILE=<path>, it will attempt to use <path>
If your current directory has .localias.yaml, it will use $pwd/.localias.yaml
If you are in a git repository and there is a .localias.yaml at the root of the repository, use $repo_root/.localias.yaml
Otherwise, use $XDG_CONFIG_HOME/localias.yaml, creating it if necessary.
- On MacOS, this defaults to ~/Library/Application\ Support/localias.yaml
- On Linux or on WSL, this defaults to ~/.config/localias.yaml

This means that your whole dev team can share the same aliases by adding .localias.yaml to the root of your git repository.

To show the configuration file currently in use, you can run

# Print the path to the current configuration file
localias debug config
# Print the contents of the current configuration file
localias debug config --print

The following commands all interact directly with the configuration file:

# add or edit an alias
localias set <alias> <port>
# clear all aliases
localias clear
# list all aliases
localias list
# remove an alias
localias remove <alias>

The configuration file is just a YAML map of <alias>: <port>! For example, this is a valid configuration file:

https://secure.test: 9000
http://insecure.test: 9001
insecure2.test: 9002
bareTLD: 9003

proxy server

When you execute localias run or localias daemon start to run the proxy server, Localias performs the following operations:

Reads the current Localias configuration file to find all the current aliases and the ports to which they're pointing.
Checks the /etc/hosts file to make sure that every alias is present
- Adds any new aliases that aren't already present
- Removes any old aliases that are no longer in the Localias config
- Only updates the file if any changes were made, since this requires sudo privileges.
Runs the Caddy proxy server
- If Caddy has not already generated a local root certificate:
  - Generate a local root certificate to sign TLS certificates
  - Install the local root certificate to the system's trust stores, and the Firefox certificate store if it exists and an be accessed.
- Generate a Caddy configuration telling it how to redirect each alias to the correct local port.
- Generate and sign TLS certificates for each of the aliases currently in use
- Bind to ports 80/443 in order to proxy requests

Localias requires elevated privileges to perform these actions as part of running the proxy server:

Edit /etc/hosts
Install the locally generated root certificate to your system store
Bind to ports 80/443 in order to run the proxy server

When you run Localias, each time it needs to do these things, it will open a subshell using sudo to perform these actions, and this will prompt you for your password. Localias does not read or interact with your password.

Localias is entirely local and performs no telemetry.

Quickstart

Running the server for the first time

After installing localias, you will need to configure some aliases. For this quickstart example, we'll assume that you're running a local http frontend devserver on http://localhost:3000, and that you'd like to be able to access it at https://frontend.test in your browser and via tools like curl.

First, create the alias:

$ localias set frontend.test 3000
[added] frontend.test -> 3000

You can check to see that it was added correctly:

$ localias list
frontend.test -> 3000

That's it in terms of configuration!

Now, start the proxy server. You can do this in the foreground with localias run (and stop it with ctrl-c) or you can start the server in the background with localias daemon start. For the purposes of this quickstart, we'll do it in the foreground.

$ localias run
# some prompts to authenticate as root
# ... lots of server logs like this:
2023/05/02 23:12:58.218 INFO    tls.obtain      acquiring lock  {"identifier": "frontend.test"}
2023/05/02 23:12:58.229 INFO    tls.obtain      lock acquired   {"identifier": "frontend.test"}
2023/05/02 23:12:58.230 INFO    tls.obtain      obtaining certificate   {"identifier": "frontend.test"}
2023/05/02 23:12:58.230 INFO    tls.obtain      certificate obtained successfully       {"identifier": "frontend.test"}
2023/05/02 23:12:58.230 INFO    tls.obtain      releasing lock  {"identifier": "frontend.test"}
# process is now waiting for requests

This will prompt you to authenticate at least once. Each time Localias runs, it will

Automatically edit your /etc/hosts file and add entries for each of your aliases.
Sign TLS certificates for your aliases, and generate+install a custom root certificate to your system if it hasn't done so already.

Each of these steps requires sudo access. But starting/stopping Localias will only prompt for sudo when it needs to, so if you hit control-C and restart the process you won't get prompted again:

^C
$ localias run
# ... lots of server logs
# ... but no sudo prompts!

Congratulations, you're done! Start your development servers (or just one of them) in another console. You should be able to visit https://frontend.test in your browser, or make a request with curl, and see everything work perfectly*.

* are you using Firefox, or are you on WSL? See the notes below for how to do the one-time install of the localias root certificate

Running as a daemon

Instead of explicitly running the proxy server as a foreground process with localias run, you can also run Localias in the background with localias daemon start. You can interact with this daemon with the following commands:

# Start the proxy server as a daemon process
localias daemon start
# Show the status of the daemon process
localias daemon status
# Apply the latest configuration to the proxy server in the daemon process
localias daemon reload
# Stop the daemon process
localias daemon stop

When running as a daemon process, if you make any changes to your configuration you will need to explicitly reload the daemon:

# Start with frontend.test -> 3000
localias set frontend.test 3000
localias daemon start
# Update frontend.test -> 4004. 
localias set frontend.test 4004
# The daemon will still be running with frontend.test -> 3000, so
# to apply the new changes you'll need to reload it
localias daemon reload

Using the CLI

localias has many different subcommands, each of which is documented (including usage examples). To see the available subcommands, run localias. To see help on any command, you can run localias help $command or localias $command --help.

$ localias
securely manage local aliases for development servers

Usage:
  localias [command]

Examples:
  # Add an alias forwarding https://secure.test to http://127.0.0.1:9000
  localias set secure.test 9000
  # Update an existing alias to forward to a different port
  localias set secure.test 9001
  # Remove an alias
  localias remove secure.test
  # List all aliases
  localias list
  # Clear all aliases
  localias clear
  
  # Run the proxy server in the foreground
  localias run
  # Start the proxy server as a daemon process
  localias daemon start
  # Show the status of the daemon process
  localias daemon status
  # Apply the latest configuration to the proxy server in the daemon process
  localias daemon reload
  # Stop the daemon process
  localias daemon stop
  
  # Show the host file(s) that localias edits
  localias hostctl print
  # Show the entries that localias has added to the host file(s)
  localias hostctl list
  # Remove all localias-managed entries from the host file(s)
  localias hostctl clear

Available Commands:
  clear       clear all aliases
  daemon      control the proxy server daemon
  help        Help about any command
  hostctl     interact with the hosts file(s) that localias manages
  list        list all aliases
  remove      remove an alias
  run         run the proxy server in the foreground
  set         add or edit an alias
  version     show the version of this binary

Flags:
  -c, --configfile string   path to the configuration file to edit
  -h, --help                help for localias
  -v, --version             version for localias

Use "localias [command] --help" for more information about a command.

Errata

Why build this?

Localias is the tool I've always wanted to use for local web development. After years of just visiting localhost:8080, I finally got around to looking for a solution, and came across hotel (unmaintained) and its fork chalet (maintained). These are wonderful projects that served as inspiration for Localias, but I think Localias is implemented in a better and more useful way.

I also wanted an excuse to play around with building a MacOS app, and this seemed like a small and well-defined problem that would be amenable to learning Swift.

Finally, my friend Justin wanted this to exist, too:

I swear there's a tool that lets me do:

localhost:8000 → application.local
localhost:3000 → marketing.local
localhost:3002 → docs.local

But I can't for the life of me remember the name of it. Does anyone know what I'm talking about?

Why not hotel/chalet?

Localias is designed to replace alternative tools like hotel/chalet. Hotel is no longer maintained, and Chalet is a fork of Hotel with basically the same features. I think Localias compares favorably:

Localias is a single binary. Hotel requires a working NodeJS runtime.
Localias works by modifying /etc/hosts (and the windows equivalent), which makes it easy to observe and debug. Hotel requires you to configure itself as a proxy in your browser or in your operating system.
- Aliases configured with Localias will also work in command-line scipts or requests sent by programs like curl. Hotel aliases only work in your browser.
Localias allows you to create any number of aliases on different TLDs at the same time. Hotel only allows you to use one TLD.
Localias will generate a root certificate and any necessary certificates for each alias, and install the root certificate in your system store so you do not see any warnings about invalid self-signed certificates. Hotel does not do any TLS signing.
Localias will automatically discover configuration files committed to your git repository, which makes it easy to share a configuration with you development team. Hotel does not allow for shared configuration files.
Localias does not attempt to do any kind of process management or launching, leaving that entirely up to you. Hotel attemps to run and manage processes for you.

Domain conflicts and HSTS

When using Localias, you should not create aliases with the same name as existing websites. For instance, if you're working on a website hosted in production at https://example.com, you really do not want to create a local alias for example.com to point to your development server. If you do, your browser may do things you don't expect:

Your development cookies will be included in requests to production, and vice-versa. If you are turning localias off/on and switching between development and production, these cookies will conflict with each other and generally make you and your website extremely confused.
If your production website uses HSTS / certificate pinning, you will see very scary errors when trying to use it as a local alias for a development server. This is because localias will be serving content with a different private key, but HSTS explicitly tells your browser to disallow this.

In general, it's best to avoid this problem entirely and use aliases that end in .test, .example, .localhost, or some other TLD that is not in use.

`.local` domains on MacOS

If you add an alias to a .local domain on a Mac, resolving the domain for the first time will take add ~5-10s to every request thanks to Bonjour. The workaround would be to set 127.0.0.1 domain.local as well as ::1 domain.local but that's tricky with the way that the hostctl package is currently implemented.

The Localias Root Certificate and System Trust Stores

Localias's proxy server, Caddy, automatically generates certificates for any secure aliases you'd like to make. When Localias runs it will make sure that its root signing certificate is installed in the system store on Mac and Linux. If your browser reads from the system store to determine which certificate authorities to trust, this means that everything will work nicely for you out of the box.

This means that if you're using Safari/Edge/Chrome on MacOS/Linux, you're good to go, and you will see a nice "verified" or "secure" status when you visit one of your secure aliases in your browser.

WSL

When you run Localias inside of WSL, so basically inside of a Linux virtual machine with a Windows host, Caddy will generate certificates and install them to the Linux VM's trust store, but not to the parent Windows host. This means that if you're using a browser running in Windows, you will see a certificate warning if you visit a secure alias.

You can fix this by explicitly installing the Localias root certificate to your Windows machine's certificate store. You can do this with the following command, which will prompt you to authorize it as an administrator:

localias debug cert --install

Firefox

Firefox does not trust the system certificate store by default. This means that unfortunately, if you visit you secure alias, you will see a warning that the certificate is invalid:

(TODO: image)

On MacOS/Linux, Firefox can be configured to trust the system store by changing a configuration setting.

Open Firefox
Visit about:config

Set

security.enterprise_roots.enabled = true

Quit and re-open Firefox

Altenately, or if you're using Firefox on Windows to try to browse to a server running in WSL, you can manually add the Localias root certificate to Firefox. You will need to do this if you're using WSL, since Firefox on Windows does not read from the system trust store.

Find the path to the root certificate being used by Localias. If you're on MacOS or Linux, run:
```
$ localias debug cert
/Users/pd/Library/Application Support/localias/caddy/pki/authorities/local/root.crt
```
to print the path to the certificate.

In WSL, you'll need to convert this to a Windows file path using the wslpath tool:
```
$ wslpath -w $(localias debug cert)
\\wsl$\Ubuntu-20.04\home\pd\.local\state\localias\caddy\pki\authorities\local\root.crt
```
Copy this path to the clipboard.
In Firefox, visit Settings > Privacy & Security > Security > Certificates, or visit Settings and search for "certificates".
Click View Certificates
Under the Authorities tab, click Import.... This will open a filepicker dialog.
- On MacOS: hit "Cmd+Shift+G" to open a filepath dialog. Paste the path you copied earlier to select the root.crt.
- On Windows: in the "Name" field, paste the path to the root certificate that you copied earlier.
Click Open.
Check the box next to Trust this CA to identify websites. then click OK.

You should now see "localias" listed as a certificate authority. If you visit a secure alias, you should see that the certificate is trusted and no errors or warnings are displayed.

Allow Localias to bind to ports 443/80 on Linux

Localias works by proxying requests from ports 80 and 443 to your development servers. When you run Localias, it therefore will attempt to listen on ports 80 and 443. On Linux you may not be allowed to do this by default -- you may see an error like:

$ localias run
# ... some informational output
error: loading new config: http app module: start: listening on :443: listen tcp :443: bind: permission denied

or you may notice that starting the daemon does not result in a running daemon

$ localias daemon start
$ localias daemon status
daemon is not running

To fix this, after installing or upgrading Localias, you can use capabilities to grant the localias binary permission to bind on these privileged ports:

sudo setcap CAP_NET_BIND_SERVICE=+eip $(which localias)

For more information, view the arch man pages for capabilities and this Stackoverflow answer.

General reading / links / sources

There's a Mac application?

Sharp eyes — yes, there's a MacOS menu bar application, but it's not done yet. You can download it from the releases page or install it with brew install peterldowns/tap/localias-app if you'd like to try an early version. It's built by compiling the golang binary into a shared C library and then embedding that into a Swift app. It works great, sort of. Once I've improved it a bit I'll update this documentation.

Remaining major items:

Allow choosing the configuration file
Better display error messages (if daemon is already running, for example)
Info / help inside application explaining how the buttons work

Future Work

Docs
- How it works section
- WSL2 details
Improvements
- Daemon config command for dumping running config
- --json formatting for command line controller + caddy logs as well
- Helper for doing explicit certificate installation
  - Handle firefox if certutil is available?
  - automatically install localias root certs using powershell script when running in wsl2

Absortio

GitHub - peterldowns/localias: custom local domain aliases for local dev servers

Extracto

Contenido

Localias

Major Features

Install

Homebrew:

Golang:

Nix (flakes):

Manually download binaries

How does it work?

configuration file

proxy server

Quickstart

Running the server for the first time

Running as a daemon

Using the CLI

Errata

Why build this?

Why not hotel/chalet?

Domain conflicts and HSTS

`.local` domains on MacOS

The Localias Root Certificate and System Trust Stores

WSL

Firefox

Allow Localias to bind to ports 443/80 on Linux

General reading / links / sources

There's a Mac application?

Future Work

GitHub - peterldowns/localias: custom local domain aliases for local dev servers

Extracto

Contenido

Localias

Major Features

Install

Homebrew:

Golang:

Nix (flakes):

Manually download binaries

How does it work?

configuration file

proxy server

Quickstart

Running the server for the first time

Running as a daemon

Using the CLI

Errata

Why build this?

Why not hotel/chalet?

Domain conflicts and HSTS

.local domains on MacOS

The Localias Root Certificate and System Trust Stores

WSL

Firefox

Allow Localias to bind to ports 443/80 on Linux

General reading / links / sources

There's a Mac application?

Future Work

`.local` domains on MacOS