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'
    tomcat_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::download_url:    'http://webserver.example.co.za/pub/software/development-tools/atlassian'
confluence::catalina_opts:
  - -Dconfluence.cluster.node.name=%{hostname}
  - -Dconfluence.upgrade.recovery.file.enabled=false
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

manage_user

Whether or not to manage the confluence user. Default: true

context_path

Specify context path, defaults to ''. If modified, Once Confluence has started, go to the administration area and click General Configuration. Append the new context path to your base URL.

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: ''

catalina_opts

Additional catalina options can be specified either as a simple string or array of strings. 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: {}

Crowd single sign on parameters

enable_sso

Enable crowd single sign on configuration as described in https://confluence.atlassian.com/display/CROWD/Integrating+Crowd+with+Atlassian+Confluence#IntegratingCrowdwithAtlassianConfluence-2.2EnableSSOintegrationwithCrowd(Optional)

application_name

Set crowd application name

application_password

Set crowd application password

application_login_url

Set crowd application login url, where to login into crowd (e.g. https://crowd.example.com/console/)

crowd_server_url

Set crowd application services url, e.g. https://crowd.example.com/services/

crowd_base_url

Set crowd base url, e.g. https://crowd.example.com/

session_isauthenticated

Some more crowd.properties for SSO, see atlassian documentation for details

session_tokenkey

Some more crowd.properties for SSO, see atlassian documentation for details

session_validationinterval

Some more crowd.properties for SSO, see atlassian documentation for details

session_lastvalidation

Some more crowd.properties for SSO, see atlassian documentation for details

Miscellaneous parameters

manage_server_xml

Should we use augeas to manage server.xml or a template file. Defaults to 'augeas'. Operating systems that do not have a support version of Augeas such as Ubuntu 12.04 can use 'template'.

download_url

The URL used to download the JIRA installation file. Defaults to 'https://www.atlassian.com/software/confluence/downloads/binary'

checksum

The md5 checksum of the archive file. Only supported with deploy_module => archive. Defaults to 'undef'.

proxy_server

Specify a proxy server, with port number if needed. ie: https://example.com:8080. Only supported with deploy_module => archive (the default). Defaults to 'undef'.

proxy_type

Proxy server type (none|http|https|ftp) Only supported with deploy_module => archive (the default). Defaults to 'undef'.

manage_service

Should puppet manage this service? Default: true

deploy_module

Module to use for downloading and extracting archive file. Supports puppet-archive and puppet-staging. Defaults to 'archive'. Archive supports md5 hash checking and Staging supports S3 buckets.

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.

mysql_connector_version

Specify the version of mysql_connector_version you want to use. Defaults to 5.1.47.

mysql_connector_install

Specify where you want to install mysql connector . Defaults to /opt/MySQL-connector

mysql_connector

Should the module deploy mysql_connector for mysql databases ? . Default to false

Limitations

• Puppet 5.5.8 or newer

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

• RedHat / CentOS 6/7
• Ubuntu 16.04 / 18.04
• Debian 9

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

Changelog

All notable changes to this project will be documented in this file. Each new release typically also includes the latest modulesync defaults. These should not affect the functionality of the module.

v6.0.0 (2024-01-24)

Full Changelog

Breaking changes:

• Fix modulesync 7.2.0 tests; Drop Debian/Ubutnu 16.04 support #232 (h-haaks)
• Drop Puppet 6 support #228 (bastelfreak)

Implemented enhancements:

• feat: stdlib9 and puppet8 compatibility #231 (dploeger)

Merged pull requests:

• Add variable to configure maxHttpHeaderSize attribute #221 (danifr)

v5.0.0 (2022-12-02)

Full Changelog

Breaking changes:

• Fix modulesync; Drop EoL CentOS 6 support #223 (h-haaks)
• made systemd daemon reload dependent on puppet version; Drop Puppet 5 support #213 (KoenDierckx)

Implemented enhancements:

• Add tomcat_redirect_port variable to customise redirectPort in server.xml #220 (techtino)
• Integrated java parameters added or changed in Confluence 7.12 #218 (timdeluxe)

Fixed bugs:

• fix mysql connector source path #207 (SimonHoenscheid)

Closed issues:

• mysql connector not found where module is looking for it #206
• Add tomcat SSL Support #194
• Support for the binary installer? #116

Merged pull requests:

• If manage_user=false, don't depend on the User resource (obsoletes #198) #216 (optiz0r)
• Allow stdlib 8.0.0 #215 (smortex)
• allow newer dependencies/drop staging module dep #214 (bastelfreak)
• Increase mysql_java_connector max version limit #209 (kobybr)
• modulesync 3.0.0 & puppet-lint updates #208 (bastelfreak)
• Allow defining additional Tomcat connectors #205 (antaflos)
• moving end statement to allow values from java_opts to be applied to … #188 (Tokynet)

v4.0.0 (2020-05-10)

Full Changelog

Breaking changes:

• drop EOL Ubuntu 14.04 #187 (bastelfreak)
• modulesync 2.5.1 & drop Puppet 4 #184 (bastelfreak)

Implemented enhancements:

• Add support for Java11 (logging options) #197 (jake2184)
• Manage mysql connector #189 (hdep)
• use service_provider fact to detect systemd, support Debian 9 #183 (rrotter)
• Add support for 18.04 #180 (baurmatt)

Fixed bugs:

• Don't create confluence.cfg.xml #182 (rrotter)

Closed issues:

• Support Ubuntu 18.04 #179
• check debian support #158
• spec tests fail when run on non-Debian OSes #135
• example request #127
• Module puppet/staging marked deprecated #123
• Should default to https for Confluence download URL #61
• Support the mysql connector natively #34

Merged pull requests:

• Use voxpupuli-acceptance #199 (ekohl)
• Remove duplicate CONTRIBUTING.md file #195 (dhoppe)
• Clean up acceptance spec helper #192 (ekohl)
• Add mysql_connector parameters to README #190 (hdep)
• Allow puppetlabs/stdlib 6.x and puppet/archive 4.x #186 (alexjfisher)
• replace deprecated has_key() with in #176 (bastelfreak)
• replace validate_* with assert_type in init.pp #175 (bastelfreak)
• confluence.cfg.xml little automation #170 (posteingang)

v3.2.0 (2018-10-20)

Full Changelog

Implemented enhancements:

• Update setenv.sh to support CATALINA_OPTS #167 (TJM)

Fixed bugs:

• setenv.sh is being broken by the puppet-confluence module #155

Merged pull requests:

• modulesync 2.1.0 and allow puppet 6.x #168 (bastelfreak)

v3.1.2 (2018-09-07)

Full Changelog

Fixed bugs:

• User 'confluence' isn't being created in /etc/passwd #153

Merged pull requests:

• allow puppetlabs/stdlib 5.x #164 (bastelfreak)
• puppet/archive 3.x and puppet/staging 3.x #162 (bastelfreak)
• Remove docker nodesets #159 (bastelfreak)
• drop EOL OSs; fix puppet version range #157 (bastelfreak)

v3.1.1 (2018-03-28)

Full Changelog

Closed issues:

• Something wrong in puppet-confluence/manifests/init.pp #131

Merged pull requests:

• bump puppet to latest supported version 4.10.0 #151 (bastelfreak)
• allow camptocamp/systemd 2.X #149 (bastelfreak)

v3.1.0 (2017-11-26)

Full Changelog

Implemented enhancements:

• Ubuntu 16.04 Support (systemd) #142 (KoenDierckx)

Merged pull requests:

• release 3.1.0 #144 (bastelfreak)
• migrate from topscope variables to facts hash #143 (bastelfreak)
• Ubuntu 16.04 Support (systemd) #133 (marcofl)

v3.0.0 (2017-10-11)

Full Changelog

Implemented enhancements:

• Add proxy support when using 'archive' #138 (bt-lemery)
• set confluence.home to homedir if data_dir is empty #112 (kpankonen)

Fixed bugs:

• confluence.home isn't set if data_dir isn't parameter isn't set #111
• Fix augeas expression to properly set context path instead of failing silently with multiple contexts #130 (Tokynet)
• Fix $homedir typo #128 (binford2k)

Closed issues:

• $data_dir should be documented in ReadMe #129
• Support for Puppet 4 #39

Merged pull requests:

• release 3.0.0 #139 (bastelfreak)
• Use 'ps' for version fact #137 (joshbeard)
• Fix incorrect failures with rspec-puppet-facts #136 (op-ct)
• Issue 119: updated facter script to not report java version #124 (senax)
• replace validate_* with puppet4 datatypes & fix archive errors #122 (bastelfreak)

v2.3.0 (2017-02-11)

Full Changelog

Closed issues:

• Error in /etc/facter/facts.d/confluence_facts.sh - [[: not found #82

Merged pull requests:

• modulesync 0.16.8 #110 (nibalizer)
• modulesync 0.16.7 #109 (bastelfreak)
• Bump minimum version dependencies (for Puppet 4) #108 (juniorsysadmin)
• modulesync 0.16.6 #107 (bastelfreak)
• modulesync 0.16.4 #106 (bastelfreak)
• Bump puppet minimum version_requirement to 3.8.7 #105 (juniorsysadmin)
• Exposes checksum_verify in init.pp w/ conditional. #103 (sacres)
• modulesync 0.16.3 #102 (bastelfreak)
• Use https instead of http #101 (dhoppe)
• Add support for configuring an AJP connector #98 (JCotton1123)
• Update based on voxpupuli/modulesync_config 0.16.2 #96 (dhoppe)
• Make confluence_version a First Class Fact #95 (spjmurray)
• Revert "Make confluence_version a First Class Fact" #94 (dhoppe)
• Allow System Group #93 (spjmurray)
• Make confluence_version a First Class Fact #92 (spjmurray)
• Modulesync 0.15.0 #91 (alexjfisher)
• Added parameter for alternative data dir #90 (tgeci)
• Add missing badges #89 (dhoppe)
• Update based on voxpupuli/modulesync_config 0.14.1 #88 (dhoppe)
• Update based on voxpupuli/modulesync_config 0.13.3 #87 (dhoppe)
• modulesync 0.13.0 #86 (bbriggs)
• Update based on voxpupuli/modulesync_config 0.12.7 #85 (dhoppe)
• Update based on voxpupuli/modulesync_config 0.12.6 #84 (dhoppe)
• make facts.sh sh compatible #83 (mookie-)

v2.2.2 (2016-08-18)

Full Changelog

Closed issues:

• Parameter name in README is wrong #76
• Clean install fails #74

Merged pull requests:

• Modulesync 0.12.1 & Release 2.2.2 #81 (bastelfreak)
• modulesync 0.11.1 #80 (bastelfreak)
• modulesync 0.11.0 #79 (bastelfreak)
• Update README.md #78 (circuitousNerd)
• modulesync 0.9.1 #77 (bastelfreak)
• Fixes #74 : Correct confluence_version to fix clean install on Puppet 4 #75 (jhg03a)
• Modulesync 0.8.0 #73 (bastelfreak)
• Update based on voxpupuli/modulesync_config #72 (dhoppe)

v2.2.1 (2016-05-12)

Full Changelog

Merged pull requests:

• Release 2.2.1 #71 (bastelfreak)

v2.2.0 (2016-05-08)

Full Changelog

Closed issues:

• Where is the template confluence.service.erb #47
• Missing default value for $javahome. #43
• Add SSL Support #38
• Need ability to set context path. #36
• Submit to puppet forge under "puppetcommunity" vendor #32
• Add \<Context> path attribute as a parameter for jira class #21
• Add systemd service file for RHEL7 #19
• Readme needs to be rewritten to comply with puppetlabs guidelines. #17

Merged pull requests:

• add note about the original author #70 (bastelfreak)
• prepare for 2.2.0 release #68 (bastelfreak)
• Update based on voxpupuli/modulesync_config #66 (dhoppe)
• Update based on voxpupuli/modulesync_config #64 (dhoppe)
• Update based on voxpupuli/modulesync_config #63 (dhoppe)
• Use module voxpupuli/archive instead of mkrakowitzer/deploy #60 (dhoppe)
• Remove uppercase parameters #59 (dhoppe)
• Check for required parameter javahome #58 (dhoppe)
• Add crowd SSO functionality #57 (patricktoelle)
• Update based on voxpupuli/modulesync_config #56 (dhoppe)
• Fix TravisCI badge #52 (juniorsysadmin)
• centos 7 service template fixes #51 (hypertext418)
• Prepare for 2.2.0 release #50 (juniorsysadmin)
• Deprecate the downloadURL parameter #49 (juniorsysadmin)
• Install systemd file before starting #48 (ericlaflamme)
• Add systemd unit file #46 (jasonhancock)
• Moved initscript into service module and template uses variable #41 (jacobmw)
• Manage context_path #40 (joshbeard)
• Add manage_user parameter #37 (choffee)
• Update metadata.json w/ stdlib 4 #35 (dudemcbacon)

2.1.1 (2015-03-22)

Full Changelog

Closed issues:

• update .travis.yaml to deploy to puppet-community #28
• make confluence users shell configurable. #25
• confluence_version fact does not correctly pick up running version #22
• When using param manage_server_xml => 'template' acceptCount option is duplicated. #20
• Init script for Debian is missing LSB-Tags #9
• Make MaxPermSize parameter configurable #8
• Make tomcat port / tomcat parameters configurable #7
• handle confluence upgrades smoothly #6
• replace deploy module with staging as the default. #5

Merged pull requests:

• Namespace change #31 (mkrakowitzer)
• (Issue #28) Update .travis.yml to autodeploy module #30 (mkrakowitzer)
• Bump to version 2.1.0 #27 (mkrakowitzer)
• Issue #25 Make confluence users shell configurable. #26 (mkrakowitzer)
• Issue20 #24 (mkrakowitzer)
• Resolve #22 - confluence_version fact detects wrong version #23 (mkrakowitzer)
• Issue6 #18 (mkrakowitzer)
• Make tomcat port / tomcat parameters configurable #7 #16 (mkrakowitzer)
• Enable strict mode for travis tests #15 (mkrakowitzer)
• F3792625/prep for v2 #14 (mkrakowitzer)
• (Issue #5) Replace mkrakowitzer-deploy with nanliu-staging #13 (mkrakowitzer)
• Add initial beaker acceptance tests #12 (mkrakowitzer)
• Update and add missing LSB information to init script. Resolves issue #9 #11 (mkrakowitzer)
• rename rspec-tests and add test for the main class #10 (gerhardsam)
• F3792625/permgen #4 (mkrakowitzer)
• F3792625/add tests #2 (mkrakowitzer)
• Changes to ensure confluence service starts on reboot #1 (brucem)

* This Changelog was automatically generated by github_changelog_generator