Last updated Sep 28, 2021

Configuring a Bitbucket cluster in AMPS

To configuring a Bitbucket cluster in AMPS, you must do the following:

  • Set up an external database.
  • Prepare the home directory.
  • Configure your POM.

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>
    ...
  • An alternative method to steps 2-6 above is to use the “migrate database” option available under the Database admin page. This avoids having to re-enter setup mode and start up Bitbucket multiple times.
  • JDBC drivers are not included in the Bitbucket distribution used by AMPS. You may have to add a <libArtifact> to your plugin as follows, to get either of the linked methods to work:
1
2
<product>
    <id>bitbucket</id>
    <instanceId>bitbucket</instanceId>
    <version>${bitbucket.version}</version>
    <dataVersion>${bitbucket.data.version}</dataVersion>
    <libArtifacts>
        <libArtifact>
            <!-- We put this at the product level, not just in the <dataSource>, so that AMPS
                  will add it to the product's lib directory. The BBS distro used by AMPS doesn't
                  ship with any JDBC drivers, unlike the one downloaded by customers. -->
            <groupId>org.postgresql</groupId>
            <artifactId>postgresql</artifactId>
            <version>42.2.18</version>
        </libArtifact>
    </libArtifacts>
</product>

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.

If you intend to commit a license to version control, it’s best to use a non-perpetual “timebombed” license. That is, one that expires a certain number of hours or days after the product starts up.

Other settings

Home directories

  • The local home of node 0 is at target/bitbucket/home, as for single-node operation.
  • The local homes of the other nodes are at target/bitbucket/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/bitbucket/home/shared as the shared home directory.

Hazelcast

AMPS sets hazelcast.port to a random free port on each node. To use a specific port, set that system property within the relevant <node> element(s):

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

SSH

AMPS sets plugin.ssh.port to a random free port on each node. To use a specific port, set that system property within the relevant <node> element(s):

1
2
<nodes>
    <node>
        <systemProperties>
            <!-- 8092 is just an example -->
            <plugin.ssh.port>8092</plugin.ssh.port>
            ...

Rate this page: