Skip to main content

1 System requirements

This document assumes that Backlog Enterprise is installed in an environment that meets System requirements in Backlog Installation Guide.

2 Operation with HTTPS

To operate Backlog with HTTPS, it is necessary to prepare SSL server certificate in advance. Follow the procedure of the issuing organization that you use. For the rest of this document, it's assumed that the HTTPS port is set to 443.

2.1 Activating HTTPS

Follow the procedure below to activate HTTPS.

  • Stop Backlog
  • Edit environment variables used by Backlog
  • Edit ssl.conf
  • Edit httpd.conf
  • Start Backlog
  • Change space URL

If you do not use the mobile version, omit the procedure on service backlog-mobile in the procedure of stopping and starting Backlog.

2.1.1 Stopping Backlog

Execute the following command to stop Backlog.

# systemctl stop backlog.target

2.1.2 Editing environment variables used by Backlog

Open the following file.

  • /opt/backlog/scripts/env

Please edit the port numbers of the following two items from HTTP port to HTTPS port.

Example)
Before change: BACKLOG_DOMAIN="xxxx:8080" * You can omit ':80' if your HTTP port is 80
After change: BACKLOG_DOMAIN="xxxx:8443" * You can omit ':443' if your HTTPS port is 443
Example)
Before change: BACKLOG_API_GIT_HTTPURLPATTERN="http://xxxx:8080/backlog/git/%s/%s.git" * You can omit ':80' if your HTTP port is 80
After change: BACKLOG_API_GIT_HTTPURLPATTERN="https://xxxx:8443/backlog/git/%s/%s.git" * You can omit ':443' if your HTTPS port is 443

Please edit the following from "http" to "https".

Example)
Before change: BACKLOG_SCHEME="http"
After change: BACKLOG_SCHEME="https"

2.1.3 Editing ssl.conf

Edit the following part in /opt/backlog/httpd/conf/ssl.conf to match your environment.

[1] Server name

### PLEASE CHANGE ###
ServerName www.example.com:443
#####################

[2] Certificate and server key location

### PLEASE CHANGE ###
SSLCertificateFile /etc/pki/tls/certs/localhost.crt
SSLCertificateKeyFile /etc/pki/tls/private/localhost.key
#####################

Depending on the certificate, you may also need to install an intermediate certificate. Please also check documents of the certificate issuer.

2.1.4 Editing httpd.conf

Execute the following command to add the setting to read ssl.conf.

# cp -a /opt/backlog/httpd/conf/httpd.conf /opt/backlog/httpd/conf/httpd.conf.bak
# echo 'Include conf/ssl.conf' >> /opt/backlog/httpd/conf/httpd.conf

2.1.5 Starting Backlog

Execute the following command to start Backlog.

# systemctl start backlog.target

2.1.6 Changing space URL

After logging into Backlog as an administrator, change the "Space URL" to that of HTTPS from the "management screen" → "edit space".



2.2 Redirecting to HTTPS

To limit Backlog access to HTTPS only, set up a redirect from HTTP to HTTPS by adding the following setting to /opt/backlog/httpd/conf/httpd.conf.

RewriteCond %{SERVER_PORT} !^443$
RewriteCond %{REMOTE_ADDR} !^127\.0\.0\.1$
RewriteCond %{HTTP_USER_AGENT} !^Backlog\ HttpClient
RewriteRule ^/(.*)$ https://%{HTTP_HOST}/$1 [R,L]

NOTE: Since Backlog uses HTTP access for internal API calls, do not stop HTTP usage itself with Apache settings. If you want to restrict HTTP access from outside the server, you can do so by setting the firewall.

3 Directory structure

Backlog Enterprise will be installed with the following directory structure.


/opt/backlog
|– api-server
|– bin
|– data
| |– image
| |– git
| |– lucene
| | `– index
| |– share
| | `– dav
| `– svn
|– git-server
|– httpd
|– httpd-mobile
|– licenses
|– licenses-mobile
|– perl
|– perl-mobile
|– perl-git
|– scripts
|– serf
|– subversion
`– tomcat

4 Log management

For logging management, use rotatelogs attached to Apache, or logrotate attached to OS. For details, please refer to the document provided in your usage environment.

4.1 Log file storage directory

