Configuring a Confluence cluster in AMPS

Configuring a Confluence cluster in AMPS involves three main steps:

Setting up an external database

Whereas non-Data Center products can run with an embedded H2 or HSQL database, Data Center products require an external database to which all nodes connect. As an AMPS or SDK user, it is up to you to provision that database. See Setting up an external database for more details.

Preparing the home directory

To explain how to configure the home directory for clustered mode, we first need to review how the home directory works in non-clustered mode.

Non-clustered mode

In non-clustered mode, each product by default uses a pre-prepared home directory in which the configuration files specify an embedded H2 or HSQL database. These home directories are shipped as Maven artifacts, with the same version as the product release to which they relate. For example, when running Confluence 7.12.3, AMPS uses version 7.12.3 of the Maven artifact com.atlassian.confluence.plugins:confluence-plugin-test-resources:zip. If we unzip this artifact, we see that it’s a Confluence home directory:

1
2
.
└── confluence-home
├── attachments
├── confluence.cfg.xml
├── database
├── index
└── synchrony-args.properties

If we then open the main configuration file confluence.cfg.xml, we see that Confluence is configured to use an H2 database:

1
2
<?xml version="1.0" encoding="UTF-8"?>
<confluence-configuration>
  <setupStep>complete</setupStep>
  <setupType>install</setupType>
  <buildNumber>8703</buildNumber>
  <properties>
    <property name="hibernate.connection.driver_class">org.h2.Driver</property>
    <property name="hibernate.connection.isolation">2</property>
    <property name="hibernate.connection.password"></property>
    <property name="hibernate.connection.username">sa</property>
    <property name="hibernate.dialect">com.atlassian.confluence.impl.hibernate.dialect.H2V4200Dialect</property>
    ...
  </properties>
</confluence-configuration>

Because this H2 database runs in the same JVM as Confluence, it’s unsuitable for clustered mode.

Clustered mode

In clustered mode, the product requires an external database. You achieve this by providing your own home ZIP (instead of the default one described above), in which the database configuration file (in this example, confluence.cfg.xml) contains the details of that external database:

1
2
<?xml version="1.0" encoding="UTF-8"?>
<confluence-configuration>
  <setupStep>complete</setupStep>
  <setupType>cluster</setupType>
  <buildNumber>8703</buildNumber>
  <properties>
    <property name="hibernate.connection.driver_class">org.postgresql.Driver</property>
    <property name="hibernate.connection.password">theProductPassword</property>
    <property name="hibernate.connection.url">jdbc:postgresql://localhost:5432/confdb</property>
    <property name="hibernate.connection.username">theProductUser</property>
    <property name="hibernate.dialect">com.atlassian.confluence.impl.hibernate.dialect.PostgreSQLDialect</property>
    <property name="hibernate.setup">true</property>
    ...
  </properties>
</confluence-configuration>

The easiest and most reliable way to generate such a home ZIP (for any product) is as follows:

1. Open a terminal within your plugin project.
2. Start the product as normal, then shut it down, to populate the target/home directory.
3. Make the product run in setup mode, as follows:
   • Bitbucket: clear out the home directory
   • Confluence: move or rename home/confluence.cfg.xml
   • Crowd: move or rename home/crowd.cfg.xml
   • Jira: move or rename home/dbconfig.xml
4. Start the product as normal, for example using atlas-run, mvn amps:run, or mvn jira:run. For Bitbucket, run mvn amps:run -Datlassian.dev.mode=false to prevent skipping the setup.
5. Point your browser to the product’s base URL; the product should open in setup mode.
6. Manually step through the setup wizard in your browser. Note:
   • You do not need to set up for clustered mode. AMPS does this for you later.
   • When you arrive at the page about the database connection, enter the details of your external database.
7. Once setup is complete, shut down the product. Important: do not clean it.
8. Still within your plugin project directory, create a home ZIP via either:
   • the plugin SDK, using the atlas-create-home-zip command, or
   • AMPS directly, using mvn <product>:create-home-zip or mvn amps:create-home-zip, depending on which AMPS plugin is configured in your POM.

Once you have your home ZIP:

1. Move the home ZIP to the version-controlled part of your plugin project; a separate directory in the root called home-zips is a good place, as it avoids the home ZIP being bundled into either your production plugin or your test plugin, if you have one.

2. Rename the home ZIP from generated-test-resources.zip to something more descriptive, such as postgres-home.zip.

