@header@

Specific Server Installation Details

Pebble has been tested on a variety of web/application servers and some of these require additional/alternative installation steps. If you have successfully deployed Pebble on other servers, please send us an e-mail and we'll update this page.

Tomcat 4.1.x/5.0.x/5.5.x

Please see the getting started instructions that are written with Tomcat in mind.

JBoss 3.x/Tomcat 4.1.x

Here's a summary of the steps required to get Pebble working, based on a default installation and assuming that you are deploying the web application to a web context called /blog.

Copy the expanded WAR file to the $JBOSS_HOME/server/default/deploy directory, in a subdirectory called blog.
Edit the $JBOSS_HOME/server/default/conf/login-config.xml file to specify which login-module to use by adding the following section.

      <application-policy name="blog">
         <authentication>
           <login-module code="org.jboss.security.auth.spi.UsersRolesLoginModule" flag="required" />
         </authentication>
      </application-policy>

Create a users.properties file underneath the WEB-INF/classes directory to specify the users for this webapp.

      # users.properties file has user=password pairs
      simon=password

Create a roles.properties file underneath the WEB-INF/classes directory to map users to roles for this webapp.

      # roles.properties has user=role,role2,roleN pairs
      simon=blog-owner,blog-contributor

Create a jboss-web.xml file underneath the WEB-INF directory to specify the security domain.

      <jboss-web>
        <security-domain>java:/jaas/blog</security-domain>
      </jboss-web>

All that these additional steps do is specify which authentication mechanism you want to use so that navigating to a protected page results in an authentication request.

Resin 2.1.x

Here's a summary of the steps required to get Pebble working on a default installation of Resin 2.1.x, assuming that you plan to install it to a web context of /blog.

As with Tomcat, you can either extract the Pebble WAR file underneath the $RESIN_HOME/webapps directory, or anywhere on your disk.
Assuming that you've extracted Pebble somewhere other than the webapps directory, open up the $RESIN_HOME/conf/resin.conf file and insert the following XML before the closing host tag, changing the id and app-dir attributes as necessary. In addition to this, you can set up the users that you need for your blog. In the example below is a single user that is both a blog-owner and blog-contributor.
```
      <web-app id='blog' app-dir='/Users/simon/pebble'>
        <authenticator>
          <class-name>com.caucho.http.security.XmlAuthenticator</class-name>
          <init-param user='simon:password:blog-owner,blog-contributor'/>
        </authenticator>
      </web-app>
```

Resin 3.0.x

Here's a summary of the steps required to get Pebble working on a default installation of Resin 3.0.x, assuming that you plan to install it to a web context of /blog. Essentially, deploying a webapp on Resin 3.0.x is the same as deploying to Resin 2.1.x although it uses a slightly different syntax.

As with Tomcat, you can either extract the Pebble WAR file underneath the $RESIN_HOME/webapps directory, or anywhere on your disk.
Assuming that you've extracted Pebble somewhere other than the webapps directory, open up the $RESIN_HOME/conf/resin.conf file and insert the following XML before the closing host tag, changing the id and document-directory attributes as necessary. In addition to this, you can set up the users that you need for your blog. In the example below is a single user that is both a blog-owner and blog-contributor.
```
      <web-app id='blog'
        document-directory='/Users/simon/pebble'>
        <authenticator>
          <type>com.caucho.server.security.XmlAuthenticator</type>
          <init>
            <user>simon:password:blog-owner,blog-contributor</user>
            <password-digest>none</password-digest>
          </init>
        </authenticator>
      </web-app>
```
Finally, you'll need to remove the following files from /WEB-INF/lib.
- jstl.jar
- standard.jar

Jetty 4.2.x

Here's a summary of the steps required to get Pebble working on a default installation of Jetty 4.2.x.

Extract the WAR file to the $JETTY_HOME/webapps directory.

Define the security realm in the $JETTY_HOME/etc/jetty.xml file (the example below uses a simple username/password pair in plain text).

      <Call name="addRealm">
        <Arg>
          <New class="org.mortbay.http.HashUserRealm">
            <Arg>Pebble Realm</Arg>
            <Put name="simon">password</Put>
            <Call name="addUserToRole">
              <Arg>simon</Arg>
              <Arg>blog-owner</Arg>
            </Call>
            <Call name="addUserToRole">
              <Arg>simon</Arg>
              <Arg>blog-contributor</Arg>
            </Call>
            <Put name="anotheruser">password</Put>
            <Call name="addUserToRole">
              <Arg>anotheruser</Arg>
              <Arg>blog-contributor</Arg>
            </Call>
          </New>
        </Arg>
      </Call>

If you are deploying Pebble to Jetty, it is important that you do define a security role before starting up the server. If you don't, you'll get the error page (indicating that "something has gone wrong") when you try to access a secure page.

Jetty 5.0.x

Follow the steps for Jettey 4.2.x and then, before starting, remove the following files from /WEB-INF/lib.

commons-logging-api.jar
commons-logging.jar
log4j.jar

BEA WebLogic 8.1

The normal installation instructions should be followed, with the exception that all security role names shouldn't contain the hyphen character. The easiest way to do this is open the web.xml file and search/replace blog-owner for blog_owner and blog-contributor for blog_contributor. These new role names should then be used when setting up users in the security realm.

Orion 1.x and 2.x

Unfortunately, at the time of writing, deployment to Orion is not supported due to a number of bugs in their implementation of the Servlet specification.

@footer@