docs/roller-install-guide.adoc

= 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 is crucial when setting up any website, even on a private network.
Here are some recommendations to keep your Roller installation secure:

* *Install Roller on a secure network*. During installation, other users could
interfere or access the Roller database or files. To prevent this, install Roller
on a secure network or when the server is not in use by others.

* *Keep new user registrations disabled unless needed*. Self-registration is off
by default. Enabling *Allow New Users* on the Server Administration page lets
visitors create accounts; review <<optional-features>> before enabling it.

* *Use SSL for Roller*. Running Roller over HTTP can expose your password
to snooping, especially on open WIFI networks. To configure SSL (https:// URLs),
modify the web.xml in the Roller WAR (WEB-INF folder) by uncommenting
the <security-constraint/> element and following the instructions.
Then, follow your servlet container’s SSL setup documentation
(e.g., http://tomcat.apache.org/tomcat-7.0-doc/ssl-howto.html for Tomcat).
Redeploy Roller and ensure secure pages like the login and registration
pages are accessible only via https:// URLs.

Following these recommendations will help secure your Roller installation against
common web vulnerabilities.

=== Safer defaults

As of Roller 6.1.4, several default settings have been updated to enhance security
for multi-user weblog sites:

* *HTML content sanitization*: Roller now sanitizes all HTML content by default
to prevent malicious content. This is controlled by the _weblogAdminsUntrusted=true_
property in your _roller-custom.properties_ file.

* *Custom themes disabled*: By default, users cannot create custom themes.
This can be enabled via the Server Admin page if you trust your users, as custom themes can pose security risks.

* *File uploads disabled*: By default, file uploads are not allowed.
If you trust your users, you can enable this feature via the Server Admin page.

See <<optional-features>> for the benefits, risks and steps for enabling these
and other optional features. A solo blog still needs upload limits and care
when publishing HTML or editing templates.

== 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.

=== H2 database considerations

H2 is not one of Roller's officially supported databases (PostgreSQL, MySQL and
Derby are), but Roller can run against it as a generic JDBC database. If you use
H2 2.5.250 or later, be aware that H2 now treats VALUE as a reserved word.
Several Roller tables, such as ROLLER_PROPERTIES, have a column named VALUE, so
Roller will fail to read them on newer H2. To work around this, append
;NON_KEYWORDS=VALUE to your H2 JDBC connection URL, for example:

----
jdbc:h2:file:/path/to/rollerdb;NON_KEYWORDS=VALUE
----

== 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]]
=== 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 by the `authentication.method`
setting in _roller-custom.properties_: OpenID Connect (`oidc`), a combination
of database passwords and OpenID Connect (`db-oidc`), and LDAP (`ldap`)
(https://cwiki.apache.org/confluence/display/ROLLER/Roller+5.1+with+LDAP).
See <<oidc-login>> for OpenID Connect configuration. Roller 7 replaces the older
OpenID 2.0 integration with OpenID Connect; an old OpenID configuration needs
an OIDC provider registration.
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&amp;useUnicode=true&amp;characterEncoding=utf-8&amp;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://eclipse-ee4j.github.io/mail/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 because
Roller uses the JavaMail API for email address validation in its core
code. Download them from Maven Central and place them in Tomcat’s _lib_
directory:
** https://repo1.maven.org/maven2/com/sun/mail/jakarta.mail/1.6.7/jakarta.mail-1.6.7.jar[jakarta.mail-1.6.7.jar]
** https://repo1.maven.org/maven2/com/sun/activation/jakarta.activation/1.2.2/jakarta.activation-1.2.2.jar[jakarta.activation-1.2.2.jar]

=== 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?*

Review <<optional-features>> to decide which additional features your site needs.
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

[[optional-features]]
== Review optional features

Roller leaves several features off until an administrator chooses to enable
them. Some expose additional publishing or account-management interfaces;
others need a mail server, an identity provider or background tasks. Review
the benefits and risks below after completing installation.

These are the defaults for a new Roller 7 installation. Upgraded sites retain
their saved runtime settings, and local configuration can override startup
defaults. The features most sites want come first; the later ones serve
specialized needs.

There are two places to change settings:

* *Server Administration > Configuration*: a global administrator changes these
settings in the web interface and clicks *Save*. They are stored in the database
and do not require a restart. Do not put these runtime settings in
_roller-custom.properties_. Property names below help identify the settings.
* *_roller-custom.properties_*: the server operator changes these startup
properties in the configuration file described earlier in this guide, then
restarts Roller. Keep passwords and secret keys in a file readable only by the
operator and the account running Roller. Do not edit the bundled
_roller.properties_ or _runtimeConfigDefs.xml_ files.

=== Summernote rich text editor

*Default:* the Summernote plugin is available; new weblogs initially select
the plain text editor.

* *Benefit:* authors can format entries, insert links and work with images
without writing HTML by hand.
* *Risk:* pasted content can include unwanted markup and large images.
The editor does not replace server-side HTML sanitization.
* *Enable:* in the weblog's settings, select *Rich Text Editor (Summernote)* as
the editor and save. If an operator removed Summernote from
`plugins.weblogEntryEditors`, restore
`org.apache.roller.weblogger.ui.core.plugins.Summernote` in that comma-separated
startup property, preserving the other editor classes, then restart Roller.

Keep `weblogAdminsUntrusted=true`. Pasted PNG, JPEG and GIF images use media
storage when uploads are available; otherwise Roller keeps validated images
inline within the configured entry size limit. See the Roller User Guide for
inline image limits and database requirements.

=== Custom themes and templates

*Default:* off (`themes.customtheme.allowed=false`). Shared themes remain
available.

* *Benefit:* weblog administrators can customize templates, layouts and styles
for their own weblogs.
* *Risk:* template mistakes can break pages. Custom HTML, scripts and external
resources can affect visitors' privacy and browser behavior. The template
sandbox remains in effect when custom themes are enabled.
* *Enable:* in *Theme Settings*, select *Allow Custom Themes?*. A weblog
administrator can then use *Design > Theme* to select a custom theme and edit
its templates. Back up custom templates before changing them and review any
third-party theme before using it.

=== File uploads and media storage

*Default:* off (`uploads.enabled=false`).

* *Benefit:* authors can store images and downloadable files in Roller and
insert them in entries. Remote publishing clients can upload media too.
* *Risk:* uploaded content consumes disk space and may contain malicious or
unwanted files. A filename extension alone does not establish that a file is
safe to download.
* *Enable:* ensure `mediafiles.storage.dir` points to a writable directory
outside the deployed web application. In *File Upload Settings*, select
*Enable File Uploads?*, set an explicit *Allowed Extensions* list for the types
you need, and review *Forbidden Extensions*, *Max File Size (MB)* and
*Max Directory Size (MB)*. The default limits are 2 MB per file and 20 MB per
weblog. Check available disk space and include media storage in backups.

=== HTML comments and comment email notifications

*Default:* comments are allowed, but HTML in comments and email notifications
are off (`users.comments.htmlenabled=false`, `users.comments.emailnotify=false`).

* *Benefit:* HTML comments allow limited formatting and links. Notifications
help authors notice new comments and moderation requests.
* *Risk:* formatting and links can carry spam. Notifications can generate
unwanted mail and require a working mail server.
* *Enable:* in *Comment Settings*, select *Allow html in comments?* and/or
*Allow email notification of comments?*. Retain the `HTMLSubset` comment
formatting plugin when allowing HTML; this permits a limited subset of tags.
For notifications, configure outbound mail and enable comment notification
in the weblog's settings too. Review comment moderation and spam controls
before accepting public comments.

=== Remember-me login

*Default:* off (`rememberme.enabled=false`).

* *Benefit:* users can remain signed in across browser sessions.
* *Risk:* someone who obtains the persistent login cookie may gain access
to the account. Avoid this option on shared computers and use HTTPS.
* *Enable:* set `rememberme.enabled=true` and set `rememberme.key` to a long,
random secret unique to your installation in _roller-custom.properties_, then
restart. Do not use the shipped placeholder key `springRocks`; Roller refuses
to enable remember-me with that key.

=== Self-registration and email activation

*Default:* off (`users.registration.enabled=false`); requiring email
activation is also off (`user.account.email.activation=false`).

* *Benefit:* visitors can create their own accounts without an administrator
creating each one. Email activation checks access to the supplied mailbox.
* *Risk:* open registration can attract spam accounts and resource abuse.
Email activation needs working outbound mail and does not establish that a
person is trustworthy.
* *Enable:* in *User Settings*, select *Allow New Users?*. Configure and test
mail before selecting *Require new users to activate accounts via email*.
Review *Allow users to create new weblogs?*, which is on by default, before
opening registration. Test registration and activation with a non-admin
account. For a private site, leave registration off and create accounts in
the user administration pages.

[[oidc-login]]
=== OpenID Connect (OIDC) sign-in

*Default:* off; `authentication.method=db` uses Roller database passwords.
Automatic OIDC account creation is also off.

* *Benefit:* users sign in through an identity provider, which can centrally
manage accounts and authentication policies.
* *Risk:* sign-in depends on the provider's availability and account policies.
The provider controls identity claims; when automatic account creation is on,
it can also supply roles for new users, including `admin`. Restrict who can
use the Roller client and who can assign those roles.
* *Enable:* register Roller as an OIDC client at your provider. For a deployment
at `https://example.com/roller` and registration ID `company`, register
`https://example.com/roller/login/oauth2/code/company` as the redirect URI.
Add the following startup properties, replacing the example values:

[source,properties]
----
authentication.method=db-oidc
oidc.company.client-id=roller
oidc.company.client-secret=replace-with-your-client-secret
oidc.company.issuer-uri=https://identity.example.com/realms/company
oidc.company.client-name=Company sign-in
----

Restart Roller and test provider sign-in while retaining a working database
administrator login. Use `authentication.method=oidc` if users should sign in
only through the provider. Use HTTPS for Roller and the provider, and make sure
the redirect URI matches Roller's externally visible URL.

With `users.oidc.autoProvision.enabled=false`, users need an existing Roller
account linked to their provider identity. Roller can link an account when the
provider username matches and the provider asserts a verified email address
matching that account. To create accounts on first provider sign-in instead,
set `users.oidc.autoProvision.enabled=true` and restart. This is independent of
*Allow New Users*, which controls the registration form. Keep
`users.oidc.firstUserAdmin=false` for normal operation.

=== Planet feed aggregator

*Default:* off (`planet.aggregator.enabled=false`); its background tasks are
not in the default `tasks.enabled` list.

* *Benefit:* combines entries from local weblogs and external RSS/Atom feeds
into an aggregated site and feeds.
* *Risk:* Roller fetches remote URLs and stores feed content in its cache.
Only global administrators should choose subscriptions; review destinations,
disk usage and refresh frequency.
* *Enable:* follow <<planet-setup>> to create the cache directory, enable
Planet and its tasks, and add the rendering model. Preserve existing tasks
when updating `tasks.enabled`; setting only `planet.aggregator.enabled=true`
does not start feed fetching.

=== Atom Publishing Protocol (AtomPub)

*Default:* off (`webservices.enableAtomPub=false`).

* *Benefit:* desktop clients and scripts can publish entries, upload media and
manage categories and templates without using the browser editor.
* *Risk:* clients hold credentials and can change or delete content with the
user's weblog permissions. BASIC authentication sends credentials with each
request, so the endpoint must use HTTPS.
* *Enable:* in *Web Services Settings*, select *Enable Atom Publishing Protocol*
and leave *AtomPub authentication* set to `basic`, the supported method in
Roller 7. Keep the *Maximum AtomPub entry size (bytes)* limit appropriate for
your entries; the default is 1048576 (1 MiB). Media uploads also need file
uploads enabled. Template access also needs custom themes enabled and a custom
theme selected for that weblog.

After saving, use a client to discover
`https://<host>/<context>/roller-services/app/` with a Roller username and
password. OIDC browser sign-in does not supply an AtomPub password. See the
Roller AtomPub Guide for discovery, permissions and request examples.

=== Blogger and MetaWeblog APIs (XML-RPC)

*Default:* off (`webservices.enableXmlRpc=false`).

* *Benefit:* supports older weblog clients that use the Blogger or MetaWeblog
publishing APIs.
* *Risk:* exposes another interface for changing content. Clients send the
username and password in requests; use HTTPS and protect stored credentials.
* *Enable:* in *Web Services Settings*, select *Enable Blogger / MetaWeblog API*.
For each weblog, also select *Enable weblog client support?* in its settings.
Configure the client to use `https://<host>/<context>/roller-services/xmlrpc`.
Enable file uploads separately if the client will upload media.

=== Publishing HTML without sanitization

*Default:* off; `weblogAdminsUntrusted=true` sanitizes HTML from weblog members.

* *Benefit:* trusted authors can publish HTML that the sanitizer would remove,
such as embedded scripts or widgets.
* *Risk:* disabling sanitization allows authors' HTML to run scripts in
visitors' browsers. This startup setting applies site-wide, including to
other weblogs. A solo author can also paste unsafe third-party content.
* *Enable:* only if every weblog author and administrator is trusted, set
`weblogAdminsUntrusted=false` in _roller-custom.properties_ and restart.
Keep the default on sites with untrusted users. Summernote, file uploads and
custom themes do not require disabling HTML sanitization.

== 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.

[[planet-setup]]
=== 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 from 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]]
=== 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

