Backlog Enterprise Upgrade Guide

Introduction

This guide explains how to upgrade Backlog Enterprise V1 to Backlog Enterprise V2 using Docker.

Prerequisite

Update Backlog Enterprise V1

Update Backlog Enterprise V1 to the latest version before starting the upgrade.

System requirements for Backlog Enterprise V2

Backlog Enterprise V2 needs AWS CLI, Docker, and Docker Compose. Make sure that the server and associated software meet system requirements. Prepare another server if your Backlog Enterprise V1 server doesn’t meet the requirements.

Process

We’ll walk through an upgrade using Linux as an example.

Advance preparation

Prepare the following before starting.

Prepare the SSL certificate

Backlog uses HTTPS. If you configured SSL on your Backlog Enterprise V1, you can skip this step. If not, you’ll need your:

• SSL certificate
• Private key file

Install AWS CLI

Download the AWS CLI installer and install:

curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip"
unzip awscliv2.zip
sudo ./aws/install

Get more information about installing the AWS CLI.

Install Docker

Set up the yum repository and install Docker.

sudo yum install -y yum-utils
sudo yum-config-manager \
    --add-repo \
    https://download.docker.com/linux/centos/docker-ce.repo
sudo yum install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

Set Docker to start automatically.

sudo systemctl enable docker

Start up Docker.

sudo systemctl start docker

Install Docker Compose.

sudo curl -L https://github.com/docker/compose/releases/download/v2.18.1/docker-compose-linux-x86_64 -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose

For more information on installing Docker:

• For Linux
• For Amazon Linux 2

Prepare a database (MySQL)

Prepare a database (MySQL) to store the Backlog data. If you’re using the database from your Backlog Enterprise V1, you can skip this step. Infrastructure as a service (IaaS), such as Amazon RDS, is available, and MySQL can be installed on any server including the one where Backlog is installed.

Add the following settings to my.cnf:

For MySQL 8.0

[mysqld]
sql_mode="NO_ENGINE_SUBSTITUTION"
default_authentication_plugin=mysql_native_password

For MySQL 5.7

[mysqld]
max_allowed_packet = 16M
character-set-server=utf8mb4
sql_mode = "NO_ENGINE_SUBSTITUTION"

[mysql]
default-character-set=utf8mb4

[client]
default-character-set=utf8mb4

Prepare an SMTP server

Prepare an SMTP server to send emails from Backlog. If you’re using the SMTP server from your Backlog Enterprise V1, you can skip this step. SMTP servers installed by default on Red Hat Enterprise Linux and CentOS, such as Sendmail and Postfix, can send email without SMTP authentication.

Set up the operating environment

Create a database

Create a database name and user for Backlog. If you’re using the database from your Backlog Enterprise V1, you can skip this step.

We recommend:

Place the SSL certificate

Place the SSL certificate and prepared private key file to any directory on the Backlog server.

mkdir “any directory”
cp “the SSL certificate” “the any directory”/crt.pem
cp “the private key file” “the any directory”/key.pem

Copy data

If you’re using the server from your Backlog Enterprise V1, you can skip this step and start upgrading Backlog.

Working on the V1 server

Stop Backlog

Stop running Backlog Enterprise V1. Execute with root privileges.

systemctl stop backlog.target

Compress data

Compress the data directory with the archived file name as data.tar.gz. Execute with root privileges.

cd /opt/backlog/
tar cvfp data.tar.gz data

If the MySQL server runs on the Backlog Enterprise V1 server, dump a database.
For example, if the dump file name is backlog-dump.sql, the database name is backlog, and the database username is backlog:

mysqldump -ubacklog -p --opt backlog > backlog-dump.sql

Working on the V2 server

Transfer your archived and dump files to the V2 server with scp command etc.

Decompress data

Decompress the archived file. Execute with root privileges.

mkdir -p /opt/backlog
tar xvfp data.tar.gz -C /opt/backlog

If you dumped a database, restore it. For example, if the dump file name is backlog-dump.sql, the database name is backlog and the database username is backlog:

mysql -ubacklog -p backlog < backlog-dump.sql

Your data is now copied.

Upgrade Backlog

Follow the procedures below to upgrade to Backlog Enterprise V2.

1. Stop Backlog Enterprise V1
2. Back up data
3. Download the upgrade tools
4. Run the inspection tool
5. Run the upgrade tool

Stop Backlog Enterprise V1

Stop running Backlog Enterprise V1. Execute with root privileges.

systemctl stop backlog.target

Back up data

Back up your database before upgrading.

Download the upgrade tools

Set AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY as environment variables copied from the Enterprise Account page.

