$OpenBSD: README,v 1.3 2012/04/22 11:41:55 ajacoutot Exp $

+-----------------------------------------------------------------------
| Running railo-4.0.2.002 on OpenBSD
+-----------------------------------------------------------------------

Configuring Tomcat to support Railo
===================================
Railo is a Java-based CFML engine. It runs as a servlet in a container;
this package is designed to work with the Apache Tomcat servlet container,
you will need to make a few configuration changes to tomcat to use it.
If you have not yet modified Tomcat's configuration, this readme includes
a patch which can be used:

	# patch -d /var/tomcat/conf < \
	    /usr/local/share/doc/pkg-readmes/railo-4.0.2.002

Then skip to the next section in this file, "Starting the service
and online configuration".

If you need to edit manually, Tomcat's /var/tomcat/conf/web.xml file
should have these changes:

- Add lines after the first <?xml...?> line at the top of the file, so it
looks like this:

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE root [
    <!ENTITY railo SYSTEM "./web-railo.xml" >
]>

- Towards the bottom of web.xml, add the CFML-related file extensions
to the <welcome-file-list> section:

	<welcome-file-list>
	    <welcome-file>index.cfm</welcome-file>
	    <welcome-file>index.cfml</welcome-file>
	    <welcome-file>index.html</welcome-file>
	    <welcome-file>index.htm</welcome-file>
	    <welcome-file>index.jsp</welcome-file>
	</welcome-file-list>

- Add "&railo;" at the bottom of the </web-app> section to include the
"railo" xml entity defined above. This just includes the contents of the
web-railo.xml file containing the CF-related settings.

	&railo;
	</web-app>

Starting the service and online configuration
=============================================

- Start/restart tomcat:

	/etc/rc.d/tomcat restart

- Connect to http://localhost:8080/. If all goes well you should see the
default Railo homepage including a couple of samples and links to the
admin pages.

- Connect to the admin pages and set passwords:

	http://localhost:8080/railo-context/admin/server.cfm
	http://localhost:8080/railo-context/admin/web.cfm

- You can add pages to /var/tomcat/webapps/ROOT to be used for "localhost".
Additional host configurations can be added to /var/tomcat/conf/server.xml.
Use the localhost configuration as a template; the _tomcat user will need to be
able to write to <appBase>/ROOT/WEB-INF, so set ownership and permissions
accordingly.

- Log files are kept in several locations. Consult them if things don't work
as expected, and don't forget to rotate/archive them as appropriate.

	/var/tomcat/logs
	/var/tomcat/railo/server-config/railo-server/context/logs
	/var/tomcat/railo/web-config/*/logs (various dirs, per-context)

Patch to unmodified Tomcat web.xml
==================================

--- web.xml.orig	Fri Apr 20 13:16:35 2012
+++ web.xml	Fri Apr 20 16:06:21 2012
@@ -1,4 +1,8 @@
 <?xml version="1.0" encoding="ISO-8859-1"?>
+<!DOCTYPE root [
+    <!ENTITY railo SYSTEM "./web-railo.xml" >
+]>
+
 <!--
   Licensed to the Apache Software Foundation (ASF) under one or more
   contributor license agreements.  See the NOTICE file distributed with
@@ -4275,9 +4279,12 @@
   <!-- to use within your application.                                       -->
 
     <welcome-file-list>
+        <welcome-file>index.cfml</welcome-file>
+        <welcome-file>index.cfm</welcome-file>
         <welcome-file>index.html</welcome-file>
         <welcome-file>index.htm</welcome-file>
         <welcome-file>index.jsp</welcome-file>
     </welcome-file-list>
 
+&railo;
 </web-app>
