Note |
---|
This article has lots of room for improvement in tone and the instructions can be more clear. |
Table of Contents |
---|
Install Required Libraries
In order to render thumbnails and related functionality you need certain x-windows libraries. Refer to the list from the Confluence install instructions and make sure to use the list matching your version of Confluence.
...
Table of Contents |
---|
Introduction
This article takes you through a Confluence 3.5+ setup using the following software stack,
- Confluence Standalone (includes its own embedded Tomcat) for Linux
- Java Development Kit (JDK)
- PostgreSQL
- Apache Web Server (optional)
Warning |
---|
It is recommended that you finish reading the article before starting. |
PostgreSQL
Confluence comes with its own embedded database called hsqldb. However, for real production use you should use a full fledged database like PostgreSQL.
Install PostgreSQL on Ubuntu
Install PostgreSQL6.0 PostgreSQL on Ubuntu.
Install Confluence
Core Package
Download the tar.gz install package and decompress it,
Code Block | ||
---|---|---|
| ||
su - svradmserveradmin # if you are not already gunzip confluence-3.25.7-std.tar.gz tar -xvpf confluence-3.25.7-std.tar su - bhitch # log in as a staff user that can run sudo # Use specific version numbers. This will make upgrade easier in the future. sudo mv home/serveradmin/confluence-3.25.7-std /opt/ |
Next, we make the symbolic link directory. Scripts and anything else you do will use the symbolic link directory. When the new version of Confluence comes along you have various options for upgrading.
Code Block | ||
---|---|---|
| ||
su - bhitch # log in as a staff user that can run sudo cd /opt # make a symbolic link which scripts and commands can run against sudo ln -s ./confluence-3.25.7-std ./confluence |
Manually Setup JDK
I use a manual Java setup with an instance of Java specifically for the application.
Note |
---|
Make sure you are install a JDK and not a JRE. This is a requirement of Confluence. |
Include Page |
---|
...
|
...
|
...
|
...
|
Log in as your staff account which has sudo access to perform the actual move to /opt/
Code Block | ||
---|---|---|
| ||
cd /home/serveradmin
sudo mv ./jdk1.6.0_16/ /opt/confluence/java # moves and renames the directory in one step |
Configure Confluence to Use JDK
The downloaded Confluence package is powered by Tomcat. You can specify Tomcat use a specific java directory by modifying the Confluence confluence/bin/setenv.sh file and test with confluence/bin/version.sh as described at Running Tomcat with a specific JRE version.
Warning |
---|
This can be improved by moving "how to specify java for Tomcat" out of the Tomcat 6 setup instructions into a separate page and then using an "include" here. |
Configure Confluence to Only Start and Stop with ServerAdmin
To prevent read errors and for security purposes we want Confluence to only run as serveradmin.
Modify /opt/confluence/bin/startup.sh and /opt/confluence/bin/shutdown.sh as instructed in "Only Allow serveradmin to Run Tomcat" at Portable Tomcat 6.x & Instances.
Configure Data Directory
Also we need to create the home directory,
Code Block | |||
---|---|---|---|
| |||
su - serveradmin cd ~ mkdir confluence-data # Don't use specific version numbers here because the data will actually be upgraded su - bhitch # to get sudo access sudo mv /home/serveradmin/confluence-data /opt/ |
Set As serveradmin, set the home (data) directory by modifying the files, ../confluence/adding confluence.home to the bottom of, /opt/confluence/confluence/WEB-INF/classes/confluence-init.properties, go to the bottom of the file,
Panel |
---|
# confluence.home=c:/confluence/data |
Configure PostgreSQL
Setup Database
These are abridged the command line version of the instructions from Confluences wiki on setting up an external database.
Rather than use the gui we can do everything from the command line. I derived the commands The commands were derived from the visual guide by Confluence.
First log into the PostgreSQL prompt as explain in PostgreSQL on Ubuntu.
Create the confluence database admin account,CREATE ROLE confluencedbuser LOGIN ENCRYPTED PASSWORD .
Note |
---|
Make sure to change putYourPasswordHere to a secure password. |
Code Block | ||
---|---|---|
| ||
CREATE ROLE confluencedbuser LOGIN ENCRYPTED PASSWORD 'putYourPasswordHere' |
...
NOINHERIT |
...
VALID UNTIL 'infinity'; |
...
COMMENT ON ROLE confluencedbuser IS 'Account used by the Confluence application.'; |
The servers will respond to each respective command,
Code Block | ||
---|---|---|
| ||
CREATE ROLE
COMMENT |
Create the database.
Code Block | ||
---|---|---|
| ||
CREATE DATABASE confluencedb |
...
WITH ENCODING='UTF8' |
...
OWNER=confluencedbuser |
...
CONNECTION LIMIT=-1; |
Note |
---|
If all goes well the response will be,
Code Block | ||
---|---|---|
| ||
CREATE DATABASE |
Finally quit the PostgreSQL prompt,
Code Block | ||
---|---|---|
| ||
\q |
Note |
---|
The name of the database is different than in the confluence documentation from confluence to confluencedb. As a coder it will be easier for me later one. Rather than the database name confluence, we use confluencedb to clearly designate a database. |
Setup JDBC4 Driver
Note |
---|
As of Confluence 3.5.1 the PostgreSQL JDBC4 driver is now included. This section is still useful as a reference for future version mismatches. |
Confluence 3.2 - 3.5.0 does include a JDBC driver for PostgreSQL. However, because we are using the newest version of Java, download the JDBC4 driver from the PostgreSQL website.
First delete the jdbc3 driver,rm and place the jar file into the /opt/confluence/confluence/WEB-INF/lib/ postgresql-8.4-701.jdbc3.jar
Then, place the JDBC Driver postgresql-8.4-701.jdbc4.jar into the <confluence-install-path>/confluence/directory. Then delete the old JDBC4 driver.
Code Block | ||
---|---|---|
| ||
su - serveradmin wget http://jdbc.postgresql.org/download/postgresql-9.0-801.jdbc4.jar rm /opt/confluence/confluence/WEB-INF/lib |
...
/postgresql-8.4-701.jdbc3.jar |
Starting the Confluence Service
We will now start Confluence for the first time to initialize everything.
Tip |
---|
If using virtual machine technology, now would be a good time to take a snapshot of the system. |
Code Block | ||
---|---|---|
| ||
cd /opt/confluence/bin/ ./startup.sh |
Note |
---|
In the Confluence notes they sometimes use catalina.sh instead of startup.sh. Investigate the difference. |
Next, hit the website with a browser, http://localhostkrypton:8080/ or change localhost to the ip address if you are not launching the browser off of the serverstart the first time configuration wizard.
Tip |
---|
If you have been following this tutorial these notes on how to setup Ubuntu, your firewall may be enabled. Make sure to enable access to port 8080. |
The very first time Confluence starts it asks you to make selections,
Warning |
---|
Everything below here needs to be flushed out better. |
...
Step through the configuration wizard and make the following selections,
- Choose Product Installation
- Makes sure PostgreSQL is selected (it should be by default) click External Database.
- Click Direct JDBC
- Fill out the form,
- Database URL: Change the default line, jdbc:postgresql://localhost:5432/confluence to jdbc:postgresql://localhost:5432/confluencedbconfluencedb
- User: confluencedbuser
- Pass: the pasword you used earlier to create the confluencedb user
- Click Next
At this point if you happen to be monitoring your system you should see a spike in CPU and confluence slowly taking up more memory. Be patient as this step can take a few minutes as the tables and contents of the database are generated.
If all goes well the you will be prompted to Load Content. You can opt to load some default content, start with a blank slate or restore from backed up data if you are rebuilding from a previous installation of Confluence.
The intial user will be called "Server Admin" with user name serveradmin
Stopping the Service
There appears to be a problem with shutting down the Confluence server. According to Atlassian, this only happens on certain configuration and they are not able to determine yet why. I have personally experienced with every type of Virtualized Ubuntu system I have setup over the past few years.
Start by trying to perform a normal shutdown,
Code Block | ||
---|---|---|
| ||
su - svradm
/opt/confluence/bin/shutdown.sh |
Next ensure that Confluence actually shut down,
Code Block | ||
---|---|---|
| ||
ps -ef | grep java | grep confluence |
The resulting output shows all your java processes. Look for you Confluence java process which looks something similar to below,
Code Block | ||
---|---|---|
| ||
svradm 2364 1 0 01:00 ? 00:02:37 /opt |
If it does not exist then the shutdown occurred properly. However, if it still exists try running ps again in a few minutes. If it still exists after that you need to kill the process,
Code Block | ||
---|---|---|
| ||
kill 2364 # Note change 2364, to the process ID that you see on your screen. |
Administrator Tasks
Warning |
---|
This section still needs to be written to take the user through setting up the base url, creating their first space, disabling automatic backup, how to do real backups and any other important activities. |
Setup Confluence to Send Emails
Confluence can send email notifications for updates and also used to perform user setup and password resets.
Setup your server to allow Email Delivery.
Verify Confluence can send emails using Confluence Administration, Mail Servers and Send test email link.
Optimize Confluence
There are some basic tasks we should do before getting other people on board.
...
- Disable automatic backup
- Setup emailConfluence to send emails
- Update Confluence plugins
Connect Apache to Confluence using Mod_JK
As this install of Confluence is powered by Tomcat we can front Confluence with the Apache Web Server.
Enable Tomcat AJP Connector
First we must enable the the Connector. In this example we will use the standard port 9009 in the Confluence Tomcat.
Warning |
---|
Still need to fill in instructions on this topic. |
Once port 9009 is enabled, mod_jk can be enabled by following the Apache Tomcat Connector instructions.
Stopping the Service
There appears to be a problem with shutting down the Confluence server. According to Atlassian, this only happens on certain configuration and they are not able to determine yet why. I have personally experienced this on pretty much every type of Ubuntu system setup by myself and by others. So here are the steps to ensure Confluence actually shuts down,
Code Block | ||
---|---|---|
| ||
ps -ef | grep java | grep confluence |
Then try the ./shutdown.sh
Code Block | ||
---|---|---|
| ||
ps -ef | grep java | grep confluence |
Which usually shows it is still running so then I do,
Code Block | ||
---|---|---|
| ||
kill #### where #### is the process id |
Future Upgrade Notes
s part of planning for future upgrades listed here are the key files to keep in mind,
...
Edit /opt/confluence/conf/server.xml.
Add the Connector directive <Connector port="8009" protocol="AJP/1.3 "URIEncoding="UTF-8" /> just above the Engine directive,
Code Block | ||
---|---|---|
| ||
useURIValidationHack="false" URIEncoding="UTF-8"/>
<Connector port="8009" protocol="AJP/1.3" URIEncoding="UTF-8" />
<Engine name="Standalone" |
Info |
---|
The UTF-8 is important as Confluence is developed to post using UTF-8. Without this setting errors occur when working with attachments containing special characters. Further details are covered in the Bonsai Tomcat Connector article. |
Select and Enable Context Path
Often you want to use the Apache Web Server to front more than one web application. In order to do this you want each web application to work within it's own context. This is pretty standard in most java applications. As such, we will pick a context path, in this case "wiki". As such the original url, http://localhost:8080/ changes to http://localhost:8080/wiki
Modify the bundled Confluence Tomcat Context directive and change the attribute path="" to path="/wiki",
Code Block | ||
---|---|---|
| ||
<Context path="/wiki" docBase="../confluence" debug="0" reloadable="false" useHttpOnly="true"> |
This change does not take effect until the Confluence service stopped and started again. We will do that in the the next section.
Configure Apache Tomcat Connector
Warning |
---|
Still need to fill in clearer instructions on this topic. |
Once port 8009 is enabled, mod_jk can be enabled by following the Apache Tomcat Connector instructions.
Change Base Url in Confluence
Warning |
---|
Put instructions here about changing the base url if fronted by Apache. |
Verify Internationalization Features
Even if you do not plan to have the wiki work for multiple languages, you should verify the internationalization is working properly just to handle special characters.
Visit the http://<host address>:<port>/admin/encodingtest.action url on your system and follow the instructions.
Future Upgrade Notes
As part of planning for future upgrades here is a checklist to keep in mind.
Backup Your Data
It goes without saying, backup your data. With Cloud and Virtual computing take a snap shot. With manual backups you can use Confluence's built in backup utility (provide link to instructions) or manually make the following backups,
- TAR the Confluece data home folder
- Backup the database using your database management tools
Database Password
Make sure you know the admin password for your database.
Key Files
- /opt/confluence/bin/setevn.sh
- /opt/confluence/conf/server.xml
- /opt/confluence/confluence/WEB-INF/classes/confluence-init.properties
- /opt/confluence/bin/shutdown.sh
- /opt/confluence/bin/startup.sh
Optionally, if there was a version mismatch with the jdbc driver,
- /opt/confluence/confluence/WEB-INF/lib/postgresql-8.4-701.jdbc4.jar - add
- /opt\/confluence-3.2.1_01-std\/confluence/WEB-INF/lib/postgresql-8.4-701.jdbc3.jar - remove
The package dependencies change between confluence versions. You should check if there are differences. For example look at the difference between 3.1 and 3.2 ,
confluence-3.1
- libice-dev - nolonger used
- libsm-dev - nolonger used
- libx11-dev - used
- libxext-dev - nolonger used
- libxp-dev - nolonger used
- libxt-dev - nolonger used
- libxtst-dev - used
confluence-3.2
- libx11-6 - new
- libx11-dev - carry over
- libxt6 - new
- libxt6-dbg - new
- libxext6 -new
- libxtst-dev - carry over
- libxtst6 - new
- xlibs-dbg - new
- xlibs-dev - new
Special Modifications
You may choose to modify special files. For example, I modify the footer,
- /opt/confluence/confluence/decorators/includes/footer-content.vm
Plug-Ins
Also, keep a page listing any plugins plug-ins you install. Upgrades generally do not require you to reinstall the plugins but they might be deprecated so make that after . After the upgrade is done, login as Administrator on Confluence and ensure plug-ins are up to date.
Disable Search Engine Indexing
In the case of a private site, you may not want Google or any other search engine to crawl your wiki. Even in the case of a password protected site this will still happen and take up unnecessary bandwidth, processing and bump up the amount of memory consumed by Confluence.
Warning |
---|
This content needs to be refined and should in fact link to a detailed article on robots.txt and other ways of preventing crawling. |
If you had been following the steps outline by the Bonsai Framework the Confluence configuration will be,
- Fronted by Apache
- The root of the website is located at /home/www.krypton.com/www
- The mapping from Apache to Confluence is /wiki/
As such, robots.txt will be placed in the root of the website and look like this,
Code Block |
---|
User-agent: *
Disallow: /wiki/
|
System Profile
Using htop, initial setup without any spaces created is 396MB. The process itself uses VIRT=913M and RES=338M.
#!/bin/sh
# Bonsaiframework - Modification Start
# --------------------------------------
if [ "$LOGNAME" != "svrdm" ]; then
echo "This service should only managed with the user svradm"
exit 1
fi
# --------------------------------------
# Bonsaiframework - Modification End