Roller 安装文档（翻译）

最近研究Roller，一直手痒，想搞个Java 的博客玩玩，网上查了下，Roller像是比较出名，所以就选择他了。
     可惜网上中文的文档不多，官方e文的文档也不多，连API也没有提供，所以，我觉得，先把他的三个文档翻译下，一来方便我学习，二来，给同时给感兴趣的又不敢冒e文同志的一些方便（声明下，我像是也不怎么感冒e文，所以敢同身受）。
   废话少说，先贴点出来，接下来连载啦。
                  ------------------------------------------------------------
                                                                   Roller  安装指南

目录
1 概述
  1.1 版权和商标信息
  1.2 反馈
  1.3 文档说明
1.4 更改和补充
2 5分钟安装
3 准备滚动了吗？
3.1 Tomcat：Javamail 和 Activation（发邮件的java API ）
3.2 Tomcat：URI编码国际化支持（I118N）
4 下载和解压Roller
4.1 安装目录说明
4.2 Roller博客打包（WAR包）
5 准备Roller所需数据库
5.1 创建Roller数据库
5.2 检验JDBC数据库驱动设置
5.3 MySQL和Oracle的注意事项
6 配置Roller
6.1 以MySQL为例子
7 部署Roller
  7.1 把 roller-custom.properties 放到 classpath的路径下
7.2 通过控制台部署Roller
8 开始使用Roller
  8.1 引导完成Roller的安装
  8.2 注册一个用户及创建一个博客
9 配置技巧和小窍门
   9.1  设置 Roller的Planet聚合器
   9.2  修改security.xml里的关键字
   9.3  使用服务器提供的数据库和邮件资源
   9.4  手动创建及其升级表的操作
10 升级Roller
   10.1 从Roller 2.x升级到Roller 4.0
  10.2 备份Roller老版本
  10.3 安装设置Roller新版本
11 roller.properties




1 概述
      这份文档是讲如何安装 Apache Roller 博客软件的。将会告诉你首先该装什么，如何下载Roller，如何设置Roller，以及如何将Roller安装到现有的java应用服务器及其关联数据库上。同样也提供了更具有亲和的5分钟安装说明。
1.1 版权和商标信息
这份文档遵循Apache Software License的条款（嘻嘻，开源啦～）。
在这个文件里的所有的商标属于法定所有者（估计就是Roller的开发者或组织）。
1.2 反馈（联系方式）
  如有对这个文档有任何意见或建议，请直接发送到： [e-mail]。
1.3 文档说明
这份文档的初始版本是由Dave Johnson撰写的，当前版本是由Apache 组织下的Apache Roller 项目组维护。
这份文档的格式是基于OpenOffice.org项目下的OpenDS项目文档模板。
1.4 更改和补充
日期            变更描述
2007七月  重写了Roller4.0简单安装步骤


2  5分钟安装
如果你知道将要怎么做，你只需要快速的预览获取的Roller安装包以及恰当支持的平台（如，Tomcat和MySQL），或许你就可以通过本写简单的5分钟安装步骤完成安装。如果你没有信心完成，可以跳到第三部分。下面就开始介绍如何在5分钟内安装Roller：
第一步：下载Roller（Zip或GNU Tar）压缩包，解压到你本机的硬盘上。
第二步：创建一个放置Roller数据表的数据库。
例如，在MySQL上你或许会这么做：
1% mysql -u root -p
2password: *****
3mysql> create database rollerdb;
4mysql> grant all on rollerdb.* to scott@'%' identified by 'tiger';
5mysql> grant all on rollerdb.* to scott@localhost identified by 'tiger';


第三步: 创建一个roller-custom.properties配置文件，放在Servlet 容器的Classpath下，例如，Tomcat上就放在common/classes.如下配置你的数据库以及邮件服务器替换文件里的粗体部分。

1installation.type=auto
2database.configurationType=jdbc
3database.jdbc.driverClass=com.mysql.jdbc.Driver
4database.jdbc.connectionURL=jdbc:mysql://localhost:3306/rollerdb
5database.jdbc.username=scott
6database.jdbc.password=tiger
7mail.configurationType=properties
8mail.hostname=smtp-server.example.com
9mail.username=scott
10mail.password=tiger


