Backlog Enterprise Operations Guide

Directory structure

Backlog is installed in the following configurations:

<Installation directory>
├── backlog-job-worker
│     └── hikaricp.properties #Maximum number of connections for database access
├── data #Store location of each data
├── logs #Store location of each log file
├── .env #File of each setting value.
└── docker-compose.yml #Definition file of each container

Command line of start/stop on Backlog

Stop

Stop running Backlog.

cd <Installation directory>
docker-compose down

Start

Start Backlog.

cd <Installation directory>
docker-compose up -d

Services

Port numbers

Services are published using the following port numbers. If you’re using iptables or other software, please allow external access to these numbers.

File data storage directory

Backlog file data is stored in the following directories:

data
├── attachment
│       └── pull_request
├── davsvn
│       ├── share
│       └── svn
├── elasticsearch
├── git
├── image
└── solr
        ├── issue
        ├── pull_request
        ├── shared_file
        └── wiki

Log file storage directory

Logs for each service are stored in <Installation directory>/logs.

logs
├── ${tag[1]} #Directory for temporary stores logs
│       └── ${tag[1]}
├── backlog-api
├── backlog-davsvn
├── backlog-davsvn-mntlog
│       ├── dav-job-worker
│       ├── httpd-davsvn
│       ├── svn-hook
│       └── svnserve
├── backlog-job-worker
├── backlog-solr
├── backlog-web
├── database-migration
├── elasticsearch
├── elasticsearch-init
├── git-http
├── git-rpc
├── git-rpc-mntlog
├── git-ssh
├── kanban-backend
├── kanban-notification
├── memcached
├── nginx
└── redis

Parameters for .env

Back-up data

The data handled by Backlog is stored in the following files, which should be backed up regularly.

• Database
• Saved file data directory
• Saved log file directory

Creating an advanced configuration file

Create docker-compose.override.yml on the same level asdocker-compose.yml. In docker-compose.override.yml, list the services you want to change and their configuration values. After it’s created, restart with the Start command.

For example:

services:
  backlog-web:
    environment:
    ...

  backlog-api:
    environment:
    ...

Get more information.

Integrating with Active Directory

Change the port number of LDAPS

For an LDAPS connection, enter the LDAPS port number in the advanced configuration file you created. After it’s created, restart with the Start command.

backlog-api:
  environment:
    - LDAPS_PORT=8636 # Default 636

backlog-web:
  environment:
    - LDAPS_PORT=8636 # Default 636

Use Active Directory Certificate Service

If you use an LDAPS connection and the Active Directory Certificate Service, place the certificate issued by Active Directory Certificate Service in any directory. After it’s placed, add the following information to the advanced configuration file you created, and restart with the Start command.

backlog-api:
  volumes:
    - /path/to/cert/dir:/mnt/certs #Please replace `/path/to/cert/dir` with the directory where you placed the certificate
  command: -Dcom.sun.jndi.ldap.object.disableEndpointIdentification=true

backlog-web:
  volumes:
    - /path/to/cert/dir:/mnt/certs #Please replace `/path/to/cert/dir` with the directory where you placed the certificate
  command: -Dcom.sun.jndi.ldap.object.disableEndpointIdentification=true

Create users with Active Directory

Create Backlog users with information from Active Directory. Set up zone definitions and SRV resource records for Active Directory before operation. Active Directory is supported on Windows Server 2012 R2, Windows Server 2016, and Windows Server 2019. Get detailed instructions.

Regenerate the search index

If the results of a keyword search are not displayed correctly, run the command to regenerate the search indexing. Note that playback is delayed if there’s a large amount of index data.

Problem with issue search (issue list)

Use the following:

docker-compose up elasticsearch-tool

Problem with global navigation keyword searches

Check if the following message is output in the backlog-solr log within the log storage directory:

java.lang.OutOfMemoryError: Java heap space

If the message appears in the log, there might be insufficient memory for Solr. Open the docker-compose.override.yml file and update the Solr memory settings.

backlog-solr:
  environment:
    - SOLR_JAVA_MEM=-Xms1024m -Xmx1024m # Default -Xms512m -Xmx512m

With the memory settings updated, restart using the same command you used to start.
After restarting, execute the following. The search index will be recreated.

docker-compose up solr-tool

If the message doesn’t appear in the log, use the following:

docker-compose up solr-tool

Change the speed of search index re-generation

Change the limits for indexing jobs in the advanced configuration file you created. After editing, restart with the Start command.

backlog-job-worker:
  environment:
    - BACKLOG_WORKER_JOB_INDEXING_ISSUE_JOB_PERMITS=16 # Default 6

Change the maximum of bucket size requests

If the wiki has too many characters and can’t be saved, for example, change the bucket size limit in the advanced configuration file you created. After editing, restart with the Start command.

backlog-api:
  environment:
    - MAX_MEMORY_BUFFER=25MB # Default 20MB
    - MAX_DISK_BUFFER=60MB # Default 55MB

backlog-web:
  environment:
    - MAX_MEMORY_BUFFER=25MB
    - MAX_DISK_BUFFER=60MB

Change the maximum number of simultaneous Nginx connections

Copy nginx.conf locally with the following command. After editing, restart with the Start command.

docker-compose cp nginx:/etc/nginx/nginx.conf .

Edit nginx.conf and docker-compose.override.yml.

nginx:
  volumes:
    - ./nginx.conf:/etc/nginx/nginx.conf

Get more information on configuring nginx.conf.

Notes on using MySQL 5.7

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=128M
character-set-server=utf8mb4
sql_mode = "NO_ENGINE_SUBSTITUTION"
query_cache_type = 0

[mysql]
default-character-set=utf8mb4

[client]
default-character-set=utf8mb4

Increase the file size limit for issue attachments

You can attach files up to 50MB to an issue. If you have any problems, try adjusting the following settings:

Increase the request packet size limit

Change the MAX_DISK_BUFFER in the advanced configuration file to 55MB or higher. Then, restart using the Start command.

backlog-api:
  environment:
    - MAX_DISK_BUFFER=55MB #default 55MB

backlog-web:
  environment:
    - MAX_DISK_BUFFER=55MB

Modify or add MySQL settings

In the my.cnf file, set the value of max_allowed_packet to 128M or higher. This is required for both MySQL 8.0 and MySQL 5.7. After editing, restart MySQL.

[mysqld]
max_allowed_packet=128M

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 are trademarks or registered trademarks of Docker, Inc. in the United States and/or other countries.
• Nginx are registered trademarks of Nginx Software Inc. in the United States and/or other countries.
• Active Directory is either a registered trademark or a trademark of Microsoft Corporation in the United States and/or other countries.
• Other company and product names in this document may be trademarks or registered trademarks of their respective owners.