源文本版权归属 Copyright ? 2002-2004 David M Johnson
- 介绍
- 开发者请参见开发者向导
介绍
这篇文档描述了如何在Tomcat Servlet引擎上安装
Roller Weblogger版本1.0
， 以及如何设置：
- Java 1.4.x SDK或更高版本的SDK
- Tomcat 4.x或5.x Servlet容器（非Tomcat＂LE＂版本）.建议建立国际化的站点使用Tomcat 5.x
- MySQL 4.x或更高版本
- Windows或基于Unix的操作系统
对于Roller 0.9.8版本请参见 安装向导098
如何设置其他的servlet引擎？ 这篇向导主要支持Tomcat，但是在拥有这些经验以后，你应该可以使Roller工作在任何与Servlet API 2.3兼容的Servlet容器中 （例如Weblogic，Websphere，Jetty， Resin ， OrionServer 等等）; 建议建立国际化的站点使用支持Servlet API 2.4的服务器。 如果你把Roller部署在一个非Tomcat的容器中，请贡献你的安装心得来帮助其他人．
如何设置其他的数据库？ 这篇向导主要支持 MySQL ，但是Roller包含了 PostgreSQL 和 HSQL-DB 的数据库安装脚本．有经验之后你应该能够使Roller工作在任何支持 JDBC 的数据库上（例如Oracle，Informix，Sybase，MS SQL Server等等）。
第一步：前决条件 [#1]
在你安装Roller之前，你需要确认在你的系统上已经安装并且设置了一下软件：Java SDK，Tomcat Servlet引擎和 MySQL 数据库．如果在Debian上使用 MySQL ，请参考 Debian MySQL ．
作为安装Tomcat的一部分，你应该已经正确地设置了CATALINA_HOME环境变量，就像下面的实例所显示的．我们需要设置它，是因为在这篇向导的其他实例中我们会引用该变量．
UNIX(csh)实例：
% setenv CATALINA_HOME /opt/jakarta-tomcat-5.0.29
Windows实例，MS-DOS或者命令提示窗口：
C> set CATALINA_HOME d:\jakarta-tomcat-5.0.29
第二步：解压缩下载的ZIP或TAR文件 [#2]
在这步中，应该把下载的ZIP或者TAR文件解压到Servlet容器的web应用程序的部署目录中．Tomcat的部署目录是Tomcat安装目录下的webapps目录．
UNIX实例：
% cp roller-1.0.tgz $CATALINA_HOME/webapps
% cd $CATALINA_HOME/webapps
% tar xzvf roller-1.0.tgz
在Windows下：使用 WinZIP ，解压roller.zip到%CATALINA_HOME\webapps目录下．
第三步：在数据库中建立Roller涉及的表 [#3]
现在你需要建立一个新的数据库，建立一个拥有适当权限的用户，然后使用SQL脚本来建立运行Roller需要的数据库表．请登陆到数据库，之后运行Roller WEB-INF/dbscripts目录下的Roller数据库建立脚本．
- WEB-INF/dbscripts/ mysql /creatdb.sql - 在 MySQL 中建立表的数据库脚本
- WEB-INF/dbscripts/hsql/creatdb.sql - 在HSQL-DB中建立表的数据库脚本
- WEB-INF/dbscripts/postgresql/creatdb.sql - 在 PostgreSQL 中建立表的数据库脚本
下面的实例将向你展示在 MySQL 中如何建立数据库表，假设你的Roller用户的用户名是scott，密码是tiger．关于 MySQL 的进一步信息请参考 MySQL 的参考手册．
UNIX实例
% cd $CATALINA_HOME/webapps/roller/WEB-INF/dbscripts/
mysql
%
mysql
-u root -p
password: *****
mysql
> create database roller;
mysql
> grant all on roller.* to scott@'%' identified by 'tiger';
mysql
> grant all on roller.* to scott@localhost identified by 'tiger';
mysql
> use roller;
mysql
> source createdb.sql
mysql
> quit
Windows实例，MS-DOS或者命令提示窗口：
C> cd %CATALINA_HOME%\webapps\roller\WEB-INF\dbscripts\
mysql
C>
mysql
-u root -p
password: *****
mysql
> create database roller;
mysql
> grant all on roller.* to scott@'%' identified by 'tiger';
mysql
> grant all on roller.* to scott@'localhost' identified by 'tiger';
mysql
> use roller;
mysql
> source createdb.sql
mysql
> quit
注意：
从Roller0.9.8升级到Roller1.0：你应该运行098-to-100migration.sql脚本来升级你的数据库.在数据库对应的creatdb.sql所在的目录下你可以找到该脚本。 从Roller0.9.7升级到Roller1.0：你应该首先运行097-to-098-migration.sql，然后再运行098-to-100-migration.sql。
问题 : MySQL 的用户不要忘记调用刷新特权，并且确认你的 MySQL 没有设置＂skip-networking＂选项．因为Connector/J只能通过TCP/IP来存取 mysql ．然而 mysql 命令行工具默认不使用TCP/IP套接字．使用以下的命令来检查你的连接是否正常工作（使用除了localhost的值来指定主机地址）
mysql
roller -h 127.0.0.1 -u scott -ptiger
第四步：下载并且安装需要的jars文件 [#4]
你需要下载并且安装几个必须的jar(s)包： JDBC 驱动和 JavaMail jars包。
4.1： JDBC 驱动
Roller使用应用服务器提供的数据库连接池，在下一步我们将会设置它。应用服务器想要和数据库进行连接，就需要对应于该数据库的 JDBC 驱动。
对于Tomcat来说，只需要简单地把 JDBC 驱动拷贝到Tomcat的common/lib目录中就行了。
实例：
MySQL
的用户可以在
MySQL
网站的Connector/J页面
上找到
MySQL
的
JDBC
驱动-
Connector/J
。 下载并且解压该文件，然后把
JDBC
驱动jar包拷贝到Tomcat的common/lib目录下。
UNIX实例： 解压（unzip，untar） MySQL Connector/J到一个目录中，cd到该目录，然后拷贝 JDBC 驱动jar包到Tomcat的common/lib目录下。
% cp
mysql
-connector-java-3.0.15-ga-bin.jar $CATALINA_HOME/common/lib
Windows实例，MS-DOS或者命令提示窗口： 解压（unzip，untar） MySQL Connector/J到一个目录中，cd到该目录，然后拷贝 JDBC 驱动jar包到Tomcat的common/lib目录下。
C> copy
mysql
-connector-java-3.0.15-ga-bin.jar %CATALINA_HOME%\common\lib
4.2： JavaMail 和激活架构（Activation）jars包
可以设置Roller发送文章评论的email通知。如果想要这个功能工作，Roller需要 JavaMail 和激活架构jars包来支持。
从Sun的网站下载 JavaMail 和激活架构jars包，解压下载的文件，然后把解压后的mail.jar和{activation.jar}文件拷贝到roller/WEB-INF/lib目录下。否则Roller将不能启动发送mail的功能。
第五步：在服务器中部署Roller [#5]
在J2EE应用服务器中部署Roller。你必须完成以下三步：
- 告诉应用服务器Roller的安装目录
- 告诉应用服务器使用Roller数据库中的rolleruser和userrole表来验证登陆的用户
- 为数据库设置数据源 jdbc /rollerdb
使用Tomcat 4.X 和 5.0.X的实例
对于Tomcat用户来说，就是编辑Tomcat Servlet引擎的conf/server.xml设置文件，添加Roller Servlet Context。在文件中设置使用Roller数据库的Servlet认证信息和Roller数据源。在server.xml文件中找到定义Contexts的位置，如果使用 MySQL ，应该把本文下面的代码添加到该位置。之前要确认你已经用你的 MySQL 数据库的用户名和密码取代了代码中的scott和tiger。
另外一种方法是：你可以把下面的Context设置代码添加到webapps/roller.xml文件中。如果你使用的是Tomcat 5.x，可以把该文件放到CATALINA_HOME/conf/Catalina/localhost目录下。 如果你使用Tomcat 5.5.X作为容器，请参考下面的实例。
为了避免 jdbc 连接问题，请用&取代connectionURL中的&。这种方法将会解决一些人遇到的xml合法性错误。当然还用改变下面的端口号为主机上正确的端口号。
<Context path="/roller" docBase="roller" debug="0">
<Realm className="org.apache.catalina.realm.
JDBC
Realm"
driverName="com.
mysql
.
jdbc
.Driver"
connectionURL=
"
jdbc
:
mysql
://localhost:3306/roller?autoReconnect=true&useUnicode=true&characterEncoding=utf-8&
mysql
Encoding=utf8"
connectionName="scott"
connectionPassword="tiger"
userTable="rolleruser"
userNameCol="username"
userCredCol="passphrase"
userRoleTable="userrole"
roleNameCol="rolename" debug="0" />
<Resource name="
jdbc
/rollerdb" auth="Container" type="javax.sql.DataSource" />
<ResourceParams name="
jdbc
/rollerdb">
<parameter>
<name>factory</name>
<value>org.apache.commons.dbcp.BasicDataSourceFactory</value>
</parameter>
<parameter>
<name>driverClassName</name>
<value>com.
mysql
.
jdbc
.Driver</value>
</parameter>
<parameter>
<name>url</name>
<value>
jdbc
:
mysql
://localhost:3306/roller?autoReconnect=true&useUnicode=true&characterEncoding=utf-8&
mysql
Encoding=utf8
</value>
</parameter>
<parameter><name>username</name><value>scott</value></parameter>
<parameter><name>password</name><value>tiger</value></parameter>
<parameter><name>maxActive</name><value>20</value></parameter>
<parameter><name>maxIdle</name><value>3</value></parameter>
<parameter><name>removeAbandoned</name><value>true</value></parameter>
<parameter><name>maxWait</name><value>3000</value></parameter>
</ResourceParams>
<!--
To enable email notification of comments: uncomment the resouce below,
set your mailhost, and make sure you have mail.jar and activation.jar
in <tomcat>/common/lib.
-->
<!--
<Resource name="mail/Session" auth="Container" type="javax.mail.Session"/>
<ResourceParams name="mail/Session">
<parameter>
<name>mail.smtp.host</name>
<value>mailhost.example.com</value>
</parameter>
</ResourceParams>
-->
</Context>
使用Tomcat 5.5.X的实例
在Tomcat 5.5.X中，定义资源参数的行为已经改变。 对于Tomcat 5.5.x来说，资源参数必须被定义为 Resource 元素的一个属性； ResourceParams 元素不被支持。 你可以使用下面的实例作为设置的起点。 这只对Tomcat 5.5.x有效；对于Tomcat 4.X 和 5.0.X 请使用上面的实例。
<Context path="/roller" docBase="roller" debug="0">
<Realm className="org.apache.catalina.realm.
JDBC
Realm"
driverName="com.
mysql
.
jdbc
.Driver"
connectionURL=
"
jdbc
:
mysql
://localhost:3306/roller?autoReconnect=true&
useUnicode=true&characterEncoding=utf-8&
mysql
Encoding=utf8"
connectionName="scott"
connectionPassword="tiger"
userTable="rolleruser"
userNameCol="username"
userCredCol="passphrase"
userRoleTable="userrole"
roleNameCol="rolename" debug="0" />
<Resource name="
jdbc
/rollerdb" auth="Container" type="javax.sql.DataSource"
driverClassName="com.
mysql
.
jdbc
.Driver"
url="
jdbc
:
mysql
://localhost:3306/roller?autoReconnect=true&useUnicode=true&characterEncoding=utf-8&
mysql
Encoding=utf8"
username="scott"
password="tiger"
maxActive="20"
maxIdle="3"
removeAbandoned="true"
maxWait="3000" />
<!--
To enable email notification of comments: uncomment the resouce below,
set your mailhost, and make sure you have mail.jar and activation.jar
in <tomcat>/common/lib.
-->
<!--
<Resource name="mail/Session" auth="Container" type="javax.mail.Session"
mail.smtp.host="mailhost.example.com" />
-->
</Context>
注意
-
<Context>
设置的第一部分设置了Tomcat的认证
<Realm>
。这个设置会让Tomcat在Roller数据库中的表中查找用户信息，来检查用户登陆的证书（用户名和密码）。我们设置Tomcat使用Roller数据库中的
rolleruser
和
role
表。关于设置<Realm>的更多信息，请参考Tomcat文档中关于
JDBC
Realm
的章节。
- <Context> 设置的第二部分用 <Resource> 设置了Roller的数据源。你必须重复一些在 <Realm> 设置中的连接参数。
- &字符在XML中被用来识别实体引用，所以你必须用&user=scott&password=password来代替connectionURL中&user=scott&password=password，来避免启动Tomcat时的解析异常。--例如：在&后添加amp;--
-
要想得到更多关于Tomcat server.xml设置文件的信息，请参考
Tomcat设置参考
。
- 如果在Roller启动时发生错误，并且在logs（roller.log）中的错误信息类似于User scott@localhost has already more than 'max_user_connections' active connections，请尝试减小maxActive，maxIdle和removeAbandoned的值。根据你数据库的设置你必须要做一些调整，例如设置maxActive为6，maxIdle为3，removeAbandonedTimeout为60。
-
从Roller 0.9.7升级，注意下面的一些变化：
- 表 role 已经被重命名为 userrole
- 表userrole中的 role 列被重命名为 rolename
- 表rolleruser中的 password 列被重命名为 passphrase
第六步：启动前的工作 [#6]
在启动Roller前，最后的一些工作...
6.1：设置应用服务器的I18N（国际化）
Roller实现国际化的方法就是用UTF-8编码做所用的事情。如果你想要I18N正常地工作，就要设置应用服务器和web服务器使用UTF-8编码。
Web应用服务器URI编码
确认你的应用服务器使用UTF-8来编码URI's。这样就允许你在urls中使用一些区分的字符。对Roller来说这点非常重要，因为在URLs中Weblog的登陆标题被使用。
实例： 在Tomcat中，URL的编码在server.xml文件的Connector中指定：
<Connector port="12345"
enableLookups="false"
URIEncoding="UTF-8"
redirectPort="8443"
debug="0"
protocol="AJP/1.3" />
注意： 你需要在与Roller应用有关的每一个connector中设置该属性。例如，如果你直接使用HTTP connector，而不是AJP和Apache，你也同样需要在 connector 元素中添加 URIEncoding="UTF-8" 属性，同样也适用于HTTPS connector。
Web服务器页面的编码
如果你使用一个独立的web服务器，比如Apache，来管理静态内容，请确认web服务器的页面编码被设置为UTF-8。
例如： Apache 2.x的情况，使用 AddDefaultCharset 来设置。
AddDefaultCharset utf-8
6.2：步骤1的继续
你是否认为6.1更像单独的一部分呢？
第七步：启动Tomcat和Roller [#7]
启动Servlet容器，打开你的浏览器，进入Roller的首页，开始享受Roller吧。
如果你在Tomcat上安装了Roller，Roller首页的URL可能是
http://localhost:8080/roller
。
UNIX实例：
% cd $CATALINA_HOME/bin
% ./startup.sh
Windows实例，MS-DOS或者命令提示窗口：
C> cd %CATALINA_HOME%\bin
C> startup
正像你做的！Roller正在完美地工作了。如果没有，请到
roller-user邮件列表
中请求帮助。一些人可能和你遇到相同的问题。
注意
：你建立的第一个用户将有管理员的权限，所以确定建立第一个用户的是你自己。管理员可以授权给其他用户管理员的权限，并且可以撤销该用户的权限。
第八步：后续工作 [#8]
现在你已经安装了Roller并且确认了它已经开始工作，这里还有一些你可能希望完成的工作。
8.1：设置Roller的命令行管理工具
Roller的命令行管理工具允许你给用户授权和撤销给用户的授权，保存所有的密码到一个文件中，从一个文件中恢复所有的密码，加密数据库中所有的密码。下面将讲解如何设置该工具。
- 打开命令行窗口
- 改变目录到Roller安装目录中的WEB-INF/dbscripts目录下
- 编辑文件 rollerdb.properties ，包含你的数据库连接参数
- 编辑文件 rollerpw.sh 或 rollerdb.bat （Windows平台），设置 JDBC 驱动的classpath
- 在UNIX环境中，在你第一次运行该脚本之前，你必须先运行命令 chmod +x rollerpw.sh 使脚本变为可执行的
- 运行脚本 rollerpw.sh 或 rollerdb.bat （Windows平台），然后它将会显示一些脚本的用法信息。
8.2：可选的步骤
一些可选的步骤...（TBD）
