Go to the top of this page is here Go to the body of 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.

  • For Red Hat Enterprise Linux 6 server or CentOS 6
    # service backlog-www stop
    # service backlog-app stop
    # service backlog-git stop
    # service backlog-api stop
  • For Red Hat Enterprise Linux 7 or CentOS 7
    # 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.

  • For Red Hat Enterprise Linux 6 server or CentOS 6
    # service backlog-app start
    # service backlog-www start
    # service backlog-git start
    # service backlog-api start
  • For Red Hat Enterprise Linux 7 or CentOS 7
    # 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.

  • For Red Hat Enterprise Linux 6 server or CentOS 6
    /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
        service backlog-git restart
      endscript
    }
  • For Red Hat Enterprise Linux 7 or CentOS 7
    /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

  • For Red Hat Enterprise Linux 6 server or CentOS 6

    Below is an example of a config using rotatelogs in /opt/backlog/scripts/backlog-api 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 &"
  • For Red Hat Enterprise Linux 7 or CentOS 7

    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 for MySQL, pg_dump for PostgreSQL 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.

  • For Red Hat Enterprise Linux 6 server or CentOS 6
    # service backlog-git stop
    # chkconfig backlog-git off
  • For Red Hat Enterprise Linux 7 or CentOS 7
    # 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.

  • For Red Hat Enterprise Linux 6 server or CentOS 6
    # service backlog-api stop
    # chkconfig backlog-api off
  • For Red Hat Enterprise Linux 7 or CentOS 7
    # 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 (database type cannot be changed)

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.

  • For Red Hat Enterprise Linux 6 server or CentOS 6
    # service backlog-www stop
    # service backlog-app stop
    # service backlog-git stop
    # service backlog-api stop
  • For Red Hat Enterprise Linux 7 or CentOS 7
    # 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.

  • For Red Hat Enterprise Linux 6 server or CentOS 6
    # service backlog-app start
    # service backlog-www start
    # service backlog-git start
    # service backlog-api start
  • For Red Hat Enterprise Linux 7 or CentOS 7
    # 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.

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 port 8969 (or the port number specified in the configuration settings )
Git SSH port 8972

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

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

9.3 During upgrade

9.3.1 Copying setup file template for automatic interactive mode

Please 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-upgrade-interactive.properties.

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

9.3.2 Modifying setup value

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

9.3.3 Specifying saved file with -i to run upgrader

Please specify -i during 4.4 Starting upgrade tool in Upgrade Guide.

/opt/backlog/bin/upgrade.sh -i pro-upgrade-interactive.properties
  • 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>

Date: 2020-02-05 15:00:00 JST