3. Configure AMPS to load your custom home ZIP instead of the default one, by setting <productDataPath>, either globally, as below, or within the relevant <product> element:

   1
   2
   <configuration>
       <productDataPath>${basedir}/home-zips/postgres-home.zip</productDataPath>
       ...
   

Configuring your POM

To configure your POM, you must do the following:

• Configure the nodes.
• Configure the license.

Configuring the nodes

You configure the nodes by adding them to your AMPS configuration. See Configuring the nodes for more details.

Configuring the license

To run in a cluster, Atlassian products require a Data Center license. If the default license provided by AMPS is not a Data Center license, or does not suit your purposes for some other reason, AMPS 8.2 and later allows you to replace the default license with one you provide, such as one obtained from My Atlassian or developer.atlassian.com.

To do this, add the desired license to your AMPS configuration, either at the global level, the <product> level, or both:

Global level

1
2
<plugin>
    <groupId>com.atlassian.maven.plugins</groupId>
    <artifactId>amps-maven-plugin</artifactId>
    <version>8.3.0</version>
    <extensions>true</extensions>
    <configuration>
        <productLicense>
            loremipsumdolorsitametconsecteturadipiscingelitseddoeius
            modtemporincididuntutlaboreetdoloremagnaaliquautenimadmi
            nimveniamquisnostrudexercitationullamcolaborisnisiutaliq
            uipexeacommodoconsequatduisauteiruredolorinreprehenderit
        </productLicense>
        ...
    </configuration>

Product level

1
2
<plugin>
    <groupId>com.atlassian.maven.plugins</groupId>
    <artifactId>amps-maven-plugin</artifactId>
    <version>8.3.0</version>
    <extensions>true</extensions>
    <configuration>
        <products>
            <product>
                <license>
                    loremipsumdolorsitametconsecteturadipiscingelitseddoeius
                    modtemporincididuntutlaboreetdoloremagnaaliquautenimadmi
                    nimveniamquisnostrudexercitationullamcolaborisnisiutaliq
                    uipexeacommodoconsequatduisauteiruredolorinreprehenderit
                </license>
                ...
            </product>
        </products>
        ...
    </configuration>

Whitespace characters are allowed in the license; the product ignores such characters at runtime.

Other settings

Hazelcast

AMPS sets confluence.cluster.hazelcast.listenPort to a random free port. To use a specific port, set that system property either in your global AMPS configuration or within the relevant <product> element.

Home directories

• The local home of node 0 is at target/confluence/home, as for single-node operation.
• The local homes of the other nodes are at target/confluence/home-n, where n is 1, etc.
• The shared home of the cluster is set as follows:
  • if the <product> contains a <sharedHome>, AMPS uses that, otherwise
  • AMPS uses target/confluence/home/shared-home as the shared home directory.

Node names

AMPS sets confluence.cluster.node.name to the AMPS instance ID plus the zero-based node index. For example, if a <product> has <instanceId>confOne</instanceId>, then the first node of the cluster will be named confOne-0. At runtime, the node names can be found in the product's Clustering page, located at <base_URL>/plugins/servlet/cluster-monitoring.

Synchrony

AMPS configures Synchrony (the collaborative editing engine) as follows:

Node 0

Node 0 (the first node) runs Confluence-managed Synchrony on a random free port. If desired, you can set this port as follows:

1
2
<nodes>
    <node>
        <systemProperties>
            <!-- 8091 is just an example -->
            <synchrony.port>8091</synchrony.port>
            ...

Nodes 1-n

All nodes other than node 0 connect to the Synchrony instance on node 0; AMPS configures them as follows:

• synchrony.proxy.enabled=false
• synchrony.service.url=http://localhost:nnnn/synchrony/v1, where nnnn is the Synchrony port for node 0.

Standalone Synchrony

AMPS provides no explicit support for running a standalone Synchrony cluster, although you should be able to configure this if you follow the usual process for setting up such a cluster on a production instance. This will involve configuring AMPS to set the relevant system properties for the instance and its nodes, as follows:

1
2
<configuration>
    <systemPropertyVariables>
        <!-- These are common to all instances of all products -->
        <myKey1>myValue1</myKey1>
    <systemPropertyVariables>
    <product>
        <!-- The instance-specific alternative to systemPropertyVariables -->
        <systemProperties>
            <myKey2>myValue2</myKey2>
        </systemProperties>
        <nodes>
            <node>
                <systemProperties>
                    <!-- These are node-specific for this product instance -->
                    <myKey3>myValue3</myKey3>
                    ...