export AWS_ACCESS_KEY_ID="XXXX"
export AWS_SECRET_ACCESS_KEY="XXXX"

Log in to Docker.

aws ecr get-login-password --region ap-northeast-1 | docker login --username AWS --password-stdin 019623933850.dkr.ecr.ap-northeast-1.amazonaws.com

Download the upgrade tools under a directory where Backlog will be upgraded. Don’t specify /opt/backlog and lower directory paths.

For example, if the directory is backlog-enterprise:

mkdir backlog-enterprise
cd backlog-enterprise
docker run --rm -it -v $PWD:/work 019623933850.dkr.ecr.ap-northeast-1.amazonaws.com/enterprise-bootstrap:2.3.0 upgrade

Run the inspection tool

Run the inspection tool before the upgrade.

cd upgrade-assistant

Edit upgrade.env with root privileges.

./advance-check.sh

Red text will appear if Backlog Enterprise V2 isn’t able to display the data. This is due to changes in the data structure, causing the upgrade tool to truncate the database records. If you want to check the data, check the database directly.

For example:

10 database records will be truncated when the upgrade tool is run due to changes in the database table structure. Please see the red messages above for further details.

Run the upgrade tool

Upgrade Backlog.

docker pull 019623933850.dkr.ecr.ap-northeast-1.amazonaws.com/enterprise-database-migration:2.3.0
docker pull 019623933850.dkr.ecr.ap-northeast-1.amazonaws.com/enterprise-password-migration-tool:2.3.0
docker pull 019623933850.dkr.ecr.ap-northeast-1.amazonaws.com/enterprise-git-rpc:2.3.0
sudo ./upgrade.sh

Your upgrade is now complete.

Run the configuration tool

Run the configuration tool under a directory where Backlog will be upgraded.
For example, if the installation directory isbacklog-enterprise:

cd /path/to/backlog-enterprise # Edit `/path/to/backlog-enterprise` to your absolute directory path
docker run --rm -it -v $PWD:/work -v $PWD/data:/data 019623933850.dkr.ecr.ap-northeast-1.amazonaws.com/enterprise-bootstrap:2.3.0

The configuration is interactive. There are eight items to complete, and they should be done according to the environment in which Backlog will function.

Please enter the host name of your database server.
[e.g.] backlog-db.example.com, 192.168.0.11
> 10.254.249.1

If you set localhost or 127.0.0.1 to BACKLOG_DB_HOST in upgrade.env, 10.254.249.1 is displayed as the initial value. Don’t change the value because it is the host name used internally when Backlog accesses the database.

Please enter the name of Backlog's database.
Default value: backlog
> backlog

Please enter the user name for connecting to the database.
Default value: backlog
> backlog

Please enter the password for connecting to the database.
>

Enter the database information created earlier.

Please enter your SMTP host name for sending email. Environment variables are also available.
[e.g.] backlog-smtp.example.com, 192.168.0.12
> 

Enter the SMTP server information created earlier. If your SMTP server is running on the server where Backlog is installed, enter 10.254.249.1.

Please enter your time zone name.
[e.g.] Asia/Tokyo, America/New_York, Europe/London
> 

Ensure the time zone name matches the time zones of other middleware such as a database server and an SMTP server.

Please enter the directory containing the SSL certificate.
> 

Enter the “absolute” directory path created earlier.

Your upgrade to Backlog Enterprise V2 is now complete.

Start Backlog Enterprise V2

Start Backlog Enterprise V2 with the following command:

docker-compose up -d

Enable the function of global navigation keyword searches with the following command:

docker-compose up solr-tool

Uninstall Backlog Enterprise V1

After upgrading to Backlog Enterprise V2, uninstall V1. Disable Backlog Enterprise V1 with the following command. Execute with root privileges.

systemctl disable backlog.target

Uninstall RPM packages with the following command. Execute with root privileges.

rpm -aq | grep backlog | xargs rpm -e

Remove Backlog Enterprise V1 directory with the following command. Execute with root privileges.

rm -rf /opt/backlog

Remove the upgrade tool

After upgrading to Backlog Enterprise V2, remove the upgrade tool. Execute with root privileges.

cd /path/to/backlog-enterprise # Edit `/path/to/backlog-enterprise` to your absolute directory path
rm -rf upgrade-assistant

About the trademark

• MySQL and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners.
• Docker is a trademark or a registered trademark of Docker, Inc. in the United States and/or other countries.
• Amazon Web Services, AWS, and AWS CLI (Command Line Interface) are trademarks of Amazon.com, Inc. or its affiliates.
• Linux® is the registered trademark of Linus Torvalds in the U.S. and other countries.
• Other company and product names in this document may be trademarks or registered trademarks of their respective owners.