The various middleware components comprising Backlog are stored in the following directory:

  • http log

    /opt/backlog/httpd/logs

  • tomcat log

    /opt/backlog/tomcat/logs

  • Mobile version of http log

    /opt/backlog/httpd-mobile/logs

  • Git server log

    /opt/backlog/git-server/logs

  • API v2 server log

    /opt/backlog/api-server/logs

4.2 Rotating Apache log

Below is an example of a config using rotatelogs in /opt/backlog/httpd/conf/httpd.conf with a key line commented out. To use this method, configure as per the following:


# Comment out the following
#ErrorLog logs/error_log
# Enable below
ErrorLog "|/opt/backlog/httpd/bin/rotatelogs -l /opt/backlog/httpd/logs/error_log.%Y-%m-%d 86400"

#LogLevel debug
LogLevel warn

LogFormat "%h %l %u %t "%r" %>s %b "%{Referer}i" "%{User-Agent}i" %p %m %D" combined
LogFormat "%h %l %{note-x-backlog-user}n %t "%r" %>s %b "%{Referer}i" "%{User-Agent}i" %p %m %D" backlog_user_combined
LogFormat "%h %l %u %t "%r" %>s %b" common

# Comment out the following
#CustomLog logs/access_log combined env=!log-x-backlog-user
#CustomLog logs/access_log backlog_user_combined env=log-x-backlog-user
# Enable below
CustomLog "|/opt/backlog/httpd/bin/rotatelogs -l /opt/backlog/httpd/logs/access_log.%Y-%m-%d 86400" combined env=!log-x-backlog-user
CustomLog "|/opt/backlog/httpd/bin/rotatelogs -l /opt/backlog/httpd/logs/access_log.%Y-%m-%d 86400" backlog_user_combined env=log-x-backlog-user

4.3 Rotating Tomcat log

Below is an example of a config using rotatelogs in /opt/backlog/tomcat/bin/catalina.sh with a key line commented out. To use this method, configure as per the following:

Before change:
>> "$CATALINA_OUT" 2>&1 "&"
#2>&1 | LD_LIBRARY_PATH="/opt/backlog/httpd/lib" /opt/backlog/httpd/bin/rotatelogs -l "$CATALINA_BASE"/logs/catalina.out.%Y-%m-%d 86400 &
After change:
 2>&1 | LD_LIBRARY_PATH="/opt/backlog/httpd/lib" /opt/backlog/httpd/bin/rotatelogs -l "$CATALINA_BASE"/logs/catalina.out.%Y-%m-%d 86400 &
#>> "$CATALINA_OUT" 2>&1 "&"

4.4 Rotating Git server log

Rotate using logrotate. Add the following files to /etc/logrotate.d/backlog-git.

/opt/backlog/git-server/logs/httpd.log
/opt/backlog/git-server/logs/rpc.log
/opt/backlog/git-server/logs/hook-worker-backlog.log
/opt/backlog/git-server/logs/hook-worker-webhook.log
/opt/backlog/git-server/logs/hook-worker-diskusage.log
/opt/backlog/git-server/logs/sshd.log
{
  sharedscripts
  postrotate
  systemctl restart backlog-git.target
  endscript
}
                          

4.5 Rotating API v2 log

Below is an example of a config using rotatelogs in /opt/backlog/scripts/backlog-api.sh with a key line commented out. To use this method, configure as per the following:

Before change:
>> ${LOGS_DIR}/play.log 2>&1 &
#2>&1 | LD_LIBRARY_PATH="/opt/backlog/httpd/lib" /opt/backlog/httpd/bin/rotatelogs -l ${LOGS_DIR}/play.log.%Y-%m-%d 86400 &
After change:
2>&1 | LD_LIBRARY_PATH="/opt/backlog/httpd/lib" /opt/backlog/httpd/bin/rotatelogs -l ${LOGS_DIR}/play.log.%Y-%m-%d 86400 &
#>> ${LOGS_DIR}/play.log 2>&1 &

5 Backup

5.1 Backup

We recommend regularly backing up the following two items:

  • Database dump
  • Data area directory under /opt/backlog/data

For database dumping various utilities are available: mysqldump and so on.

5.2 Data area