第四步：校验你servlet容器下的JDBC和javamail的设置。确保你的数据库的JDBC驱动在你的 Servlet容器的classpath路径下，例如Tomcat的驱动放置的路径为common/lib。如果你还需要发送邮件的话，还要把 Javamail和Activation.jar（mail.jar和activation.jar）放到该路径下。
第五步：使用Servlet 容器管理控制台部署Roller目录到Servlet 容器上。Roller应用就会安装到webapp/roller目录下第六步：浏览打开Roller（或许是http：//localhost:8080/roller）。如果Roller运行正常，那么就继续第八部分，开始使用Roller。如果Roller没法运行而且你无法形容为什么这样，那就试着采用正常安装步骤从以下第三部分开始。


3 准备滚了吗？
首先，我们来确认你用来安装和运行Roller要做的每一件事。
Roller是一个需要数据库驱动的java 网络应用。所以你要运行该应用，需要Java，Java Servlet 容器像Tomcat和 一个数据库像MySQL。特别明确下，安装和运行Roller所要具备的条件：
. Java开发工具集（JDK），需要Sun Java2 SE 1.5 JDK。在你的计算机上安装Roller就要配置Java SE 5。Roller 3.x是最后一个支持Java1.4.2的版本。
. 一个Java 应用服务，特别指出要支持Servlet2.4API的Servlet 容器。在下面，都称其为服务（server）。Roller社区往往就对Tomcat 5.5，Tomcat 6.0，Sun Web Server 7.0以及Glassfish2.0的使用中的问题作答。
.一个关联数据库 例如，MySQL或Apache Derby。Roller社区倾向于使用和回答问题关于MySQL and Apache Derby,但是Roller也可以使用其他数据库。Roller创建了针对DB2，Derby,HSQL-DB,Microsoft SQL Server,MySQL，Oracle 和PostgreSQL这些数据库的脚本。
如果你正在使用Tomcat的话，下面部分将验证Tomcat所需具备的事项，否则，你可以直接看第四部分：下载解压Roller。
3.1 Tomcat:JavaMail and Activation
Tomcat没有包含Roller所需电邮公告（发送）的java Mail 和 Activation 的jar包，所以，如果你要使用Roller的电邮公告的功能，你就需要下载那些jar包放到Tomcat的Classpath下。需要从Sun的站点下载（http://java.sun.com/products/javamail）然后放到Tomcat的common/lib 目录下。
3.2 Tomcat：URI 编码国际化（I118N）
Roller 支持国际化（I18N），但是Tomcat需要另外的一些设置。你必须确保Tomcat的URI编码是设置为UTF-8.因此你要修改Tomcat配置文件conf/server.xml在每一个连接元素加URIEncoding="UTF-8",就像下面这样：
<Connector port="8080"
  maxThreads="150" minSpareThreads="25" maxSpareThreads="75"
  enableLookups="false" redirectPort="8443" debug="0"
  acceptCount="100" connectionTimeout="20000"
  disableUploadTimeout="true"
  URIEncoding="UTF-8" />
确保Roller所要用到的连接加以修改。例如，你使用AJP连接或HTTPS 连接，同样也要加URIEncoding="UTF-8"的属性。

4 下载解压Roller

从http://roller.apache.org下载Apache Roller 版本文件.如果你是Windows用户就下载.zip文件，用你所喜爱的解压工具解压这个文件。Unix用户就下载.tar.gz文件，使用GNU tar 来解压。
4.1 安装目录展示
一旦你解压这个文件，你将发现如下结构的目录


LICENCE.txt 和 NOTICE.txt包含了Apache Software Liscense以及其他一些同版本关联的法律条文。README.txt指出了这篇文档所在的doc目录。
4.2 Roller博客网络应用程序
Roller博客程序在webapp/roller目录下，采用了标准的Java EE WAR 的目录结构。一般来说，你不需要修改者里面的任何文件。你可以部署这个在目录表单里，或者部署一个文件，那就要打包成.war文件。
例如，这里是打包成WAR文件的方法：
1% cd apache-roller-X.0/webapp/roller
2% jar cvf ../roller.war *



