Setting Up Your Environment for Confluence Plugin Development

Note This page may still provide useful information to some. However, Atlassian has much improved their documentation and tools for development which you should now probably review first. This document was written for plugin development to Confluence version 2.9. Things have changed. Review the following area first... See: How to Build an Atlassian Plugin using the Atlassian Plugin SDK We are in the process of updating this page to make sure it is valid for the new Plugins2 architecture, and the new Atlassian PDK.

Atlassian provides instructions for preparing your development environment to build Confluence plugins. However, those instructions seem to make several assumptions about one's level of knowledge and experience. We have written our own instructions in an effort to provide better clarity - especially around some steps that commonly cause confusion. We have validated and refined these instructions to help your setup go a smoothly as possible - whether you're a seasoned developer or not.

PROCEDURE

• Install the Java JDK
• Configure Maven Options
• Install Apache Tomcat 6
• Install Confluence
  • Advanced - Build Confluence from Source and Install with MySQL Database
  • Alternative - Install Confluence WAR with Embedded Database
• Setup Maven for Confluence
• Start a new plugin
• Import project into eclipse
• Test plugin deployment
• Install Subclipse (optional)
• Install Veloeclipse plugin (optional)

Install the Java JDK

BTG is currently using Java JDK version 1.6.0_10.

If you already have the JDK installed on your machine, you may skip steps 1 and 2 in this section.

1. Download the installation program, jdk-6u10-windows-i586-p.exe, from http://java.sun.com/javase/downloads/index.jsp
2. Run the installation. We recommend changing the default installation path, which is typically C:\Program Files\Java\jdk1.6.0_10\ to C:\Java\jdk1.6.0_10\. Because the 'Program Files' directory has a space character in it, it could cause unnecessary hassles when working with the command line or with scripts. Also simplifying installation paths can help you work more efficiently. Take note of the path you choose for the next step.
3. Add an environment variable to your machine called JAVA_HOME and set its value to the JDK installation directory (for example: C:\Java\jdk1.6.0_10).
   1. Right-click on My Computer and select Properties
   2. Click on the Advanced tab
   3. Click the Environment Variables button
   4. Click the New button to add a new entry in the User Variables section.
   5. Enter 'JAVA_HOME' for the variable name.
   6. Enter the JDK installation path for the variable value.
   7. Click OK, OK, OK to set the new entry and close the the Properties dialog.
4. Optionally, you can validate your installation with the following steps:
   1. Click Start > Run, type 'cmd', and click OK to open the Windows Command window.
   2. Enter the command 'java -version' and hit ENTER. If the JDK has been installed properly, the Java version will be printed.
   3. Now type the command 'cd %JAVA_HOME%' and hit enter. If you set you environment variable properly, this will change the directory in the command window to the JSK installation path.

back to top

Configure Maven Options

It is not necessary to download and install Maven since it comes bundled in the Atlassian PDK. Still, however, you should set Maven Options so that it will have appropriate memory settings for large builds.

1. Add a new environment variable called 'MAVEN_OPTS' with the value '-Xms256m -Xmx512m' (without the single quotes).

back to top

Install Apache Tomcat 6

BTG is currently using Tomcat version 6.0.18

Confluence can run on different application servers, but Tomcat is relatively lightweight, open-source, and free. It's perfect for your local development environment and it can sufficiently support a wiki in your enterprise when properly configured.

1. Download the Tomcat installation from http://tomcat.apache.org/download-60.cgi.
   1. We recommend downloading the Windows Service Installer instead of the zip archive. This will give you the option to install Tomcat to run as a Windows service. You can then set the Tomcat service to start automatically, or configure it to start manually. You will be able to start and stop the Tomcat service from the Services console in Computer Management.
2. Run the installer.
   1. You must select the Service component to install it as a Windows service!
   2. You should also simplify the installation directory so that it sits on the root of your primary drive (C:\Tomcat6, for example).
   3. Leave the port on the default setting (8080) unless this port is already taken on your machine. If the port is in use, you could use port 8081 instead.
   4. Note the administrative username and password that you enter; you may need it to access the Tomcat console at a later date.
   5. On the last screen in the installation, check Run Apache Tomcat and then click Finish.
