Configure repository servers

3 minute readScalability

This section describes how to configure repository servers for high availability.

Overall Steps for Configuring Repository Servers

The overall steps for configure repository servers for high availability are as follows:

To set up repository servers for a typical cluster deployment, complete the following steps.

Duplicating Repository Contents to a New Repository Server

To duplicate the contents of an existing repository server to a new repository server:

  1. Stop both repository servers.

  2. Copy the entire contents of the repository backingstore directory from the existing repository server to the corresponding location on the new repository server.

    The default location for the backingstore directory ( DATA_DIR/repository-data ) is: UNIX— /opt/cloudbees/sda/repository-data Windows— C:\ProgramData\CloudBees\Software Delivery Automation\repository-data

  3. Restart both repository servers.

Configuring Each Existing Repository Server for Clustered Operation

Additional configuration is required for any repository server that existed before being converted to operate in a cluster or was not configured to point to a remote server location during installation. You must point each of these repository servers to the CloudBees CD/RO server’s load balancer machine instead of directly to a CloudBees CD/RO server. To do so, enter the following command on each repository server:

/opt/cloudbees/sda/bin/ecconfigure --repositoryTargetHostName load_balancer_FQDN

This avoids an AccessDenied error when an artifact is uploaded from the Automation Platform UI:

In the example above, is the IP address of one of the two load-balanced CloudBees CD/RO servers.

To point a repository server to the CloudBees CD/RO server’s load balancer machine:

  1. Locate the ecconfigure tool.

    • On Linux, it is usually at /opt/cloudbees/sda/bin/ecconfigure.

    • On Windows, it is usually at C:\Program Files\CloudBees\Software Delivery Automation\bin\ecconfigure.exe.

  2. Run the tool with the following option on the repository server.

    You might need to do this as root or with administrator privileges:

    ecconfigure --repositoryTargetHostName load_balancer_FQDN

    where load_balancer_FQDN is the fully-qualified domain name of your CloudBees CD/RO server’s load balancer machine.

Pointing Each Repository Server to the Repository Backingstore

In a non-clustered configuration, the repository server is configured to store artifact versions in a directory called the repository backingstore. By default, the backingstore is the DATA_DIR/repository-data directory in the repository installation. In a clustered configuration, you must point each repository server to a common backingstore location.


In C:\ProgramData\CloudBees\Software Delivery Automation\conf\repository\ on each repository server, set REPOSITORY_BACKING_STORE to a UNC path to a network share on the file server, and then restart that repository server.

For example, set:


You can also configure this by running the ecconfigure --repositoryStorageDirectory command on each repository server. For example, enter:

ecconfigure --repositoryStorageDirectory //


If the network file share is Linux, mount it to the DATA_DIR/repository-data on all repository servers. For example, you can mount the file share for DATA_DIR/repository-data in the /etc/fstab file on each Linux repository server.

This means that you do not need to run the ecconfigure –repositoryStorageDirectory command to change REPOSITORY_BACKING_STORE from its REPOSITORY_BACKING_STORE= repository-data default value.

Opening the 7800 and 8200 Firewall Inbound Ports on Each Repository Server

On each repository server, make sure that the firewall inbound ports for 7800 and 8200 are open. This allows the load balancer to balance these ports.

Load balancing the repository local agent port 7800 is optional. If you choose to do so, you can register just the repository local agent load balancer port 7800 in the DevOps Essentials  Platform Home Page  Cloud  Resources page on the CloudBees CD/RO server. Otherwise, you must register each repository local agent on the Resources page.

Registering the Repository to the CloudBees CD/RO Cluster

You must use the load balancer URL to register the repository to the CloudBees CD/RO cluster so that the CloudBees CD/RO server can find the repository server load balancer. To do so:

  1. Navigate to DevOps Essentials  Platform Home Page  Artifacts  Repositories on the CloudBees CD/RO server.

  2. Verify that URL for the specified Repository Name points to the load balancer machine.

Registering the Repository Local Agents to the CloudBees CD/RO Cluster

You must register the repository local agents to the CloudBees CD/RO cluster. You can do this by registering only the load balancer as the agent resource if you already load-balanced port 7800 of the repository local agents.

If you did not load balance port 7800, you must register each repository local agent in the DevOps Essentials  Platform Home Page  Cloud  Resources page on the CloudBees CD/RO server.

Re-Creating a Deleted DATA_DIR /tmp Directory on a CloudBees CD/RO Web Server

Each CloudBees CD/RO web server that is load balanced requires a DATA_DIR/tmp directory. When you upload artifacts using the Automation Platform UI, that web server uses this folder as an intermediate location to upload the artifacts to the repository. This means that if the following error appears on a web server during file upload from the UI, you must re-create this folder on that machine:

Upload file: Error in tempdir() using /app/cloudbees/sda/tmp/XXXXXXXXXX: Parent directory (/app/cloudbees/sda/tmp) does not exist