In the following exercise, we will be installing and configuring a fresh Confluence instance that will be ready for production. We will be using the standalone bundle, and the installation will be based upon the Windows platform. If you are planning on using a different operating system, please refer to https://confluence.atlassian.com/display/DOC/Installing+Confluence for details on installing Confluence on that specific platform.
In this exercise we will:
We will continue to use this Confluence instance in other chapters and exercises as we prepare Confluence for usage within your own organization.
For our implementation, we will be using:
Confluence standalone distribution 5.1.0
Java Development Kit 7 update 9
Microsoft Windows Server 2008 R2
Confluence requires Java to be installed on the system, so this is our first step. Confluence 5.1 requires the latest update of JDK 7. If you are installing a different version of Confluence, make sure if JDK 7 is supported. Your choice between a 32-bit or 64-bit version depends on the amount of memory you want to allocate to Confluence; if it's more then 4 GB, pick the 64-bit version as 4 GB is the upper limit for the 32-bit version.
Currently, it is only possible to install Confluence as a Windows service if it is running on a 32-bit Java version.
Download the latest version of 32-bit JDK 7 from http://www.oracle.com/technetwork/java/javase/downloads/index.html.
Double-click on the downloaded installation file to start the installation wizard.
Select where you would like to install Java; or you can simply accept the default values. The location where you install the JDK will be referred to as
JAVA_HOMEfor the rest of the book.
Create a new environmental variable named
JAVA_HOMEwith the path where you just installed Java, as shown in the following screenshot:
This should display the version of Java installed:
C:\>java –version java version "1.7.0_17" Java(TM) SE Runtime Environment (build 1.7.0_17-b02) Java HotSpot(TM) Client VM (build 23.7-b01, mixed mode, sharing)
To install PostgreSQL, simply perform the following steps:
Download PostgreSQL from http://www.postgresql.org/download/windows/.
Double-click on the downloaded installation file to start the installation wizard.
Select where you would like to install PostgreSQL and want to store the data. We'll be using the default settings during this exercise.
Choose a password for the root user; keep in mind that this is not the password for our Confluence database. I used
p0stgre$, to keep it simple and easy to remember during this exercise and confirm to the Windows 2008 password security rules.
If you choose a different port number, please make sure it doesn't conflict with any other services running on your machine. Also remember the port number, as we'll need it later.
Uncheck the checkbox to make sure Stack Builder isn't launched at the completion of the installation process. We don't need it.
Now that PostgreSQL is installed on our machine, we need to create a dedicated user and database for Confluence to use. This will prevent other users of the application from accessing Confluence data.
Connect to the PostgreSQL server running at localhost, by double-clicking on the server name. Enter the root password you just picked, when prompted:
Enter the database name: confuencedb.
Set the owner of the database to the user we just created.
Select UTF-8 for encoding.
Confirm the creation of the database.
Configure the Confluence Home directory
Check the ports Confluence uses
Optionally, we can configure Confluence to use HTTPS and run as a Windows service.
Download the latest version of Atlassian Confluence from www.atlassian.com/software/confluence/download.
The Atlassian website will detect the operating system you are using and will suggest a distribution accordingly. If you intend to install Confluence on a different system than the one you are currently on, make sure you select the correct distribution.
As mentioned before, there are one-click installers available for both Windows and Linux. For the purpose of this exercise we will be using the ZIP archive, as it will provide us with an insight of the steps that are normally hidden by the installation process.
Extract the downloaded ZIP file to
c:/confluence/. It is recommended to use a third-party unzip software, such as 7-Zip or WinZip, as there are known issues with the unzip application provided with Windows. You can choose a different installation path; just make sure that you don't use spaces in your directory path.
C:\confluence\atlassian-confluence-5.1will now be known as
CONF_INSTALL. Next, we will define the Confluence Home directory.
c:\confluence\data; this directory will now be known as
CONF_INSTALLand open the file
confluence\WEB-INF\classes\confluence-init.propertiesin your favorite text editor.
Locate the following line; it's usually at the end of the file.
#and the space at the beginning of this line, so that Confluence no longer regards it as a comment.
If you have selected a different directory for
CONF_HOME, then change the path accordingly. Please note the following:
Avoid spaces in the directory path.
Use forward slashes
/to define the path.
By default, Confluence runs on port 8090 with no context path. This means that after starting Confluence it will be available at
http://localhost:8090/. If you have another application running on your machine that is using the same ports, you may need to change the port Confluence will use. Changing the context path is useful when you are running your applications behind a proxy and want to access them with the same domain, for example,
http://example.com/confluence. For this exercise we will be changing the context Confluence is running on to
To change the ports for Confluence, open the file
conf/server.xml under your
CONF_INSTALL directory. An extract from that file is shown here:
<Server port="8000" shutdown="SHUTDOWN" debug="0"> <Connector className="org.apache.coyote.tomcat4.CoyoteConnector" port="8090"…. /> <Context path="/confluence" docBase="../confluence" debug="0" reloadable="false" useHttpOnly="true">
Downloading the example code
You can download the example code files for all Packt books you have purchased from your account at http://www.packtpub.com. If you purchased this book elsewhere, you can visit http://www.packtpub.com/support and register to have the files e-mailed directly to you.
Line 1: This line specifies the port for the command to shut down Tomcat. By default this port is 8000. If you already have an application running on that port, you can change this to another port.
Line 2: This line specifies on which port Confluence/Tomcat will be running. By default this is port 8090. If that port is unavailable for some reason, you can change it to another available port.
For this exercise we will change the context path to
/confluence, as shown in the previous file.
In order to use the share and notification features from Confluence an e-mail account has to be set up. Normally, we could do this using the Confluence interface, but there is an exception if you want to use SMTPS, with your Gmail account for example. So for this exercise we will be configuring Confluence to use your Gmail account for sending e-mail notifications to the users.
Move (don't copy)
Add the following resource to your
CONF_INSTALL/conf/server.xml; make sure to add it just before the
<Resource name="mail/GmailSMTPServer" auth="Container" type="javax.mail.Session" mail.smtp.host="smtp.gmail.com" mail.smtp.port="465" mail.smtp.auth="true" mail.smtp.user="[email protected]" password="yourPassword" mail.smtp.starttls.enable="true" mail.transport.protocol="smtps" mail.smtp.socketFactory.class="javax.net.ssl.SSLSocketFactory" />
yourPasswordwith the proper values for your account.
Remember or write down the resource name. When we are configuring Confluence and asked for an e-mail server the JNDI location will be:
Note that the name is case-sensitive.
By default, Confluence runs with a standard, non-encrypted HTTP protocol. This is acceptable if you are running Confluence in a secured environment, such as an internal network. However, if you are planning to open up access to Confluence via the Internet, you need to tighten the security. We will be doing this by configuring Confluence to run over HTTPS (HTTP over SSL), so that login information and data are encrypted during transport over the Internet.
For a standalone installation, we need to perform the following tasks:
Create or request a new SSL Certificate
Enable HTTPS on our application server
Redirect traffic to HTTPS
First, we need to get a digital certificate. This can be one from a Certification Authority such as VeriSign or StartSSL (CA certificate), or a self-signed certificate generated by you. A CA certificate will not only encrypt your data, but also identify your copy of Confluence to users. A self-signed certificate is useful when you do not have a valid CA certificate and you are only interested in setting up HTTPS for encryption.
Because a self-signed certificate is not signed by a Certificate Authority, users may receive a message that the site is not to be trusted and may have to perform several steps to accept the certificate before they can access the site. This usually will only occur the first time they access the site. A self-signed certificate is great for evaluation purposes, but I would recommend a CA certificate for your production environment.
For the purpose of this exercise we will create a self-signed certificate. If you already have a CA certificate you can, of course, use that certificate.
Run the following command in the command prompt:
"%JAVA_HOME%/bin/keytool.exe" -genkeypair -alias tomcat -keyalg RSA
When asked for a password:
Specify the password you want to use for the certificate. Note that the password text will not appear as you type.
Make a note of the password you choose; we will need it in the next step when editing the Tomcat configuration.
In this exercise we will be using the default password
Follow the prompts to specify your domain name, organization, and location. This information is used to construct the X.500 Distinguished Name (DN) of the entity. To the question What is your first and last name? (CN), don't give your actual name. The CN must match the fully-qualified hostname of the server running Confluence. Tomcat will not be able to use the certificate for SSL otherwise.
For example, for our Confluence, running on localhost:
localhost, OU =
Confluence Essentials, O =
Packt, C =
When asked for the password for
tomcat(the alias you entered in the keytool command), press the Enter key. You must use the same password here as the one that was used for the keystore password. This is a restriction of the Tomcat implementation.
Your certificate is now ready.
Our self-signed certificate is now available in Java's keystore. If you are using a previously generated certificate or a CA certificate, you will need to import that certificate into Java's keystore. This can be done with the following command:
keytool -importcert -alias tomcat -file <MY_CERTIFICATE_FILENAME>
<Connector port="8443" maxHttpHeaderSize="8192" maxThreads="150" minSpareThreads="25" maxSpareThreads="75" enableLookups="false" disableUploadTimeout="true" acceptCount="100" scheme="https" secure="true" clientAuth="false" sslProtocol="TLS" SSLEnabled="true" URIEncoding="UTF-8" keystorePass="<MY_CERTIFICATE_PASSWORD>"/>
This connector will enable HTTPS for Confluence on port 8443. We will have to replace
<MY_CERTIFICATE_PASSWORD> with the password we specified when creating our certificate. In our case this would be
By default, Tomcat expects the keystore file to be named
.keystore and be located in the user home directory under which Tomcat is running. This could be a different account than your own, and therefore, can be another directory. If your certificate is not in the default location, you will have to update the server configuration to include
keystoreFile="<MY_CERTIFICATE_LOCATION>" in the connector element.
Although HTTPS is now active and available, the old HTTP URLs are still available. We will have to set up Confluence so that it will redirect automatically from an HTTP to an HTTPS request. We will need to do this by adding a security constraint in
CONF_INSTALL/confluence/WEB-INF/web.xml and add the following snippet to the end of the file, before the
<security-constraint> <web-resource-collection> <web-resource-name>Restricted URLs</web-resource-name> <url-pattern>/</url-pattern> </web-resource-collection> <user-data-constraint> <transport-guarantee>CONFIDENTIAL</transport-guarantee> </user-data-constraint> </security-constraint>
This will cause Tomcat to redirect all requests that come in on a non-SSL port. The first part will make sure all URLs are checked by this security constraint. The second part will guarantee that HTTPS is used for transportation.
Under Windows, Confluence can be configured to run as a Windows service, thus starting up automatically when the operating system reboots. This is recommended, as the alternative is having a console window open on the machine, which could be accidentally closed, thus shutting down Confluence.
Start a new command prompt as administrator, and browse to the
Run the following command:
service.bat install Confluence
This will install Confluence as a Windows service. The service will be called Apache Tomcat Confluence.
Verify the configuration by going to the Services console by going to Start | Administrative Tools | Services.
You can now start, stop, and restart Confluence from the Windows service panel.