3. In a web browser, navigate to http://localhost:8080/ to verify that Tomcat is running and has been installed successfully; you should see the Tomcat welcome page.
4. Add an environment variable to your machine called CATALINA_HOME and set its value to the tomcat installation directory (for example: c:\Tomcat6).

Increase Memory Settings for Tomcat

1. Modify the settings
   • For Windows:
     1. Launch the Configure Tomcat application from Start menu > Programs > Apache Tomcat...
     2. Navigate to the Java tab
     3. Enter 1024 in the filed for Maximum Memory Pool
     4. Add the following line to the end of the Java Options field:
        -XX:MaxPermSize=128m
     5. Click Apply, OK
   • For Linux or Mac:
     1. Edit /path-to-tomcat/bin/setenv.sh
     2. Add
        to the end of the file
2. Restart the Tomcat service for these changes to take effect

Caution You should do this before installing Confluence or else Confluence will likely fail with memory problems when it tries to first create its database.

back to top

Install Confluence

Now, it is possible to download and install Confluence as a stand-alone which comes bundled with Tomcat. You can also use an embedded database for development purposes. But so far, we have prepared for a setup that is slightly more involved. We recommend setting up your local environment in a way that more closely mirrors the kind of setup you'd likely have for your production server in the enterprise. If your serious about Confluence plugin development, taking this time up front will provide more benefits to your development over the long-term. It makes upgrades easier, helps you retain test data and pages, and can improve your Confluence administration skills.

There are a few different ways to install Confluence. We give a couple; take your pick. If your serious or seasoned, you may wish to tackle the advanced approach. If you just want to play it safe for now, skip to the alternative approach which should be much less complicated. We do not recommend the stand-alone installation for plugin developers because it avoids a set of experiences and knowledge that we think Confluence plugin developers should go through and have.

Advanced - Build Confluence from Source and Install with MySQL Database

Build Confluence from Source

1. Download the source distribution package of Confluence.
   1. Licensed Confluence users can obtain this from http://my.atlassian.com
   2. Not only will we have the source code for study, but we'll also learn how to build it and deploy it.
2. Extract the source archive to C:\ so you end up with C:\confluence-<version>-source.
3. Open a Windows command prompt and change directory to C:\confluence-<version>-source.
4. Type 'build.bat' and hit ENTER.
   1. The build will commence. It will kick-off a Maven process and start downloading a bunch of dependencies. Unfortunately, it will likely fail on a couple of missing artifacts (click to enlarge example...)
      
5. Luckily, the clues for resolving this are in the output. Note, it says, "Try downloading the file from..." So, download the dependent libraries from the recommended locations. In the next steps, we'll show you how to install them manually into your Maven repository.
   1. Before we continue, however, let's take a look at what just happened. In the Windows File Explorer, navigate to your home directory (typically C:\Documents and Settings\<your name>).
   2. Open the directory '.m2/repository'. You should see several folders where all of the dependencies that were downloaded reside. This is good to know. Maven stores dependencies in your local '.m2' repository.
6. Go ahead and download any missing dependencies from the recommended locations, but do not put them into your .m2 repository. We'll use Maven itself to install them into the repository properly. Here's how:
   1. Download Java Mail from the recommended location: http://java.sun.com/products/javamail/downloads/index.html (into c:\temp, for example).
   2. Download JAF from the recommended location: http://java.sun.com/javase/technologies/desktop/javabeans/glasgow/jaf.html (into c:\temp, for example).
   3. Extract both archives (into C:\temp, for example)
   4. Open a command prompt, change directory to C:\ (the root) and enter the following command (notice the full path to the jar):
      1. If you executed the command from C:\ (root), you should get a BUILD SUCCESSFUL message.
   5. Another example for the second jar:
      1. If you executed the command from C:\ (root), you should get a BUILD SUCCESSFUL message.
7. Now we can try the Confluence build again. In a command prompt change the directory to C:\confluence-2.10-source and execute 'build.bat'.
   1. If you still get a build error, there may still be missing dependencies and you'll have to install them with the same approach. Sometimes, you may have to get a specific version of a library instead of just the latest one. Install any missing dependencies manually until you can build Confluence successfully.
