Red5 Trunk Development - Revisited

So, I know I just posted about using the latest version of Red5 two days ago, but I feel like I was a bit brief on the subject and that there's much more to cover. It is my experience that a lot can go wrong in using Red5, so it's better to write a post that's more exhaustive than thin. Anyways, let's dive into it.

Comparing Red5 Trunk to 0.7:
There are a lot of differences in using the latest trunk versus using previous releases. The latest trunk (as of the time of this post's writing, revision 3332) utilizes the concept of "distributions," allowing you as a user to create as many Red5 servers as you can put your mind to. When reviewing the build.xml file, you should see a build target called "dist". This is the default target of the build file in Ant. When you issue "ant" from command line in this folder, the "dist" target will be called. (Likewise, you can call "ant dist" from command line, but it achieves the same result.)

Before going over what "dist" does, we need to do some brain washing. In 0.7 and before, when you need to start Red5, you go to Red5's home directory and call either the red5 or the red5-debug script. In the trunk, if you try doing this, you will be rewarded with tons of errors. Why? Because Red5 Trunk is meant to be started as a distribution, not as its own stand alone server. What does this mean for you? Well, firstly you need to understand this so-called concept of distributions.

Ok, now we can cover the Ant "dist" target. The "dist" target relies on one other target, the "jar" target. The JAR target does the following:

1. Calls Ivy to start downloading the dependencies of Red5. Using Ivy is beyond the scope of this tutorial, but basically here's what happens. Red5 has declared that it depends on certain external JAR files that do not natively exist in the repository. Ivy contacts web sites and downloads the JAR's that Red5 needs. They are downloaded to a folder on your computer (usually a folder named .ivy2, its location varies based on your OS) called the Ivy "cache," then they are copied to the Red5/lib folder. You need to have internet access the first time you try and compile Red5 for this reason. Red5 won't compile if it can't get the JAR's it needs.
2. Compiles all of the Java source files located in the Red5/src folder to the Red5/bin folder. If you can't see why this is necessary, you need to learn a whole lot more about Java.
   
3. It then creates a JAR archive of Red5 with a manifest file declaring some attributes about the version and other things such as the Red5's classpath. The JAR file is output to Red5/red5.jar.
   

After all of this is done, the "dist" target is called, as you'd expect. The "dist" target copies all of Red5's essential files to a folder specified by the "dist.dir" property declared up at the top of the build.xml file in the base directory. As you can see, "dist" simply creates your distribution of Red5. Why is this important?

Distributions allow you to do a whole lot. Let's talk about some of the advantages of using distributions. First, let's say you're working on Red5 and you believe you found a new way to handle connections that would be a lot faster than the old way. (This is actually something that happened, by the way) You open up Eclipse to work on the Red5 source code, and create a new class: "org.red5.server.adapter.MultiThreadedApplicationAdapter". To test it, you would create a few distributions of Red5 by modifying the "dist.dir" property in the build.xml file. You could create the old version in a folder called "dist_old_way" and the new version employing MultiThreadedApplicationAdapter in a folder named "dist_new_way". To do this, you'd edit the "dist.dir" property in the Red5/build.xml file from this:

<property name="dist.dir" value="dist"/>

To this:

<property name="dist.dir" value="dist_old_way"/>

After doing so, you'd issue "ant" from command line in the Red5 home directory. This would create your distribution in the "dist_old_way" directory. Likewise, you'd create the "dist_new_way" distribution. You'd then start the 'old way' distribution by running the red5-bootstrap script in the directory you specified, ie: "dist_old_way/red5-bootstrap.sh" or "dist_old_way/red5-bootstrap.bat". It would start the server, you'd do some time tests, then create the new distribution with your modifications in the "dist_new_way" directory and run some tests against it. You'd then find out that MultiThreadedApplicationAdapter is much faster than ApplicationAdapter.

Another useful feature of using distributions is allowing for versioning of your distributions. As suggested by a member of the Red5 team, you could create distributions in directories like "dist_3324" and "dist_2345" to test features against different distributions. Ok, I believe that we've covered the concept of distributions quite thoroughly, so we'll move on to the next topic.

*Note: In Red5's default configuration, you can not run more than one instance of Red5 on one machine at a time. If you get a "BindException" when running your startup script, you probably have another Red5 running in the background. Be sure to shut it down. There are ways to allow for more than one Red5 instance on one machine, but it involves modifying ports that Red5 uses and that concept is beyond the scope of this tutorial but will hopefully be covered in a future tutorial by me or another Red5 user.

*Another Note: Do not try starting Red5 from the scripts contained in the base directory. They won't work. Don't do it! DON'T! Remember, you're using distributions now! Start Red5 from the scripts in the distribution's base folder. This is to save you weeks of frustration that I was unlucky enough to face.

red5-bootstrap vs. red5-debug, what the heck?
In the latest trunk, you may have noticed the new red5-bootstrap script. This is new since Red5 0.7 and I will explain it now. A lot of people including me have had problems using the standard red5 and red5-debug scripts to start the server in the latest trunk version. This is due to a problem with Red5's way of dealing with classpath entities. For more information on it, I suggest you post to the mailing list (red5@osflash.org). I myself have no idea when this will be fixed or if it is even being planned for being fixed. All that I know is that it's an issue with creating distributions. There is also a bug with the current Red5, again at the time of this post's writing, that creates problems when including required JAR files in a web application's /lib folder. I myself have not experienced this problem in particular, but that is because I put all of my required libraries, such as Hibernate libraries, inside of my distribution's global /lib folder. Let's just say I'm a little paranoid about errors and if I can avoid them, at all costs I will. Again, I'm not even sure if this is a bug or not, but I have seen posts in the mailing list concerning this many times.

So, all you really need to know is that the red5 and red5-debug scripts won't find JARs that you placed in your distribution's /lib folder. red5-bootstrap will find them. Here's a really handy rule, always favor red5-bootstrap. Again, it will save you hours of frustration. However, when you run the script, you may notice something. The red5-bootstrap script issues no output to command line when you open it up. It either says "Starting Red5 (org.red5.server.Bootstrap)..." or nothing at all and that's it. Let's address this.

Red5 is running invisibly?
It may appear after trying to run the red5-bootstrap script that Red5 is doing nothing or it's suspended. Well, there's no need to fear, the output is just going somewhere else, not to your console. The latest Red5 (rev 3332) addresses a problem that has been long existent in Red5. For the longest time, Red5 had problems with using common logging utilities in Java such as log4j and sl4j. This has now been fixed. I myself am not currently using a logging utility so I can't tell you how to get up and running with that, and besides, that's beyond the scope of what we're doing here.

For now, let's modify the red5-bootstrap script in your distribution's directory. Alternatively, you can edit the master script in the Red5 base directory to ensure that all future distributions you create have the changes applied to them and you won't have to change red5-bootstrap every time you create a new distribution. It's your call what to do, but open the red5-bootstrap script of your choosing, relative to your operating system. IE: For Windows, open the red5-bootstrap.bat file in Notepad, for other operating systems open the red5-bootstrap.sh file in a text editor. The last line in this script is the one of interest. It should read somewhat as so: (note, it will look different depending on whether you're editing the .bat or .sh script)

red5-bootstrap.bat file:
%RED5_HOME%\red5.bat 1>%RED5_HOME\log\stdout.log 2>%RED5_HOME%\log\stderr.log
red5-bootstrap.sh file:
exec $RED5_HOME/red5.sh 1>$RED5_HOME/log/stdout.log 2>$RED5_HOME/log/stderr.log

What you need to do now is change the last line of the script. You should change the script to simply read as so:

red5-bootstrap.bat file:
%RED5_HOME%\red5.bat
red5-bootstrap.sh file:
exec $RED5_HOME/red5.sh

After doing that, shut down Red5 if it is running, then start it with red5-bootstrap in your distribution's directory. Note: if you modified the master red5-bootstrap script in the Red5 base directory, you need to copy it to your existing distributions' folders. You should see output in your console. If you are still not seeing any output, make sure that you have the following entry in your distribution's conf/logback.xml file:

<appender name="CONSOLE"
class="ch.qos.logback.core.ConsoleAppender">
<layout class="ch.qos.logback.classic.PatternLayout">
<Pattern>[%p] [%thread] %logger - %msg%n</Pattern>
</layout>
</appender>

And that it's referenced in the "root" element in that file as so:

<root>
<level value="DEBUG" />
<appender-ref ref="CONSOLE" />
<appender-ref ref="FILE" />
<appender-ref ref="ERRORFILE" />
</root>

If you're still having problems with this, comment back to this post and/or post to the mailing list.

Changes in an application's web.xml file since 0.7:
Another thing that has changed since 0.7 is in the way that your web-app definition file ("web.xml") is constructed. There have been a few major changes in the way that this file defines applications that will throw major errors and exceptions on startup. If you are seeing some very strange errors around startup of a distribution of Red5, validate that all of your applications' web.xml files have been updated if you are migrating them to the trunk server. For more information on how these files should be constructed, post to the mailing list. I myself am not too familiar with modifying these files, excepting of course the modification of the webAppRootKey property.

Hopefully this has been very helpful in getting set up to work with the latest Red5. If you have any questions or notice an error, please comment back to this post. For some of the concepts covered here, such as the web.xml file, please send messages to the mailing list, as I'm pretty unfamiliar with the modification of that file. Long live Red5!

*Note: When I refer to something as a script, IE: "the red5-debug script", I am referring to a file with the extension of either *.bat or *.sh