Ayende @ Rahien

My name is Oren Eini
Founder of Hibernating Rhinos LTD and RavenDB.
You can reach me by phone or email:


+972 52-548-6969

, @ Q c

Posts: 6,026 | Comments: 44,842

filter by tags archive

Fix it in the code, not in the documentation

time to read 2 min | 365 words

One of the things that Fitzchak is working on right now is the RavenDB in Practice series. During the series, he run into an issue with RavenDB failing if the configured port is already taken. Since by default we use 8080, it wasn’t very surprising that on his machine, the 8080 port was already taken. Because he run into this problem, he set out to document how to fix this issue if you run into it.

My approach was different, I don’t like documenting things. More to the point, documenting a problem is a last ditch effort, something that you do only if you have no other choice. It is usually much easier to figure out a way to solve the problem. In the case of RavenDB and the busy port, we start out at port 8080, and if it is busy, we find another port that is open that we can use. That means that the initial experience is much easier, since you can immediately make use of the database without dealing with how to change the port it is listening on.

Nitpicker corner: this feature kicks in only if you have explicitly stated that you wanted it in the configuration. This is part of the default config for RavenDB, and is meant for the initial process only. It is not recommended for production use.

Why is it so much better in code than in the documentation? Surely it takes a lot less time to explain how to modify an App.config value than write the code for auto detecting an open port and binding to it… and you need to document the behavior anyway…

The answer is that it saves on support and increase success rate. The saves on support are pretty obvious. If it works Out Of The Box, everyone is happy. But what is this Success Rate that I am talking about?

Unless you are someone like Oracle, you have a very narrow window of time when a user is willing to try whatever it is that you are providing. And you had better make that window of time a Success Story, rather than “Reading the Known Issues” document.



Unless the client can somehow detect which port the server is running on, I'm not convinced this is actually a success maker. You've just moved the problem to first run of the client failing mysteriously.


Shouldnt you fix it so it doesn't clash with a Well Known Port?


Either register a port with IANA (still doesn't fix the issue if someone else is not playing nice) or use the private range >= 49152.


interesting. Like most of the truths, it seems obvious once you hear it. That doesn't applies only to developer tools like RavenDB.
We are building a cms for the publishing industry. If you can setup a demo in a finger snap for a client and never meet this kind of configuration conflict, that can only help the decision process :).


IMHO one of the best things to do if you want to make initial user experience as painless as possible is to provide a virtual machine appliance. Without it I wouldn't even try to set up some 'exotic' products like SOLR, Kannel, ejabberd and many other - because of the pain of going manually through the installation process. You may, however, have some problems with handing out Windows VMs...

Ayende Rahien

JB, You mean like HTTP Alternate when you are writing HTTP server? That sounds like an excellent choice to me, the reason that we choose that port was to allow easier support for proxies and firewalls.

Ayende Rahien

Rafal, That assumes: a) That your client has VM software and is willing to run it. b) That scares people off because they assume that your software must be very hard to configure. c) If you are using a Windows VM, you have licensing issues.


I agree with Matthew; how is the client made aware of the auto-chosen port?

Fitzchak Yitzchaki

@Robert @Matthew,
Take a look here, specifically in this picture. As you can see, the console application specifies the Server Url and Port values.


Ugh. That's complicated.

Now I have to remember all these things:

  1. It will swap ports if 8080 is already in use
  2. BUT - this feature only kicks in if explicitly set in config
  3. BUT! The default config has this explicitly set!
  4. Also, I have to remember to take it out for production config!

And to top it off, it's not in documentation, so to recall these 4 points I have to wade through code!

Too much magic. Why don't you just have a port variable in the config. Let the user choose; don't assume you know what they want.

Fitzchak Yitzchaki

It's actually very simple. You have two options here:

  1. Explicitly specify the port that you want. If you do so, that's the port that Raven.Server is going to use. If it can't use it, an exception will be thrown.
  2. Use the star value ("*") which will let Raven.Server to automatically choose a port that is free to use. In this case, we'll start looking for port number 8080 and increase the port number until a free port is found. This option will give you more flexibility in development environments.

You can set this setting in the Raven.Server.exe.config file:

<add key="Raven/Port" value="*"/>

Comment preview

Comments have been closed on this topic.


No future posts left, oh my!


  1. Technical observations from my wife (3):
    13 Nov 2015 - Production issues
  2. Production postmortem (13):
    13 Nov 2015 - The case of the “it is slow on that machine (only)”
  3. Speaking (5):
    09 Nov 2015 - Community talk in Kiev, Ukraine–What does it take to be a good developer
  4. Find the bug (5):
    11 Sep 2015 - The concurrent memory buster
  5. Buffer allocation strategies (3):
    09 Sep 2015 - Bad usage patterns
View all series


Main feed Feed Stats
Comments feed   Comments Feed Stats