diff --git a/docs/images/db-connection-error.png b/docs/images/db-connection-error.png new file mode 100644 index 0000000000..85917a8dbc Binary files /dev/null and b/docs/images/db-connection-error.png differ diff --git a/docs/images/no-tables-found.png b/docs/images/no-tables-found.png new file mode 100644 index 0000000000..acaed1851e Binary files /dev/null and b/docs/images/no-tables-found.png differ diff --git a/docs/images/roller-home.png b/docs/images/roller-home.png new file mode 100644 index 0000000000..ff0bed73a3 Binary files /dev/null and b/docs/images/roller-home.png differ diff --git a/docs/images/roller-install-guide-tomcat-deploy.png b/docs/images/roller-install-guide-tomcat-deploy.png new file mode 100644 index 0000000000..dc28dbe8a3 Binary files /dev/null and b/docs/images/roller-install-guide-tomcat-deploy.png differ diff --git a/docs/images/roller-install-guide-tomcat.png b/docs/images/roller-install-guide-tomcat.png new file mode 100644 index 0000000000..487abfffb5 Binary files /dev/null and b/docs/images/roller-install-guide-tomcat.png differ diff --git a/docs/roller-install-guide.adoc b/docs/roller-install-guide.adoc new file mode 100644 index 0000000000..2deae22cf6 --- /dev/null +++ b/docs/roller-install-guide.adoc @@ -0,0 +1,855 @@ += Installation Guide +Apache Roller Weblogger +:toc: +:sectnums: +:imagesdir: ./images + +== Overview + +This document describes how to install the Apache Roller Weblogger +software. It explains what you need to install first, how to download +Roller, how to configure Roller and how to install it to your existing +Java application server and relational database. + +=== Copyright and trademark information + +The contents of this document are subject to the terms of the Apache +Software License. + +All trademarks within this document belong to legitimate owners. + +=== Feedback + +Please direct any comments or suggestions about this document to the +Roller User Mailing list. For more information on the Roller mailing +lists please refer to the following page: + +Roller Mailing Lists - +https://cwiki.apache.org/confluence/x/ZYk[_https://cwiki.apache.org/confluence/x/ZYk_] + +=== Acknowledgments + +The original version of this document was written by Dave Johnson. The +document is currently written and updated by the Apache Roller project +of the Apache Software Foundation. + +== Securing Roller + +Security should be top-of-mind when setting up any web site, even one +that is on a private network and internal to your organization. Here are +some recommendations for keeping your Roller installation secure: + +* *Perform Roller installation on a secure network*. When you are +installing Roller it is possible for other users to interfere with your +installation. If other users have access to the server, one of them +could create the admin account before you do. So, when you install +Roller, do so on a server that cannot be accessed by others. +* *Do not allow open registration of new users*. Roller can offer a +registration link so that new users can register themselves, but this +feature is turned off because it is not safe to allow just anybody to +register for an account on your blog server. If you want to turn it on, +login as an administrative user, go to Roller’s Server Administration +page and enable the *Allow New Users* option. +* *Enable HTML Sanitization*. If you cannot trust the webloggers who +will use your Roller site to author HTML, then you should configure +Roller to sanitize all HTML published by the system. Do this by setting +the _weblogAdminsUntrusted=true_ property in your +_roller-custom.properties_ file. +* *Do not allow HTML in comments*. Roller can allow users to write +comments in a safe-subset of HTML, but HTML use in comments is not +allowed at all because of security concerns with even a so called +safe-subset of HTML. If you want to turn it on, login as an +administrative user, go to Roller’s Server Administration page, enable +the *Allow html in comments* option and make sure the *HTML Subset +Restriction* box is checked. +* *Run Roller over SSL connection*. If you run Roller over a plain old +HTTP connection, it is possible for others to snoop your password when +you login, for example over an open WIFI network. To configure Roller to +work over SSL (i.e., using https:// URLs), first modify the web.xml +located in the Roller WAR (WEB-INF folder), uncommenting the + element and following the instructions given in +that file above that element. Next, follow your servlet container’s +documentation for setting up SSL +(http://tomcat.apache.org/tomcat-7.0-doc/ssl-howto.html for Tomcat, for +example.) Then redeploy Roller and confirm that pages containing secure +data such as the login page and new user registration page are available +only via https:// URLs. + +== Ready to roll? + +First, let’s make sure you have everything you need to install and run +Roller. + +Roller is a database-driven Java web application. To run it you need +Java, a Java Servlet container such as Tomcat, a connection to a +database such as MySQL and optionally a connect to a mail server. More +specifically, here’s what you need to install and run Roller: + +* *Java Development Kit*, specifically the Java 2 SE 1.6 JDK or more +recent. The computer on which you install Roller should already have the +JDK installed and configured. +* *Java EE 6 Application Server*, or more specifically a Servlet +container that supports at least the Servlet 2.4 API. Hereinafter, we’ll +just call this your _server_. Roller has traditionally worked best on +Tomcat and Tomcat only, but Roller 6.0.0 is known to run on: +** Tomcat 8 +** Jetty 9 +* *Relational database* such as MySQL or Apache Derby. Roller stores +blog entries, comments, bookmarks and almost all other data in a +relational database accessed via the Java Persistence API 2.0. +PostgresSQL, MySQL and Derby are best supported but Roller. Roller also +includes database creation scripts for DB2, HSQL-DB, Microsoft SQL +Server and Oracle but these have not been tested recently. +* *(Optional) An SMTP mail server*. Roller can send email notifications +for comments and other events via the JavaMail and Activation APIs. +* *Roller installation file*. The Roller installation file contains the +Roller WAR file, ready to deploy to your server, plus Roller license +files, README and documentation. Unpack using either file based on a +compression method your operating system supports: +** roller-release-6.0.0-standard.zip +** roller-release-6.0.0-standard.tar.gz + +This step can also be done after deployment and determination that you +would like themes other than the defaults available available, just +modify the WAR and redeploy on your servlet container. + +* *(Optional) Additional blog themes*. Roller comes pre-packaged with +several blog themes (templates) for you to choose and optionally +customize for each blog you create. You may wish to add additional +themes to the Roller WAR file so they will be available to choose from +when you deploy the application. To do this, just open the Roller WAR +and add the theme to the "themes" folder located at the top level of +the WAR. Google and/or check the non-Apache +resources section of the Roller wiki page +(https://cwiki.apache.org/confluence/display/ROLLER/Roller+Wiki) for any +externally available themes—external themes are not supported by the +Roller team, however. + +== Download and un-package Roller + +Download the Apache Roller release file from +http://roller.apache.org/[http://roller.apache.org]. If you’re a Windows +user download the .zip file and use your favorite ZIP program to unzip +the release into a directory on your computer’s disk. Unix users can +download the .tar.gz file and use GNU tar to un-package. + +=== Installation directory layout + +Once you’ve unpackaged the files you’ll find a directory structure like +this: + +---- +README.txt + +LICENSE.txt + +NOTICE.txt + +docs/ + + roller-install-guide.pdf + + roller-user-guide.pdf + + roller-template-guide.pdf + +webapp/ + + roller.war +---- + +The _LICENCE.txt_ and _NOTICE.txt_ files contain the Apache Software +License and other legal notices related to the release. The _README.txt_ +file just points to the documentation in the _docs_ directory. + +https://cwiki.apache.org/confluence/display/ROLLER/Roller+Wiki + +== Prepare your database for Roller + +Before you can install Roller you’ll probably need to some work to +prepare your database. You’ll need to create a place to put the Roller +tables; some call this a table-space and we refer to it as a _database_ +in this installation guide. You’ll need to create a database for Roller, +or get your database administrator to do it for you. You also need to +have a JDBC driver for your database of choice, but we’ll cover that +later. + +=== Create a database for Roller + +If you’re luck enough to have your own database administrator, ask them +to setup a database for Roller. When they are done, ask them to provide +you with this information, you’ll need it later: + +* Username and password for connecting to database +* JDBC connection URL for database +* JDBC driver class name + +If you don’t have a database administrator then you’ll have to refer to +the documentation for your database and do it yourself. You need to +create a database for Roller, protected by username and password. For +example, if you’re using MySQL you might do something like this (be sure +to use a different username and password from the scott/tiger below): + +---- +% sudo service mysql start + +% mysql -u root -p + +password: ***** + +mysql> create database rollerdb DEFAULT CHARACTER SET utf8 DEFAULT +COLLATE utf8_general_ci; + +mysql> grant all on rollerdb.* to scott@`%' identified by `tiger'; + +mysql> grant all on rollerdb.* to scott@localhost identified by `tiger'; + +mysql> exit; +---- + +If you’re using Derby: + +---- +% ij + +ij> connect `jdbc:derby:/path/to/new/MYROLLERDB;create=true'; + +ij> quit; +---- + +For PostgreSQL: + +---- +%sudo -u postgres psql postgres + +postgres=# create user scott createdb; + +postgres=# \du (see list of users and roles) + +postgres=# \password scott + +Enter new password: ????? + +postgres-# \q + +%createdb -h localhost -U scott -W pgsqlroller -E UTF8 +---- + +=== MySQL and Oracle considerations + +Based on our experience supporting MySQL, we have the following +recommendations: + +* For MySQL, make sure that TCP/IP networking is enabled. +* For MySQL, UTF-8 must be enabled for your database, as done in the +"create database rollerdb" command above or server-wide +(http://dev.mysql.com/doc/refman/5.6/en/charset-applications.html). ++ +If a non-UTF8 database has already been created you can switch the +database to UTF-8 as follows providing the tables have *not* already +been created: ++ +---- +ALTER DATABASE roller DEFAULT CHARACTER SET utf8 COLLATE +utf8_general_ci; +---- +* For Oracle users, use the 10g (10.1.0.2 higher) drivers which should +be packaged as ojdbc14.jar, even if operating on Oracle 9 server. +* See the server specific sections to information on where to place the +JDBC driver jars. + +== Deploy Roller to Tomcat + +Deploying Roller to the Tomcat servlet container involves creating a +Roller configuration file, adding some jars to Tomcat and then deploying +the Roller WAR file. + +You are expected to install and configure Apache Tomcat before you +attempt to install Roller, and be aware of how to deploy a WAR archive +on Tomcat. Refer to the Tomcat documentation linked from this page for +more information: http://tomcat.apache.org/[_http://tomcat.apache.org_] + +=== Tomcat: Create Roller Configuration File + +There are a variety of ways to configure Roller and Tomcat and here +we’ll explain the easiest route: providing database and mail connection +information directly to Roller via the Roller configuration file. + +*Create the Configuration File* + +For most settings, Roller can be configured from its own web console. +But for some startup-properties and advanced configuration options you +must set properties in an override file called: + +roller-custom.properties + +That is a simple Java properties file, a text file that overrides +settings defined in Roller’s internal __roller.properties __file. To +configure Roller you look at Roller’s internal properties file, decide +which properties you need to override and then set those in your +_roller-custom.properties_ file. + +The precise roller.properties file your distribution is using is located +in /WEB-INF/classes/ org/apache/roller/ weblogger/config/ within the +roller.war file. It is also viewable online at +http://svn.apache.org/viewvc/roller/trunk/app/src/main/resources/org/apache/roller/weblogger/config/roller.properties, +click the "(view)" button at a revision just prior to the Roller +release you’re using. We encourage you to look through this file to +determine other properties you may wish to override, but we’ll get you +started right here and now with a simple example that shows you the +minimum startup, database, and mail configuration settings that you need +to run Roller. You’ll need to alter this information using settings +appropriate for your filesystem, database, and mail server. (Also note +the database and mail configuration shown below will be done differently +if you’re using JNDI, which will be discussed in the next section. JNDI, +in particular, is presently required if your mail SMTP server requires +authentication.) + +Example: _roller-custom.properties_ file +---- +installation.type=auto + +mediafiles.storage.dir=/usr/local/rollerdata/mediafiles + +search.index.dir=/usr/local/rollerdata/searchindex + +log4j.appender.roller.File=/usr/local/rollerdata/roller.log + +database.configurationType=jdbc + +database.jdbc.driverClass=com.mysql.jdbc.Driver + +database.jdbc.connectionURL=jdbc:mysql://localhost:3306/rollerdb?autoReconnect=true&useUnicode=true&characterEncoding=utf-8&mysqlEncoding=utf8 + +database.jdbc.username=scott + +database.jdbc.password=tiger + +mail.configurationType=properties + +mail.hostname=smtp-server.example.com + +mail.username=scott + +mail.password=tiger +---- + +The _installation.type=auto_ property tells Roller to operate in +automatic installation mode. In this mode Roller will provide very +detailed error output to help you debug database connection problems. If +Roller finds that the database exists but its tables are not, it will +offer to run the database creation scripts. If find finds that the +tables are there, but they are not up-to-date Roller will offer to +upgrade them for you. Once your Roller installation is complete and you +are ready to go "live" then you should set __installation.type=manual__. + +The above sample __roller-custom.properties__ uses a MySQL connection. +It shows the MySQL JDBC driver class name, an example MySQL connection +URL and username/password settings for the mail connection: + +If you’re using Derby, database configuration properties +similar to the following will be more appropriate. Note authentication +is not used by default with Derby (any username and password provided +below will be accepted), see +http://db.apache.org/derby/docs/10.2/tuning/rtunproper27467.html on how +to require authentication with Derby. The username configured below will +be the table owner used when the Roller installation process later +creates the database tables. + +---- +database.configurationType=jdbc + +database.jdbc.driverClass=org.apache.derby.jdbc.EmbeddedDriver + +database.jdbc.connectionURL=jdbc:derby:/path/to/new/MYROLLERDB + +database.jdbc.username=app + +database.jdbc.password=app +---- + +For PostgreSQL: + +---- +database.configurationType=jdbc + +database.jdbc.driverClass=org.postgresql.Driver + +database.jdbc.connectionURL=jdbc:postgresql://localhost:5432/pgsqlroller + +database.jdbc.username=scott + +database.jdbc.password=tiger +---- + +*Alternative Authentication Options* + +The above instructions rely on Roller’s default user authentication +mechanism, i.e., using a Roller-provided database table (roller_user) to +store usernames and encrypted passwords. Roller provides other +authentication options defined under the "authentication.method" +setting in the roller.properties file: OpenID, OpenID/DB combination, +and LDAP +(https://cwiki.apache.org/confluence/display/ROLLER/Roller+5.1+with+LDAP). +These authentication methods are used less frequently so should be +tested more thoroughly with your particular setup if you wish to use +them. Check the roller.properties file included in your WAR for +available options and configuration information, and consult the Roller +User’s Mailing List should you need assistance. + +Add Configuration file to Tomcat + +Place the configuration file into the Tomcat lib directory so that it is +on the Tomcat classpath and therefore available to Roller. + +=== Using Server-provided database & mail resources (optional) + +It’s easiest to setup your Roller for Tomcat database connection using +the `jdbc' approach and the mail connection using `properties' but in +some cases you might want to use the datasource and/or mail session +resources provided by your application server instead. For +authentication-requiring mail connections like Google’s Gmail service, +JNDI is presently required. For databases, you might use JNDI to take +advantage of the database connection pool management that is built into +your server. Or, your boss might want everything to be managed via your +server’s Admin Console. No matter the reason, it’s easy to do in Roller. + +Here, you omit the _roller-custom.properties_ database and mail +configuration given in the previous section and replace it with just: + +---- +installation.type=auto +mediafiles.storage.dir=/usr/local/rollerdata/mediafiles +search.index.dir=/usr/local/rollerdata/searchindex +log4j.appender.roller.File=/usr/local/rollerdata/roller.log + +database.configurationType=jndi +database.jndi.name=jdbc/rollerdb +mail.configurationType=jndi +mail.jndi.name=mail/Session + +---- + +The _database.configurationType=jndi_ setting tells Roller to look up +its datasource via Java Naming and Directory Interface (JNDI). Roller +will look for a datasource with the JNDI name _jdbc/rollerdb_. You must +set that datasource up in your server. + +The _mail.configurationType=jndi_ setting tells Roller to look up it’s +mail sessions via JNDI. Roller will look for a mail session provider +with the JNDI name _mail/Session_. You must set that provider up in your +server. Let’s discuss how to do that on Tomcat. + +Setting up database and mail resources on Tomcat + +There are a couple of different ways to setup database and mail +resources on Tomcat. One way is to provide a Context Configuration file. +Here’s how to do this on Tomcat. + +Before you deploy Roller to Tomcat, create a new Context Configuration +file in the installation directory _webapp/roller/META-INF_. You’ll find +an example configuration file there, shown below. Rename it from +_context.xml-example_ to _context.xml_ and substitute the correct values +for driverClassName, url, username, password in 'jdbc/rollerdb' Resource and mail.smtp.user +password in 'mail/Session' Resource. + + +---- + + + + +---- + +The Java mail properties listed above are defined here: +https://javamail.java.net/nonav/docs/api/com/sun/mail/smtp/package-summary.html. +Note the email account defined above will appear in the "From:" line +of notification email messages sent to blog owners (and, if they select +"Notify me of further comments", blog commenters) so take care not to +use an email account you wish to keep private. + +Another method is to the add the configuration to the Tomcat server.xml +file under the correct host value already present in the file. (The +Tomcat project advises against this method as it requires restarting the +server whenever changes are made to this file, see +http://tomcat.apache.org/tomcat-7.0-doc/config/context.html#Defining_a_context.) +For example, with the same mail connection as above: + + +---- + + + + + + + +---- + +=== Tomcat: Add JDBC Driver and JavaMail API Files + +You will also need to place some additional jars in the Tomcat _lib_ +directory: + +* **JDBC Driver Jars. **Add the appropriate JDBC driver jars to the +Tomcat classpath. Once they are in your classpath, Roller’s database +subsystem will be able to find and use them. Download them from your +database vendor/provider and place them in Tomcat’s _lib_ directory. +* **Java Mail and Activation. **Tomcat does not include the Java Mail +and Activation jars. Even if you do not plan to use email features, you +must download those jars and place them in Tomcat’s classpath. Download +them from Oracle (https://java.net/projects/javamail/pages/Home) and +place them in Tomcat’s _lib_ directory. + +=== Tomcat: Set URI Encoding + +Roller supports internationalization (I18N), but on Tomcat some +additional configuration is necessary. You must ensure that Tomcat’s URI +encoding is set to UTF-8. You can do this by editing the Tomcat +configuration file conf/server.xml and adding URIEncoding=”UTF-8” to +each connector element, as shown below: + +---- + +---- + +And make sure you do this for _every_ connector through which you use +Roller. For example, if you use the AJP connector or HTTPS connector you +need to add the URIEncoding="UTF-8" attribute to those connectors as +well. + +=== Tomcat: Deploy Roller + +Refer to the Tomcat documentation for information on the various ways to +deploy a WAR. By renaming the Roller WAR to roller.war and placing it in +the webapps directory of a running Tomcat instance, you should be able +to access Roller at http://localhost:8080/roller (the /roller portion +comes from the name of the WAR.) Another way to do this is to use the +Tomcat Manager application, which you can reach at the following URL +http://localhost:8080/manager. Once you are there, you’ll see something +like this: + +image::roller-install-guide-tomcat.png[] + +On the manager screen above, scroll down until you see the *Deploy* +section, see below: + +image::roller-install-guide-tomcat-deploy.png[] + +Enter the context path at which you would like to see Roller, above we +use _/roller_. Enter the full path to the Roller WAR file, in the +webapps directory of the Roller installation and click *Deploy* to +deploy Roller. + +Finally, navigate to http://localhost:8080/roller to complete the +installation. + +== Getting started with Roller + +You’re not quite done with the installation process, but now you’re +ready to start using Roller, so we’ll walk you through getting started, +registering a user and setting up a blog. We’ll also discuss briefly +what happens when there is an error. + +=== Navigate to Roller and finish the install + +Navigate to Roller, if you are using a default Tomcat or Glassfish +installation then then URL of Roller is probably +http://localhost:8080/roller. You will see either a web page of error +messages, a web page offering to create database tables for you or web +page asking you to complete the installation by registering an admin +user and creating a front-page blog. First, let’s talk about what +happens when things go wrong. + +image::db-connection-error.png[] + +If there’s a problem with your database configuration, Roller will +display a page or error messages to help you diagnose the problem. It’s +possible that you entered the wrong JDBC driver class name, connection +URL, username or password. Or perhaps your database is not running. Use +the information provided to determine what is wrong, fix it and then +redeploy Roller. + +*Automatic tables creation* + +If your database configuration is good but Roller cannot find its +database tables, then Roller will offer to create those pages +automatically for you. If you give the go-ahead, Roller will run the +appropriate database creation script for your database and then show you +the results. You can then proceed to the next step to setup your first +user account and weblog. + +image::no-tables-found.png[] + +=== Register a user and create a weblog + +If Roller starts up fine but doesn’t find a front-page weblog then it +will display the Completing Your Installation below that explains how to +register your first user, create your first weblog and setup your site’s +front page. + +image::roller-home.png[] + +You have to decide what you want as the front-page of your Roller site. +If you are using Roller to run your personal weblog, then you probably +want your weblog to be the front-page of the site. In this case, create +a weblog for yourself, _don’t_ choose the front-page theme but _do_ set +your weblog as the front-page weblog for the site. + +If you are using Roller to run a community of multiple weblogs, then +you’ll probably want to display an aggregated front-page combining all +weblogs on the site. In that case, create a weblog to serve as the +front-page, set it as the front-page weblog and make sure you set the +"aggregated front-page" setting on the Server Admin page. + +*Don’t forget: Reset the _installation.type_ flag* + +Now that you’re done with the installation you should turn off Roller’s +auto-installation system. Edit your _roller-custom.properties_ file and +set _installation.type=manual_. Then restart your server or Roller so +that it accepts the new setting. + +*What’s next?* + +Once you’ve gotten Roller up and running refer to the Roller User Guide +for more information on running your Roller system and your weblog. For +information on customizing your weblog, refer to the Roller Template +Guide. If you can’t find what you want in the documentation then +subscribe to the Roller user mailing list and ask your questions there: + +https://cwiki.apache.org/confluence/display/ROLLER/Roller+Mailing+Lists + +== Configuration tips and tricks + +This section covers some tips and tricks that can help you get the most +out of Roller. It covers Roller’s Planet feed aggregator and how to +setup Roller to use server-provided resources. + +=== Setting up Roller’s Planet feed aggregator + +Roller includes a RSS/Atom feed aggregator that makes it possible to run +a site like https://blogs.oracle.com/ which provides weblogs for +thousands of writers and an aggregated front-page that displays the most +recent posts form those plus dozens of Sun bloggers from other sites +such as blogger.com, typepad.com and other services. Here’s what you +need to do. + +==== STEP 1: Create a Planet cache directory + +Roller Planet needs a cache directory in which to store the feeds it +fetches. By default, Roller Planet will put it’s cache in your home +directory under _roller_data/planetcache_. If you want to place the +cache somewhere else, you must override the planet.aggregator.cache.dir +property in your _roller-custom.properties_ file. For example: + +`cache.dir=c:\\roller_data\planetcache` + +Whether you override that property or not, *you must create the cache +directory*. Planet will not work unless the cache directory exists and +is writable by Roller. + +==== STEP 2: Enable Planet via Roller custom properties + +Enable Planet by adding the following to your _roller-custom.properties_ +file: + +---- +planet.aggregator.enabled=true + +# Tasks which are enabled. Only tasks listed here will be run. +tasks.enabled=ScheduledEntriesTask,ResetHitCountsTask,\ +PingQueueTask,RefreshRollerPlanetTask,SyncWebsitesTask + +# Set of page models specifically for site-wide rendering +rendering.siteModels=\ +org.apache.roller.weblogger.ui.rendering.model.SiteModel,\ +org.apache.roller.weblogger.ui.rendering.model.PlanetModel + +---- + + +Those property settings enable Planet and enable the Planet tasks, both +the _RefreshRollerPlanetTask_, which runs every hour and fetches all +RSS/Atom feed subsciptions, and the _SyncWebsitesTask_, which runs every +midnight and ensures that each weblog in the Roller system is +represented by a subscription in the Planet aggregator. To enable usage +of the PlanetModel in the front-page weblog, we also override the +_rendering.siteModels_ property. + +==== STEP 3: Configure Planet via Planet custom properties + +Create a new file called _planet-custom.properties_ and place it in the +same directory as your existing _roller-custom.properties_ file. In this +configuration file, add a property called __cache.dir __that points to +the directory that you’d like Planet to use for caching it’s RSS and +Atom newsfeeds. The default setting is: + +`_cache.dir=${user.home}/roller_data/planetcache_` + +Once you’ve made those property settings restart Roller and proceed to +the next step. + +==== STEP 4: Display your Planet aggregations + +You can use Roller’s UI to add external RSS/Atom feeds to the Planet +setup. To display these feeds you’ll need to do a little template +customization. The easier way to get started is to Roller’s existing +Front-Page theme. Here’s how. + +Create a weblog to server as the front-page of your Roller site. Start +with the Front-Page theme and customize it. Edit the weblog template and +look for the part that mentions PLANET-entries. Comment-out the +SITE-WIDE part and un-comment the PLANET-entries part. The double hash +"##" marks indicate a commented-out line. The code should look like +this: + +---- +## 1) SITE-WIDE entries (the default) +##set($pager = $site.getWeblogEntriesPager($since, $maxResults)) + +## 2) PLANET-entries +#set($pager = $planet.getAggregationPager($since, $maxResults)) +---- + +With that in place, your front-page will be display your Planet entries. +You can find your Planet feeds at the following URLs: + +* Main Planet feed +http://localhost:8080/roller/planetrss +* Per group feed +http://localhost:8080/roller/planetrss?group=[] + + +=== Manual table creation and upgrade + +If you would rather create your database tables yourself instead of +letting Roller do it automatically, you can. Instead of enabling +automatic installation you should disable it by putting this in your +_roller-custom.properties_ file: + +installation.type=manual + +Now you’ve got to run the database creation script. You can find the +database creation scripts in the +_webapp/roller/WEB-INF/classes/dbscripts_ directory. You’ll find a +_createdb.sql_ script for each of the databases we hope to support. + +If you are upgrading Roller, you’ll have to run the migration scripts +instead of createdb.sql. You’ll find those under the _dbscripts_ +directory too. However, the migration script should probably be run +statement-by-statement checking the database responses as you go along, +or alternatively by first removing any delete index or delete foreign +key statement that you know doesn’t exist in your database. Certain +databases like MySQL throw errors when one attempts to delete objects +such as foreign keys or indexes that don’t already exist, a specific +error type which the automated installation process is coded to ignore. + +== Upgrading Roller + +This section describes how to upgrade an existing Roller installation to +the latest release of Roller by shutting down, backing up and then +following the installation instructions with a couple of key exceptions. +But first, there is some required reading for those upgrading from +ancient versions of Roller. + +=== Backup your old Roller + +Before you get started with your upgrade, shutdown your existing Roller +install and make a backup of your Roller data. + +Backup your database to somewhere safe on your system or to a remote +file-system. Here are a couple of examples: of how to do that on various +databases: + +* On MySQL you create a dump file + +`mysqldump -u scott -p rollerdb > +/somewhere/safe/roller.dmp` + +* With PostgreSQL you can do the same thing + +`pg_dump -h 127.0.0.1 -W -U +scott rollerdb > /somewhere/safe/roller.db` + +And backup any other data. Make a copy of your Roller data directory, +i.e. the one with your Roller resources and search-index files. If you +added or modified any files within your old Roller web application +directory, then you’ll want to backup that whole directory. + +Migrating your old file uploads to the new Media Blogging system + +If upgrading from Roller 4.0 to 5.1 (5.0 already has this configuration +done), when you first start Roller 5.1 it will migrate your old file +uploads to the new Media Blogging system. If this is to work properly +you *MUST* ensure that the three properties below are set correctly +before you start Roller 5.0/5.1 for the first time. + +---- +# The directory in which Roller 5.x will upload files + +mediafiles.storage.dir=$\{user.home}/roller_data/mediafiles + +# The directory in which Roller 4.0 uploaded files + +uploads.dir=$\{user.home}/roller_data/uploads + +# Set to true to enable migration + +uploads.migrate.auto=true +---- + +The _mediafiles.storage.dir_ property should be set to the location +where you would like to store uploaded files. The _uploads.dir_ property +should be set to the location where you stored uploaded files in Roller +4.0. + +=== Install and startup the new Roller + +Follow the normal installation instructions for the new version of +Roller, but… + +* When creating your _roller-custom.properties_, copy of your old one. +Carefully review each property and compare it to the property settings +in the Roller property file described in Section link:#tomcat-create-roller-configuration-file[6.1]. +* Don’t create a new database for Roller. Instead point Roller to your +existing Roller database. *This is completely safe because you created a +backup of your database, right?* + +When you deploy and startup, Roller will detect that your database needs +to be upgraded and it will offer to run each of the migrations scripts +necessary to upgrade you from your old version to the new version of +Roller. + +*NOTE*: You can run the database scripts manually too, see Section +link:#manual-table-creation-and-upgrade[8.2]. + +*NOTE*: On Tomcat, before startup you should delete the contents of the +Tomcat work directory (located under the webapps folder.)