5 准备Roller所需的数据库
在你安装Roller之前，先要为Roller所需的数据库做一些准备工作。
你在一些地方存放Roller的数据表，有的人称之为数据表空间，但是我们情愿称其为数据库。
你需要创建一个数据库，或让数据库管理员来为你创建。然后你需要为你的数据库选择一个JDBC驱动来安装。
如果你正在将Roller安装到Glassfish并JavaDB/Derby数据库的话，你就可以跳过这一部分了；Derby不需要创建数据库，并且Glassfish也包含了Derby的JDBC驱动。
5.1 创建一个Roller所需的数据库
  如果你有幸有自己的数据库管理员，就请他们安装一个数据库，当他们做完后，问他们要如下的信息，你之后会用到：
  . 用来连接数据库的用户名和密码
  . 连接数据库的 JDBC的地址（URL）
  . JDBC的类名
如果你没有数据库管理员，那你就只能参照文档准备数据库。你需要创建一个Roller所需的数据库，并使用用户名和密码来保护。例如，你正在使用的数据库是MySQL，请如下操作：
1% mysql -u root -p
2password: *****
3mysql> create database rollerdb;
4mysql> grant all on rollerdb.* to scott@'%' identified by 'tiger';
5mysql> grant all on rollerdb.* to scott@localhost identified by 'tiger';


5.2 检查JDBC驱动设置
确保在服务器上安装的是正确的JDBC驱动。通常，基本上都是JDBC驱动的jar包，然后放在服务器的CLasspath的路径下。例如，在 Tomcat5.5上是common/lib,在Tomcat6.0上是在lib，在Glassfish的domain的lib目录下。
5.3 MySQL和Oracle考虑事项
基于我们支持MySQL的经验，我们如下的建议：
.  对于MySQL，确保TCP/IP网络是可用的。
.  对于MySQL4.1.x 使用J/Connector3.0.xJDBC驱动替代更加新的3.1.x系列。
.  对于MySQL5.x 使用J/Connector3.1.xJDBC驱动替代更加新的3.1.x系列。
.  确保MySQL的 UTF-8支持可用。详情见如下的页面：
http://rollerweblogger.org/wiki/Wiki.jsp?page=SetupUTF8onMySQL
.对于Oracle的用户，请使用ojdbc14.jar的10g（10.1.0.2更高）驱动，即使是在对Oracle9服务器操作。


先贴到这里，明天继续。






6  设置Reller

可能让你设置Roller的文件只有一个：

roller-custom.properties

那是一个简单的Java属性配置文件，

一个重写了Roller内部默认设置(roller.properties)文件。用来设置你所看到的Roller内部配置文件，决定哪些属性你需要重写，可以在roller-custom.properties文件里设置那些属性。

你可以找到完整的Roller 内部配置文件（roller.properties）在第11部分，也建议你可以看一下，但是在这里我们举个简单的例子只要你知道如何配置数据库让Roller运行。

创建一个名为roller-custom.properties内容如下的的文本文件，但是从、需要替换斜体部分的文字用来设置你的数据库和邮件服务器。

1installation.type=auto
2database.configurationType=jdbc
3database.jdbc.driverClass=JDBC driver [class name]
4database.jdbc.connectionURL=JDBC connection URL
5database.jdbc.username=database username
6database.jdbc.password=database password
7mail.configurationType=properties
8mail.hostname=mail server hostname



installation.type=auto是告诉Roller是自动安装模式。在这个模式下，提供非常详细的错误详情来帮助你调试数据库连接的问题。如果Roller发现数据库存在但是表不存在，则会运行数据库创建脚本，如果发现表存在，但是不是当前版本的Roller则会提供表的升级。一旦Roller安装成功，并且需要在线使用，则你应该设置installation.type=manual。

6.1 MySQL例子

这里的roller-custom.properties示范了MySQL连接。显示了MySQL JDBC

驱动类名，MySQL连接URL，以及用来连接邮件服务器的用户名、密码


1installation.type=auto database.configurationType=jdbc
2
3database.jdbc.driverClass=com.mysql.jdbc.Driver
4
5database.jdbc.connectionURL=jdbc:mysql://localhost:3306/rollerdb
6
7database.jdbc.username=scott
8
9database.jdbc.password=tiger mail.configurationType=properties mail.hostname=smtp-
10server.example.com mail.username=scott
11
12mail.password=tiger
13

接下来，我们来部署Roller。



7 部署Roller

现在你已经有了Roller War和Roller配置文件roller-custom.properties，你可以准备部署Roller到服务器上了。首先，部署你的配置文件。