=== Initial setup security token

Whenever Roller starts and finds setup work to do, it generates a cryptographically random, one-time setup token and prints it to the Roller server log. This applies to two cases:

* a **new installation**, where the database tables have yet to be created; and
* an **upgrade of an existing site** whose database schema needs to be migrated — for example from Roller 5.2.x or 6.0.x.

Upgrades that require no schema change issue no token and show no installer. Upgrading from any Roller 6.1.x release to another, including to 6.1.6, is such a case: the site starts up normally with no operator interaction.

When a token is issued, open `/roller-ui/bootstrap-token.rol` over HTTPS (or a secured local tunnel) and enter the token before opening the installer or registering the first administrator. The token is accepted only in the POST body, expires after 60 minutes, and is consumed on successful entry. Restart Roller to obtain a new token if it expires or the browser session is lost. The token is never included in a URL or Roller page.

NOTE: Because the token is written only to the server log, make sure you can read the Roller log — `roller.log`, or the container's console output — before you begin an upgrade that needs one. Plan for this in deployments where logs are shipped elsewhere or the console is not readily accessible.

The token authorizes the installer and first-user flow for the current browser session only. Run database creation or upgrade on one setup node at a time. Bootstrap access closes permanently as soon as setup finishes: on a new installation when the first administrator is committed, including after deleting or disabling that account; on an existing site when the database upgrade completes. Existing installations with users continue to use their normal login and registration settings.

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 <<tomcat-create-roller-configuration-file>>.
* 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
<<manual-table-creation-and-upgrade>>.

*NOTE*: On Tomcat, before startup you should delete the contents of the
Tomcat work directory (located under the webapps folder.)