8. You should now be able to find confluence.war in the following path: C:\confluence-2.10-source\confluence-project\conf-webapp\target.

We can soon deploy this war file to Tomcat, but first - let's get MySQL installed and ready.

Download, Install, and Prepare MySQL Database

BTG is currently using MySQL Community Server 5.0.67.

1. Download MySQL Community Server (Windows Essentials package) from: http://dev.mysql.com/downloads/
2. Install MySQL server and note your administrative username and password.
3. Open MySQL Administrator
4. Click on Catalogs
5. Right-click under Schemata and create a new, empty database named 'confluencedb'.
6. Now click User Administration and right-click under User accounts to create a new db user.
7. Create a user named 'confluenceuser' and note the username and password that you use.
8. On the Schema Privileges tab, click confluencedb. Select all available privileges (on the right) and move them to Assigned Priviledges for the user (on the left).
9. Click Apply Changes
10. Now we need to download the JDBC driver for MySQL and place it in the Tomcat environment so that it will be available for Confluence to use.
    1. Download the MySQL Connector J driver from http://dev.mysql.com/downloads/connector/j/5.1.html
    2. Unzip the file
    3. Copy or move mysql-connector-java-5.1.7-bin.jar to Tomcat/lib folder (for example, to C:\Tomcat6\lib)

We will soon have to configure Confluence so that it can access this database, but otherwise, there's nothing more to do on this end. Confluence will automatically populate the empty database with the tables it needs after installation.

Edit Tomcat Context Descriptors

1. In the Tomcat installation's conf directory, create a folder called 'Catalina'
2. In the new Catalina directory, create a folder called 'localhost'
3. In the new localhost directory, Create a new file called 'confluence.xml'
4. Open your new confluence.xml and add these lines:

This file, named confluence.xml, tells Tomcat that there is a web-app. It also defines the datasource for the web-app. Since we have pointed the docBase to the war file, that war will be automatically deployed and extracted the first time we stop and restart Tomcat. Let's do that now.

1. Open Control Panel > Administrative Tools > Computer Management (or right-click My Computer and select Manage)
2. Go to Services and Applications > Services
3. Find and stop the service for Apache Tomcat if it is started.
4. Restart the service
5. Now, after a couple of seconds, navigate to the Tomcat webapp folder (for example, C:\Tomcat6\webapps). If you've done your steps right, you should see an exploded war confluence folder inside with lots of files in it). We're getting close.
6. Stop the Tomcat service again.
7. In the deployed (exploded) confluence/WEB-INF/classes folder, create a file called confluence-init.properties with the following single line of contents:
   confluence.home=C:/confluence/data
   1. Note that this tells confluence where to store your attachments and indexes and such. You should keep this path separate from any of your other confluence stuf so that when you upgrade you can always use this same directory independent of everything else.
8. Finally, open the deployed confluence/WEB-INF/web.xml file and add the following stanza just before the closing </web-app> tag:

Do not execute the following steps unless you have increased the memory settings for Tomcat as described previously in the Tomcat installation section. If you skip that step, it is likely that the database setup will fail and you will have to use MySQL to drop tables before attempting these steps again. These steps can also fail if you did not put the mysql-connector-java-5.1.7-bin.jar file in your Tomcat lib folder.

1. Navigate to http://localhost:8080/confluence
2. On the first screen, enter your developer or personal use license key. You can get a developer key directly from Atlassian, or you can get a free personal use license key: http://www.atlassian.com/software/confluence/personal-wiki.jsp
3. Click the Custom Installation button.
4. Under External Database, choose MySQL and click External Database >>
5. Click to Connect via a Datasource (not a Direct JDBC Connection)
6. For the Datasource Name, use: java:comp/env/jdbc/confluence
   1. If that does not work, try just: jdbc/confluence
7. Click Next
   1. Now, be patient. It takes a little time for Confluence to build the database. If you get a failure message, check the Tomcat logs (in C:\Tomcat6\logs for example); they will typically provide a clue to any problems.
   2. If everything goes successfully,you will then have the option to load a demonstration space, create an empty site, or restore from backup. For development purposes, we recommend loading up the demonstration space (Example Site).
8. Configure your administrator account and note the username and password that you use.
9. You should get a Confluence Installation Successful page!