7.1 把roller-custom.properties放到Classpath下
Roller能够找到你的配置文件通过不同的方法，详情你可以看第11部分。

最简单的事，你要做的是把文件在你的应用服务器的classpath下，就是放到Classes的目录下。启动时，Roller将找到配置文件。这里对一些热门的服务器的路径地址。

在Tomcat5.5，拷贝到common/classes目录下。

在Tomcat6.0，拷贝到lib目录下。

在Glassfish，拷贝到你的domain的lib/classes目录下。

现在你可以准备部署Roller了。

7.2 通过管理控制台部署Roller

使用服务器管理控制台来部署Roller网络应用。

你可以部署一个目录，在这种情况下，配置你的安装路径webapp/Roller。或者你可以部署一个WAR文件，在这个情况下你得先创建一个WAR文件（第4.2部分有交代）。

我们来看看如何在Tomacat6.0和Glassfishv2.0部署的。


部署到Apache Tomcat 6.0上

你可以在Tomcat上部署

WAR文件或者是目录。下面这个截屏展示了基于目录的部署项。



一旦Roller被部署，你将看到其他应用的列表里列出。那个/roller是用来链接到Roller的，还有启动，停止，重载，卸载部署的选项。





如果Roller没法启动，请查看问题日志。能在Tomcat的log目录下找到。

Tomcat的日志文件在catalina.out，Roller的日志文件在roller.log下。



 

部署到Glassfish v2.0上

同样你也可以部署一个WAR文件或者一个目录到Glassfish上。下面的截屏展示基础目录部署项。

一旦Roller被不是上，你将看到Roller也被列在应用列表里。在映射连接到Roller上，有的按钮可用，有的则不展示，或置灰。

如果Roller没有启动，可以在日志里查看问题。你能在Glassfish的domain的logs目录下找到。Glassfish日志是server.log，Roller日志是在roller.log.




8 开始使用Roller

在你完成了安装步骤后，现在你可以准备开始使用Roller了，所以我们将带你进入Roller，注册一个用户和创建一个博客。我们也会针对发生错误，就是什么问题。

8.1 浏览Roller，完成安装

浏览Roller，如果你使用的是Tomcat或Glassfish安装的，那么Roller也许在http://localhost:8080/roller。你或许会看到一个有错误信息的页面，一个提供创建数据库表的网页或一个提示你完成注册一个管理员用户及创建首页博客的网页。首先，我们来看看当发生错误的时候，就近出了什么问题。

如果是你数据库设置问题，Roller将会展示一个错误信息页面来帮助你诊断这个问题。或许是连错了的JDCB驱动类名，URL链接，用户名，密码。亦或许你的数据库没有启动起来。利用所提供的资料，以确定哪些是错的，修理，然后重新部署Roller。


自动创建表

如果你的数据库没有问题，但是Roller没能找到数据表，那么Roller将会提供自动创建的页面。如果你

如果使用这个页面，Roller将会运行创建数据库表的脚本及可以看到创建结果。然后你可以进行下一步设置你的第一个用户帐户和博客。


8.2 注册一个用户，创建一个博客

如果Roller启动好了，但是没有找到博客的首页，那么下面将展示如何注册你第一个用户，创建你第一个博客，设置你的站点的首页。

你必须要决定什么作为你Roller站点的首页。如果你使用Roller来运行你的个人博客，那么你就要你的博客作为站点的首页。这样的话，只要创建的你自己的博客，不要选择首页主题但是要设置你的博客作为站点的首页博客。


如果你用来创建一个社区性的多用户博客，那么你可以在首页展示全部博客的汇总，这样的话，创建一个博客用来服务于首页的博客，并设置为首页博客，一定要设置“汇总首页”做为服务管理页。

不要忘了：重置installation.type标志
现在你已经完成安装，你应该关闭roller自动安装系统了。编辑roller-custom.properties文件，设置installation.type=manual。
然后重启你的服务器，Roller就接受了新的设置。
接下来做什么？
一旦你启用了Roller，Roller用户指南有关于更多运行Roller系统和博客的信息。通过Roller模板指南信息，来定制你的博客。如果你通过文档无法找到你需要的关于Roller使用的描述，那么你在邮件列表里提问：地址是：http://cwiki.apache.org /confluence/display/ROLLER/Roller+Mailing+Lists