What is Router Mode?

Ideally, you would never have to know about this setting. But here you are; I’m sorry and welcome to the club!

So what is Router Mode?

Router Mode is Local’s way of offering the best offline development experience possible while still “playing nice” with other, similar development applications.

You can access this setting by navigating to “Preferences > Advanced > Router Mode,” where you will find two options:

  1. Site Domains Router Mode
    • The default mode that Local runs. In this mode, Local will start a “router” that listens on port 80 and directs traffic to the individual sites that Local manages. The domain for each site will look something like example.local
  2. localhost Router Mode
    • This fallback mode doesn’t start the Local router and instead, each site is reached directly using a dedicated port on the computer. Using this mode means that the domain will look something like localhost:10005

Ok, that’s a lot of jargon, so if you’re confused, it might help to zoom out a bit and understand how the different Local parts work.

In general, the software that serves up web pages “listens” for requests and then generates a “response” for that request. The actual location that these pieces of software listen to is called a port. For example, the default port for requests made over HTTP is port 80, while requests made over HTTPS is port 443.

Since only one piece of software can listen to a port at one time, Local has to figure out a way to serve multiple sites from the same HTTP port (port 80).

Local does this by doing two things:

  1. Each site that Local manages is given a random port number to listen to, for example, 10005. Those sites can be accessed directly by appending the port to localhost, which looks like: localhost:10005.
  2. A “router” is created and is listening on port 80. This router is responsible for translating a meaningful domain like example.local into the actual site listening on a specific port: ie, localhost:10005.

When using “Site Domains” router mode, the browser connects to port 80 and Local’s router then connects to the appropriate port for each individual site.

When using localhost router mode, the browser connects directly to the port that each site is listening on. This allows another process to listen on port 80, but it also means some diminished functionality when interacting with those sites.

Hopefully, that additional context helps visualize how Local is configured. As you might imagine, things can break when the router isn’t able to start – the most obvious thing that breaks is that you can’t use meaningful domains like example.local. Instead, you would have to remember the port number for each site.

In most cases, Local can’t start the router because there is something already occupying port 80. There are only two options to get things working:

  1. Set Local to use localhost Router Mode.
  2. Stop whatever is already listening on port 80 and restart Local.

Of the two modes that Local can use, setting the router mode to localhost is the easiest and allows Local to run while other applications are using the default HTTP port of 80. If you go this route, there are some limitations when using localhost router mode:

  1. Sites can’t use HTTPS. Because Local can’t manage the localhost SSL certificate, there’s no way for Local to make the sites accessible over HTTPS.
  2. Sites can’t use Live Links. The router handles part of the magic of using live links.

Selecting the Router Mode from the “Advanced” section of the Preferences screen.

When in localhost Router Mode, the Site Host will have localhost and the port number for the site.

If you want to use all of the features that Local offers, then running in the default “Site Domains” router mode is required. In most cases, this is seamless, but if you are unsure about what piece of software is already listening on port 80, it can be challenging to zero in on where the conflict is.

The quickest way to zero in on what is listening on port 80 is to open a terminal and issue this command, which will prompt you for your computer password.

sudo lsof -i:80; sudo lsof -tnP -i:80 | xargs -n 1 ps -p

If you’re curious about what this command is doing, it’s basically:

  1. Listing all the “open files” on port 80
  2. Listing more details about the process that’s running on port 80

With that additional info, you should be able to shut down that application gracefully, but if you need to kill that process forcefully, you can do so from within a terminal:

kill <process-id>

Under Windows, finding those processes that are listening on Port 80 can be a little more tricky and might need to do some examining with the Task Manager.

One thing that can help is to use cmd.exe to run the following commands to help drill down to the actual processes that are listening on port 80.

Note: make sure to replace <process-id> with whatever process you found in the first command:

netstat -nao | find "80"
tasklist /v /fo list /fi "pid eq <process-id>"

Hopefully, that points you to the application that’s listening, as well as give you enough info to investigate further.

As an example, here are a couple of screenshots of investigating and disabling the built-in IIS server that is enabled by default for some versions of Windows.

A screenshot showing how to use the output from the netstat command to zero in on the actual process in the Task List. From there, additional info can be found by right-clicking on the process and selecting “Properties.”
Using the information from the previous image, we can do an internet search for ntoskrnl windows port 80. This lead me to disable the built-in IIS server from within Windows Features.

Changing Router Mode

If the router mode is changed, some additional steps need to happen for the site to work with the new Router Mode.

Local will occasionally check to see if the domain within the database matches what it thinks the domain should be. If those are different, it will prompt you to “fix it”. In the case of switching to localhost router mode, Local will search for example.local and replace it with the appropriate port number, something like localhost:10005.

A similar process happens when switching back to “Site Domain” router mode.

A screencast that walks through changing the Router Mode and then clicking the “Fix It” button to update the domain within the database.