There is a special but important issue when installing on a real server (a problem which doesn't happen on localhost or installs), which can stump users.

For this I must explain some background. If you're running Razor in Server-Mode (which is probably the most common today) you actually have 3 layers:

  1. The Browser Client which is basically an empty page and some JS which will then use WebSockets to load html / data from the backend.
  2. The Server Client which is an isolated process that does the work which could otherwise run in the browser - this will generate HTML and stuff and do click-handling etc. 
  3. The Server Backend which contains backend APIs

What is easy to get wrong is when you use local hosts.ini settings on your PC to test this. If you configure oqtane.test to point to (that would be the server IP) then this happens:

  1. You point my browser to oqtane.test  - it will resolve to and get the Browser Client which will then - running on my PC - continue with WebSockets requests to oqtane.test - again on
  2. This will start the Server Client which is in an isolated process. It will start processing the DLLs at very early on need some data from the backend. The communication between the Server Client and the Server Backend happens through http, even though it's running on the same machine. 
  3. The Server Client knows it's communicating on oqtane.test so it will open an http-connection to the Server Backend on oqtane.test
  4. Since this process is running on the server, it doesn't have your hosts.ini setting and will not be able to find this IP. So that would fail. 

This is IMHO one of the biggest issues which people will run into when test-installing it on real servers.

To Solve this you have these Options

  1. Use and test on the PC (as all * point to localhost)
    1. Configure the IIS on the server to use such a domain and listen to in addition to your server IP - you don't need a hosts.ini entry as it's already in the public DNS
    2. Test it using a browser on the server 
  2. Use and test on your PC
    1. Configure IIS as mentiond in the first example
    2. Then configure your local hosts.ini file to have the same domain but point to the server IP
    3. Now you can ist from your local PC 
  3. Use a real domain which you added to a real DNS which is used by both your PC and the server