Ayende @ Rahien

Refunds available at head office

Fix it in the code, not in the documentation

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.

Comments

Matthew
06/05/2011 01:58 PM by
Matthew

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.

JB
06/05/2011 10:02 PM by
JB

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

http://www.iana.org/assignments/port-numbers

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.

stephane
06/06/2011 06:31 AM by
stephane

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 :).

Rafal
06/06/2011 07:39 AM by
Rafal

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
06/06/2011 11:51 AM by
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
06/06/2011 11:52 AM by
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.

Robert
06/06/2011 12:50 PM by
Robert

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

Fitzchak Yitzchaki
06/06/2011 06:07 PM by
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.

James
06/08/2011 08:55 AM by
James

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
06/08/2011 08:36 PM by
Fitzchak Yitzchaki

@James,
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="*"/>
Comments have been closed on this topic.