confluence

#puppet-confluence

Table of Contents

1. Overview
2. Module Description - What the module does and why it is useful
3. Setup - The basics of getting started with Confluence
   • Confluence Prerequisites
   • What Confluence affects
   • Beginning with Confluence
4. Usage - Configuration options and additional functionality
5. Reference - An under-the-hood peek at what the module is doing and how
6. Limitations - OS compatibility, etc.
7. Development - Guide for contributing to the module

Overview

This is a puppet module to install and handle upgrades of Atlassian Confluence. Confluence is team collaboration software.

Module Description

This module installs/upgrades Atlassian Confluence. The Confluence module also manages the Confluence configuration files with Puppet.

Setup

Confluence Prerequisites

• Confluence require a Java Developers Kit (JDK) or Java Run-time Environment (JRE) platform to be installed on your server's operating system. Oracle JDK / JRE (formerly Sun JDK / JRE) versions 1.7 and 1.8 are currently supported by Atlassian.

:warning: There's a known issue with Java 1.8.0_25 and 1.8.0_31, and another known issue with 1.7.0_25 and 1.7.0_45. Atlassian don't recommend running Confluence on these versions.

• Confluence requires a relational database to store its configuration data. Unfortunatly it is not possible to do the initial configuration (Database setup) of confluence with puppet (See issue #3 - No database support). The configuration needs to be done via the web GUI.

What Confluence affects

If installing to an existing Confluence instance, it is your responsibility to backup your database. We also recommend that you backup your Confluence home directory and that you align your current Confluence version with the version you intend to use with puppet Confluence module.

You must have your database setup with the account user that Confluence will use. This can be done using the puppetlabs-postgresql and puppetlabs-mysql modules.

When using this module to upgrade Confluence, please make sure you have a database/Confluence home backup.

The following resources are potentially effected by this module:

• confluence user
• confluence init script
• setenv.sh
• confluence-init.properties
• server.xml

Beginning with Confluence

This puppet module will automatically download the Confluence tar.gz from Atlassian and extracts it into /opt/confluence/atlassian-confluence-$version. The default Confluence home is /home/confluence.

  class { 'confluence':
    javahome => '/opt/java', 
  }

Usage

This module also allows for direct customization of the JVM, following atlassians recommendations

This is especially useful for setting properties such as http/https proxy settings. Support has also been added for reverse proxying confluence via apache or nginx.

####A more complex example

  class { 'confluence':
    version        => '5.7.1',
    installdir     => '/opt/atlassian/atlassian-confluence',
    homedir        => '/opt/atlassian/application-data/confluence-home',
    javahome       => '/opt/java',
    java_opts      => '-Dhttp.proxyHost=proxy.example.com -Dhttp.proxyPort=3128 -Dhttps.proxyHost=secure-proxy.example.com -Dhttps.proxyPort=3128'
    proxy          => {
      scheme       => 'https',
      proxyName    => 'confluence.example.co.za',
      proxyPort    => '443',
    },
  }

####Hiera example

This example is used in production for 2000+ users in an traditional enterprise environment. Your mileage may vary.

confluence::user:           'confluence'
confluence::group:          'confluence'
confluence::shell:          '/bin/bash'
confluence::dbserver:       'dbvip.example.co.za'
confluence::version:        '5.7.1'
confluence::installdir:     '/opt/atlassian/atlassian-confluence'
confluence::homedir:        '/opt/atlassian/application-data/confluence-home'
confluence::javahome:       '/opt/java'
confluence::java_opts:      '-Dhttp.proxyHost=proxy.example.co.za -Dhttp.proxyPort=8080 -Dhttps.proxyHost=proxy.example.co.za -Dhttps.proxyPort=8080 -Dhttp.nonProxyHosts=localhost\|127.0.0.1\|172.*.*.*\|10.*.*.*\|*.example.co.za -XX:+UseLargePages'
confluence::manage_service: false
confluence::tomcat_port:    '8090'
confluence::jvm_xms:        '4G'
confluence::jvm_xmx:        '8G'
confluence::jvm_permgen:    '512m'
confluence::downloadURL:    'http://webserver.example.co.za/pub/software/development-tools/atlassian'
confluence::tomcat_proxy:
  scheme:    'https'
  proxyName: 'webvip.example.co.za'
  proxyPort: '443'

Reference

###Classes

####Public Classes

• confluence: Main class, manages the installation and configuration of Confluence.

####Private Classes

• confluence::install: Installs Confluence binaries
• confluence::config: Modifies Confluence/tomcat configuration files
• confluence::service: Manage the Confluence service
• confluence::facts: Class to get the running version of confluence
• confluence::params: Default params

###Parameters

####Confluence parameters####

#####javahome Specify the java home directory. No assumptions are made re the location of java and therefor this option is required. Default: undef #####version The version of confluence to install. Default: '5.5.6' #####format The format of the file confluence will be installed from. Default: 'tar.gz' #####installdir The installation directory of the confluence binaries. Default: '/opt/confluence' #####homedir The home directory of confluence. Configuration files are stored here. Default: '/home/confluence' #####user The user that confluence should run as, as well as the ownership of confluence related files. Default: 'confluence' #####group The group that confluence files should be owned by. Default: 'confluence' #####uid Specify a uid of the confluence user. Default: undef #####gid Specify a gid of the confluence user. Default: undef #####shell Specify the shell of the confluence user. Default: undef

####JVM Java parameters####

#####jvm_xms The initial memory allocation pool for a Java Virtual Machine. Default: '256m' #####jvm_xmx Maximum memory allocation pool for a Java Virtual Machine. Default: '1024m' #####jvm_permgen Increase max permgen size for a Java Virtual Machine. Default: '256m' #####java_opts Additional java options can be specified here. Default: ''

####Tomcat parameters#### ####tomcat_proxy Reverse https proxy configuration. See customization section for more detail. Default: {} #####tomcat_port Port to listen on, defaults to '8090' #####tomcat_max_threads Defaults to '150' #####tomcat_accept_count Defaults to '100' #####tomcat_extras Any additional tomcat params for server.xml. Takes same format as tomcat_proxy. Default: {}

####Miscellaneous parameters####

#####manage_server_xml Should we use augeas to manage server.xml or a template file. Defaults to 'augues'. Operating systems that do not have a support version of Augeas such as Ubuntu 12.04 can use 'template'. #####downloadURL Default: 'http://www.atlassian.com/software/confluence/downloads/binary/' #####manage_service Should puppet manage this service? Default: true #####staging_or_deploy Choose whether to use nanliu-staging, or mkrakowitzer-deploy. Defaults to 'staging' to use nanliu-staging as it is puppetlabs approved. Alternative option is 'deploy' to use mkrakowitzer-deploy. #####stop_confluence If the Confluence service is managed outside of puppet the stop_confluence paramater can be used to shut down confluence for upgrades. Defaults to 'service confluence stop && sleep 15' #####facts_ensure Enable external facts for confluence version. Defaults to present.

Limitations

• Puppet 3.4+
• Puppet Enterprise

The puppetlabs repositories can be found at: http://yum.puppetlabs.com/ and http://apt.puppetlabs.com/

• RedHat / CentOS 5/6/7
• Ubuntu 12.04 / 14.04
• Debian 7

Operating Systems without an Augueas version >= 1 such as Ubuntu 12.04 must use the paramater:

manage_server_xml => 'template',

We plan to support other Linux distributions and possibly Windows in the near future.

Development

See CONTRIBUTING.md

Contributors

See CONTRIBUTORS

##2014-03-22 - Release 2.1.1

• Rewrite README file
• Bump confluence version to 5.7.1
• Update metadata, CHANGELOG to point to new namespace.
• Add .pmtignore file

##2014-03-22 - Release 2.1.0

Note: This is the final release of this module before it is deprecated with a 999.999.999 version. This module will be moving the the puppet-community namespace on github and the puppet namespace on puppetforge soon.

• Make confluence users shell configurable.
• update README, metadata, .travis.yml
• Add CONTRIBUTING.md and test coverage spec.

##2014-01-23 - Release 2.0.1

• Resolve issue #22 - confluence_version fact detects wrong version
• Resolve issue #20 - param manage_server_xml acceptCount option is duplicated

##2014-01-21 - Release 2.0.0

• Replace mkrakowitzer-deploy with nanlui-staging as default for dropping files.
  • Add tests
• Resolve issue #7 Make tomcat port / tomcat parameters configurable.
• Add parameter manage_server_xml, tomcat_max_threads, tomcat_accept_count, tomcat_extras.
  • Add tests
• rename parameter proxy to tomcat_proxy, port to tomcat_port.
• Add support for STRICT_VARIABLES=yes FUTURE_PARSER=yes
• Resole issue #6 Handle confluence upgrades smoothly
  • This will stop confluence if running version is less than manifest version. Attempt to upgrade and then start confluence.