You've completed the advanced installation, so you can skip the next section and proceed instead with the section called Setup Maven for Confluence.

Alternative - Install Confluence WAR with Embedded Database

1. Download the installation, confluence-2.10-std.zip, from http://www.atlassian.com/software/confluence/ConfluenceDownloadCenter.jspa

• Unzip the file to c:\ directory. Verify that the zip file directory structure is preserved.
• Configure confluence-init.properties
  • Open the c:\confluence-2.10-std\confluence\WEB-INF\classes\confluence-init.properties in a text editor.
  • Now define your Confluence Home directory, by setting the confluence.home property to a directory of your choosing. We suggest using different paths for your installation and home directories. This will facilitate upgrades. This is the directory that will contain all of Confluence's configuration, backup and attachment files.
  • Remove the # sign in front of the last line to make c:\confluence\data the data directory.
  • Save the file
    SJ: I'd recommend modding the confluence .zip directly to have this edit already completed

• Edit Tomcat Context Descriptors
  • In the Tomcat installation's conf directory (c:\apache-tomcat-6.0.18\conf) Create a folder called 'Catalina'
  • In the new Catalina directory, create a folder called 'localhost'
  • In the new localhost directory, Create a new file called 'confluence.xml'
  • Open your new confluence.xml and add these lines:

• • Note the docBase attribute points to the confluence webapp(folder) within the confluence install
    SJ: I'd recommend modding the confluence .zip directly to have this edit already completed

• Verify Confluence installation
  • Start tomcat
  • Open a browser to http://localhost:8080/confluence
  • You'll be prompted to enter your license key. You can get a developer key directly from Atlassian, or you can get a free personal use license key: http://www.atlassian.com/software/confluence/personal-wiki.jsp
    (Click to enlarge)
    
    
    
    
  • After entering your key, Click Standard Installation to continue the setup process. This may take a couple minutes.
    (Click to enlarge)
    
    
    
    
  • Then you will be prompted to setup the admin account. Fill in the fields and click Next. Remember the username and password, you'll need them soon.
    (Click to enlarge)
    
    
    
    
  • Setup is complete
    (Click to enlarge.)
    
    
    
    

back to top

Setup Maven for Confluence

In order for Maven to find and download all of the necessary dependencies for confluence, we have to tell it where everything is stored. The best option is to do that once, in your $HOME/.m2/settings.xml file. $HOME is the home directory for the logged in user.

If on windows:

• Open a command prompt
• Type 'cd %HOMEPATH%'
• Type 'dir' and hit ENTER to get a listing of directories. Check to see if a folder called '.m2' exists already. If it does not:
  • type 'mkdir .m2'
• Navigate into this new folder and copy this file (settings.xml) http://confluence.atlassian.com/display/DEVNET/Example+settings.xml
• Verify the properties below match your confluence admin settings (in other words, make sure that the url and port matches that through which you access your local Confluence site and that the username and password match your administrator credentials.)

back to top

Start a new plugin

• We're planning on doing our plugin development inside eclipse, so you'll need a folder for your eclipse workspace (for example, c:\workspace). Go ahead and create that folder now.
• From a command prompt, enter the folder and execute the following command. Replace MY_PACKAGE with the java package(for example: com.acme.confluence) for your source code and replace MY_PLUGIN with the name of your plugin (for example: TestPlugin). Copy the code stanza below and paste it into a text document; be sure to bring it all up on a single line.

For Example...

• Convert the project structure to an eclipse project by running the following command. You will first have to enter the newly created folder (matching MY_PLUGIN above). Verify there is a pom.xml file in this folder before running the command.
  • If this errors out immediately you may have an issue with maven and your settings.xml. A workaround is to include an extra switch to point directly at your edited settings.xml
• Sun will not allow Maven to redistribute its binaries. You must install all Sun binaries manually by downloading them from Sun's website and running the mvn install command. If you followed the advanced Confluence setup path described previously, then you probably already have installed all of the Sun jar files manually (you can skip the next 3 sub-steps).
  • Download jaf-1_0_2-upd2.zip from http://java.sun.com/javase/technologies/desktop/javabeans/glasgow/jaf.html
  • Unzip the files to a temporary directory, like c:\temp.
  • Install the library using the following command. Replace c:\temp if neeeded.