In addition to database data, data used by Backlog is stored in the following directories:

  • Image file area

    /opt/backlog/data/image

  • Index search file area

    /opt/backlog/data/lucene

  • File area managed by "file share" function

    /opt/backlog/data/share/dav/project name

  • Repository area of "Subversion" function

    /opt/backlog/data/svn/project name

  • Repository area of "Git" function

    /opt/backlog/data/git/project name

6 Stopping unwanted services

6.1 Git service

If you do not use Git-related functionality, you can stop the backlog-git service.

# systemctl stop backlog-git.target
# systemctl disable backlog-git.target \
    backlog-git-rpc.service \
    backlog-git-httpd.service \
    backlog-git-sshd.service \
    backlog-git-hook-diskusage-worker.service \
    backlog-git-hook-webhook-worker.service \
    backlog-git-hook-backlog-worker.service

6.2 API v2 service

If you do not use version two (v2) of the API, you can stop the backlog-api service.
For details on API v2, please see Nulab Developers.

# systemctl stop backlog-api.target
# systemctl disable backlog-api.target backlog-api.service

7 Resetting after installation

7.1 Starting setup tool

After installation, you can reset the following configuration values.

  • SMTP server
  • Database reset

Use the resetting tool enclosed in the Backlog package (backlog-app) to reconfigure Backlog application.

Execute the following command to start the setup tool.

# /opt/backlog/bin/config.sh

7.2 Changing notification sender email address

Backlog sends out notifications to update users of new changes. For example, if a user "closes" a Backlog Issue, Backlog will send out a notification email wherein the issue registrant's email address will be used as the email sender. In certain cases, the email address and the domain sending the email may differ - resulting in the email being mistakenly marked as spam.

You can prevent this by changing sender email address!

7.2.1 Stopping Backlog

Execute the following command to stop Backlog.

# systemctl stop backlog.target

7.2.2 Specifying sender email address as environment variable used by Backlog

Open the following file.

  • /opt/backlog/scripts/env

Please specify sender email address in the following.

Example)
BACKLOG_MAIL_NOTIFICATIONS_ADDRESS_FORMAT="notifications@backlog.com"

7.2.3 Starting Backlog

Execute the following command to start Backlog.

# systemctl start backlog.target

7.2.4 Setting options

You can make the sender email address unique to each sender by including the "sender ID" in the sender email address, as shown below.
[notifications@backlog.com] -> [notifications-21@backlog.com]
If the sender email address is fixed, Gmail will judge that it's from the same sender, and only one sender name will be displayed.
To display sender name on the thread, set sender address again in the following procedure.

Example)
BACKLOG_MAIL_NOTIFICATIONS_ADDRESS_FORMAT="notifications-%d@backlog.com"
Example of sender email address)
notifications-21@backlog.com

After the correction, please restart the Backlog service to apply the changes. It corresponds to steps 7.2.2 and 7.2.3 above. This will enable the name of each user who performed an action appear on Gmail inbox.

7.3 Using Active Directory with LDAP Signing

If you are using Backlog with Active Directory and want to support LDAP Signing, check out the following settings.
In order to use LDAPS (LDAP over SSL/TLS) between Backlog and Active Directory, you need to install a server certificate in Active Directory first.

7.3.1 Installing a server certificate in Active Directory

Please use one of the following ways to create a server certificate and install it in Active Directory.

7.3.2 Stopping Backlog

Execute the following command to stop Backlog.

# systemctl stop backlog.target

7.3.3 Setting environment variables used by Backlog

Open the following file.

  • /opt/backlog/scripts/env

Set BACKLOG_LDAPS_USING to "true" to use LDAPS protocol. If BACKLOG_LDAPS_USING is set to "false", LDAP protocol is used instead of LDAPS.

Example)
BACKLOG_LDAPS_USING="false" * To use LDAP protocol
BACKLOG_LDAPS_USING="true"  * To use LDAPS protocol

Specify the port number of LDAPS in BACKLOG_LDPAS_PORT. This setting will not be used if BACKLOG_LDAPS_USING is false.

Example)
BACKLOG_LDAPS_PORT="636"

