| = 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. |
| |
| The general format of this document was based on the documentation |
| template used by the OpenDS project which in turn was based on the |
| templates used by the http://www.OpenOffice.org/[OpenOffice.org] |
| project. |
| |
| == 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 |
| <security-constraint/> 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 <Apache Roller Themes> 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. |
| |
| |
| ---- |
| <Context path="/roller" debug="0"> |
| <Resource name="jdbc/rollerdb" auth="Container" type="javax.sql.DataSource" |
| driverClassName="com.mysql.jdbc.Driver" |
| url="jdbc:mysql://localhost:3306/rollerdb?autoReconnect=true&useUnicode=true&characterEncoding=utf-8&mysqlEncoding=utf8" |
| username="scott" |
| password="tiger" |
| maxActive="20" maxIdle="3" removeAbandoned="true" maxWait="3000" /> |
| <Resource name="mail/Session" auth="Container" type="javax.mail.Session" |
| mail.transport.protocol="smtp" |
| mail.smtp.host="smtp.gmail.com" |
| mail.smtp.port="465" |
| mail.smtp.auth="true" |
| mail.smtp.user="blah.blah@gmail.com" |
| password="yourgmailpassword" |
| mail.smtp.starttls.enable="true" |
| mail.smtp.socketFactory.class="javax.net.ssl.SSLSocketFactory" |
| mail.smtp.socketFactory.port="465" |
| mail.smtp.socketFactory.fallback="false" |
| mail.debug="false"/> |
| </Context> |
| ---- |
| |
| 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: |
| |
| |
| ---- |
| <Host name="localhost" appBase="webapps" unpackWARs="true" autoDeploy="true"> |
| |
| <Context |
| path="/roller" |
| docBase="roller" |
| antiResourceLocking="false"> |
| |
| <Resource name="mail/Session" |
| auth="Container" |
| type="javax.mail.Session" |
| mail.transport.protocol="smtp" |
| mail.smtp.host="smtp.gmail.com" |
| …rest of properties same as above… |
| /> |
| </Context> |
| </Host> |
| ---- |
| |
| === 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: |
| |
| ---- |
| <Connector port="8080" maxThreads="150" minSpareThreads="25" |
| maxSpareThreads="75" |
| |
| enableLookups="false" redirectPort="8443" debug="0" |
| acceptCount="100" |
| |
| connectionTimeout="20000" disableUploadTimeout="true" |
| URIEncoding="UTF-8"/> |
| ---- |
| |
| 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=<group-name>[] |
| |
| |
| === 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:#anchor-2[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:#anchor-5[8.2]. |
| |
| *NOTE*: On Tomcat, before startup you should delete the contents of the |
| Tomcat work directory (located under the webapps folder.) |