• Verify you can deploy your plugin using maven
  • From your project folder (MY_PLUGIN) run the following command
    • This should complete with a message similar to:

• Validate that the plugin has truly been installed in Confluence. In Confluence, navigate to Confluence Admin and click Plugins under the Configuration section. You should be able to see your plugin in the list of plugins by the name you gave as the ArtifactId (e.g. MyTestPlugin).

back to top

Install Eclipse

BTG is currently using Eclipse version 3.4.1 (Ganymede)

• Download the installation program,
  Eclipse IDE for Java EE Developers (eclipse-jee-ganymede-SR1-win32.zip), from http://www.eclipse.org/downloads/
• Unzip the file to c:\ (root) directory. Verify that the zip file directory structure is preserved.

back to top

Import project into eclipse

• Before starting eclipse, run the following command. Replace <path-to-eclipse-workspace> with your workspace folder configured earlier (for example: c:\workspace). This step ensures that dependencies in your Maven repository will be on the classpath for your project and thus, you will not get build errors from within eclipse.

• Start eclipse. Browse to your workspace folder when prompted.
• Import the project. Go to File->Import
  (Click to enlarge...)
  
  
  
  
• Select Existing Projects into Workspace
  (Click to enlarge...)
  
  
  
  
• Use browse and the file chooser to find the location of your plugin. This should be the same directory with the pom.xml. Click Finish.
  (Click to enlarge...)
  
  
  
  
• If there's a splash screen for the main page, go ahead and close it. You should then see the Project Explorer view. On the left should be your plugin, it's source code and all the libraries it has dependencies on. If you open the src/main/java package you should see the ExampleMacro.java file. This is the code that's running in the plugin you've deployed. Let's go ahead and test that functionality.

back to top

Test plugin deployment

• Open a browser to http://localhost:8080/confluence
• Click on the Demonstration Space link so we can do some edits
  (Click to enlarge...)
  
  
  
  
• Click on Edit
  (Click to enlarge...)
  
  
  
  

• You should then see a form like this. Find the section under the picture in the text editor.
  (Click to enlarge...)
  
  
  
  

• Enter the name of your plugins in curly brackets like 'test' below
  (Click to enlarge...)
  
  
  
  
• Click on the preview tab to see the results. Your plugin's ExampleMacro.java is the code behind all that text.
  (Click to enlarge...)
  
  
  
  
• Go back to eclipse and find this line in ExampleMacro.java

and replace it with:

• Save the file (Ctrl-S).

• From the command prompt, navigate to your plugin directory and run the same command as before:

• Go back to your open confluence session and click on the Rich Text tab, then the Preview tab again. You should see the text has changed:

(Click to enlarge...)

back to top

Install Subclipse (optional)

Subclipse is used to add Subversion integration to Eclipse. If you plan to work with a team, we recommend using Subversion for your source code repository.

• Start eclipse (c:\eclipse\eclipse.exe)
• Begin the installation from the Eclipse Help menu item.
  (Click to enlarge...)
  
  
  
  

• Click on the Available Software tab to get to this screen and then select Add Site...
  (Click to enlarge...)
  
  
  
  

• Enter 'http://subclipse.tigris.org/update_1.4.x' in the Location text field. Click OK.
  (Click to enlarge...)
  
  
  
  

• Select Subclipse(required) and JavaHL Adapter(recommended). Then click the Install... button.
  (Click to enlarge...)
  
  
  
  

• Click Next->
  (Click to enlarge...)
  
  
  
  

• Choose to accept the license agreements and click finish.
  (Click to enlarge...)
  
  
  
  

• After installation, you may be prompted to restart eclipse. Choose yes.
  (Click to enlarge...)
  
  
  
  

Install Veloeclipse plugin (optional)

The Veloeclipse plugin for eclipse is an HTML and Velocity editor for eclipse. It provides some syntax coloring and other features that can make it a little easier to edit Velocity files for Confluence.

Update Site: http://propsorter.sourceforge.net/veloeclipse

After installation, you might have to right-click .vm files and select to Open With > Veloeclipse. They should open with Veloeclipse automatically from then on.