If you are using Active Directory Certificate Services, when users who are authenticated with Active Directory access Subversion, Git, or shared files, they may encounter an error when trying to verify the server certificate. BACKLOG_LDPAS_VERIFY can be edited from "require" to "none" to ignore the verification.
This setting will not be used if BACKLOG_LDAPS_USING is false.

Example)
BACKLOG_LDAPS_VERIFY="none"

If you are using Active Directory Certificate Services, an error may occur when searching for users from Active Directory. Add the following option to BACKLOG_CATALINA_OPTS to avoid the error.
This setting will not be used if BACKLOG_LDAPS_USING is false.

BACKLOG_CATALINA_OPTS="... -Dcom.sun.jndi.ldap.object.disableEndpointIdentification=true"

7.3.4 Starting Backlog

Execute the following command to start Backlog.

# systemctl start backlog.target

8 Port number to use

The Backlog service is published using the port numbers below. If you are using iptables or similar, please allow access from the outside to the following port numbers:

HTTP port8969 (or the port number specified in the configuration settings )
Git SSH port8972

Other than the above, the following port numbers are internally used for Backlog.
5701, 8905, 8970, 8971, 8973, 8974, 8975

9 Automatic interactive mode

Installing, updating, and upgrading are performed in basic interactive mode, but it's also possible to run them in automatic interactive mode.

9.1 During installation

9.1.1 Copying setup file template for automatic interactive mode

Copy the setup file template for automatic interactive mode. You can name the copied file whatever you'd like.
In the following example, the name of the copied file is pro-init-interactive.properties.

cp /opt/backlog/bin/pro-init-interactive.properties.template pro-init-interactive.properties

9.1.2 Modifying setup value

Open the copied file and update the configuration values accordingly.
Items that require setting are described:
# [Required]
in the explanation column. Otherwise, it can be left unset, but default value will be used.
Please see the explanation column in the file for details.
The "#" at the beginning of a line indicates a comment line. Delete the first "#" to validate the setting.
Also, even if you write "#" in the middle of a line, it is not treated as a comment. If you want to invalidate the setting, write "#" at the beginning of the line.

9.1.3 Specifying saved file with -i to run installer

Specify -i during 4.6 Starting configuration tool in Installation Guide.

/opt/backlog/bin/init.sh -i pro-init-interactive.properties

9.2 During update

9.2.1 Copying setup file template for automatic interactive mode

Copy the setup file template for automatic interactive mode. You can name the copied file whatever you'd like.
In the following example, the name of the copied file is pro-update-interactive.properties.

cp /opt/backlog/bin/pro-update-interactive.properties.template pro-update-interactive.properties

9.2.2 Modifying setup value

Open the copied file in the same way as 9.1.2 Installation, and update the config values accordingly.

9.2.3 Specifying saved file with the -i flag to run updater

Specify the -i flag during 4.5 Starting up updater in Update Guide.

/opt/backlog/bin/update.sh -i pro-update-interactive.properties

10 Notes on using MySQL 5.7

10.1 Troubleshooting

MySQL 5.7 may cause issues in Backlog if the MySQL query cache is enabled. If query_cache_type has an existing value in my.cnf, set it to 0. If not, there’s no need to add it as the default value for query_cache_type in MySQL 5.7 is 0.

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

[mysql]
default-character-set=utf8mb4

[client]
default-character-set=utf8mb4
  • Linux is a registered trademark or trademark of Mr. Linus Torvalds in Japan and other countries.
  • Red Hat is a registered trademark or trademark of Red Hat, Inc. in the United States and other countries.
  • MySQL and Java are registered trademarks of Oracle Corporation and its subsidiaries and affiliates in the United States and other countries. Company names, product names, etc. in the text may be trademarks or registered trademarks of each company.
  • Other company names and product names mentioned are registered trademarks or trademarks of each company.

Author: Backlog Support <support@backlog.com>

Revision History

2024-02-29

  • Added a section called 10 Added Notes on using MySQL 5.7.

2023-08-30

  • Removed about PostgreSQL.

2021-07-09

  • Removed port number 18969 from ports used internally by Backlog in section 8 Port number to use.

2021-01-29

  • Removed descriptions about Red Hat Enterprise Linux (RHEL) 6 and CentOS 6 for end of support.
  • Added a section called 7.3 Using Active Directory with LDAP Signing.