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:
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:
Name | backlog |
User | backlog |
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.
- Stop Backlog Enterprise V1
- Back up data
- Download the upgrade tools
- Run the inspection tool
- 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.2.1 upgrade
Run the inspection tool
Run the inspection tool before the upgrade.
cd upgrade-assistant
Edit upgrade.env with root privileges.
Parameter name | Initial value | Description |
---|---|---|
BACKLOG_DB_HOST | 127.0.0.1 | Host of the database to connect |
BACKLOG_DB_PORT | 3306 | Port of the database to connect |
BACKLOG_DB_NAME | backlog | Schema name of the database to connect |
BACKLOG_DB_USER | backlog | Username of the database to connect |
BACKLOG_DB_PASSWORD | Password of the database to connect | |
ENTERPRISE_V1_DATA_DIR | /opt/backlog/data | Never change this parameter |
ENTERPRISE_V2_DIR | Absolute directory path to upgrade Backlog /path/to/backlog-enterprise |
./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.2.1
docker pull 019623933850.dkr.ecr.ap-northeast-1.amazonaws.com/enterprise-password-migration-tool:2.2.1
docker pull 019623933850.dkr.ecr.ap-northeast-1.amazonaws.com/enterprise-git-rpc:2.2.1
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.2.1
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.