🏠 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.

Major Features

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!
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.
Serves .local domains over mDNS, so you can visit your development servers from your phone or any other device connected to the same network.

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>
# import all the aliases from another config file
localias import path/to/another/config/localias.yaml

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

bareTLD: 9003 # serves over https and http
implicitly_secure.test: 9002 # serves over https and http
https://explicit_secure.test: 9000 # serves over https and http
http://explicit_insecure.test: 9001 # serves over http only

proxy server

When you execute localias run or localias 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 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 start. You can interact with this daemon with the following commands:

# Start the proxy server as a daemon process
localias start
# Show the status of the daemon process
localias status
# Apply the latest configuration to the proxy server in the daemon process
localias reload
# Stop the daemon process
localias 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 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 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.

$ localia

Localias

Install / Use

README