Preparing for Installation

This section describes preliminary tasks to be performed before you can install Garoon. The tasks include preparing information necessary for installation and installing a Web server service.

Preparing Information Necessary for Installation

The following information is required for installing Garoon:

Item Description
Installer You can download the latest installer from the following Japanese page:
https://garoon.cybozu.co.jp/support/package/download/
Administrator password (for Windows) or root password (for Linux) The password of the user account that is used to manage Garoon. This password is required for initializing Garoon.
System administrator information The information of the system administrator of Garoon.
  • User name
  • Login name
  • password
Customer information The information of the customer who will use Garoon. The following information must be available:
  • Company name
  • Pronunciation of company name
    If you want to change the logo displayed on screens, prepare one of the following:
    • Image file
    • URL pointing to the image file's location
database administrator password The password of the user account (cbroot) that is used to manage MySQL. You must keep this password strictly confidential.
database user password The password of the user account that is used to connect to MySQL. You must keep this password strictly confidential.
installation identifier A string that identifies a Garoon installation. The following characters can be used:
  • Lowercase alphabetical characters (a-z)
  • Uppercase alphabetical characters (A-Z)
  • Underscores (_)
  • Numbers (0-9)
CGI directory A directory to be used for storing CGI programs and configuration files for Garoon.
The default directory is as follows:
  • For Windows: C:\Inetpub\scripts
  • For Linux: /var/www/cgi-bin
Document root directory A directory to be used for storing HTML files and image files for Garoon.
The default directory is as follows:
  • For Windows: C:\Inetpub\wwwroot
  • For Linux: /var/www/html

(For Both Operating Systems) Installing a Web Server Service

Install a Web server service on the serve machine, and configure the Web server to enable CGI programs.
If you plan to use an existing installation of a Web server service, additional configurations may be required for running Garoon, such as granting permissions and setting virtual directories.
You must refer to Installing and Setting up the Web Server/Web Browser to configure required settings, regardless of whether you plan to install a new Web server service or use an existing service.
After a Web server service is installed, ensure that the Web server service is running.

(For Both Operating Systems) Configuring Access Logs of a Web Server

In access logs of a Web server, you can find the number of accesses to Garoon per minute, the request content when an issue occurred, and the processing time of a request.
Output content and settings may vary depending on the type of your Web server, but make sure that the following information is recorded in access logs.

  • On
  • Source client IP
  • Method (GET, POST, etc)
  • Request URL
  • Query string
  • HTTP status
  • Number of bytes sent from the server to the client
  • Processing time
  • UserAgent
  • Referrer
When using Apache

By default, Apache may not be configured to write the processing time to the access log.
Follow the steps below to configure that the processing time is written to the access log.

Steps:
  1. Edit "httpd.conf" and describe "%D".

    • Example setting (before change):
    LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-Agent}i\"" combined
    
    • Example setting (after change):
    LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-Agent}i\" %D" combined
    

  2. To apply the setting, restart Apache or reload the setting file.

(For Both Operating Systems: Only When Using an Existing MySQL Installation) Changing MySQL Settings

MySQL is bundled in the Garoon installer. We recommend that you set up Garoon by installing MySQL bundled in the Garoon installer. However, you can use your existing MySQL installation.
The only supported version of MySQL is 8.0.28, which is bundled in the Garoon installer.
To use an existing MySQL installation, the following steps are required:

Editing the MySQL Configuration File (my.ini or my.cnf) Before You Install Garoon

Before you install Garoon, edit the my.ini file or my.cnf file to include the values described below.

Steps:
  1. Stop the MySQL service.

  2. Move to the directory where the configuration file exists.

    • Example of the directory in the Windows environment: C:\ProgramData\MySQL\MySQL Server 5.7\my.ini
    • Example of the directory in the Linux environment: /usr/my.cnf

  3. Open the configuration file in a text editor, enter the following values, and save the file.

    If the values have been already configured, comment them out and enter the following values.

    • For Windows (my.ini)
    [mysqld]
    sql_mode=NO_ENGINE_SUBSTITUTION
    • For Linux (my.cnf)
    [mysqld]
    sql_mode=NO_ENGINE_SUBSTITUTION
    character-set-server = utf8mb4
    collation-server = utf8mb4_general_ci
    skip-character-set-client-handshake
    [client]
    default-character-set=utf8mb4

  4. Start the MySQL service.

Entering the Connection Information of MySQL While Installing Garoon

While installing Garoon, select the "Use MySQL already installed on the server" option and enter the following information about the existing MySQL installation:

  • The directory where MySQL is installed
  • The port number of MySQL
  • The MySQL root password
Restarting the MySQL Service After Garoon Is Installed

After the installation of Garoon is completed, you must restart the MySQL service.

(Only for Windows) Configuring a Virtual Directory

A virtual directory maps a URL that users enter on the Web browser to a specific directory on the server. The CGI directory of the Web server must be configured as a virtual directory before you can install Garoon.
For information on how to create a virtual directory, refer to How to Create a Virtual Directory.

(Only for Windows) Disabling the QuickEdit Mode in Command Prompt

For Windows, disable the QuickEdit Mode in Command Prompt. If the QuickEdit mode is enabled, operations such as selecting text during the installation halt the upgrade process.
Right-click the title bar of Command Prompt, and select "Properties". Clear the "QuickEdit Mode" checkbox in the displayed properties screen, and click OK.

(Only for Linux) Disabling KeepAlive in Apache

The default configuration of Apache2.4 (bundled in Red Hat Enterprise Linux 8 and 9) has KeepAlive enabled. To disable KeepAlive, specify the statement "KeepAlive Off" in the configuration file.

Steps:
  1. Edit httpd.conf to disable KeepAlive.

    Before change:

    User apache  
    Group apache

    After change:

    User apache  
    Group apache  
    KeepAlive Off

  2. After you edit the configuration file, restart the Web server service on the server machine.

    [root@garoon admin]# systemctl restart httpd.service

(Only for Linux) Disabling Transparent Huge Pages (THP)

THP should be disabled. When THP is enabled, the performance of Garoon can be degraded.

Steps:
  1. Check that the THP function is disabled.

    [root@garoon admin]# cat /sys/kernel/mm/transparent_hugepage/enabled

    If "never" is surrounded by [ ], the THP function is disabled.
    Example:

    always madvise [never]

    If "[always] madvise never" or "always [madvise] never" is displayed, the THP function is enabled. Proceed to step 2.
    If the THP function is disabled, proceed to step 3.

  2. THP should be disabled.

    [root@garoon admin]# echo never > /sys/kernel/mm/transparent_hugepage/enabled

  3. Edit /etc/rc.d/rc.local to include the following statement so that THP can stay disabled after a restart:

    File to be changed: /etc/rc.d/rc.local
    Before change:

    touch /var/lock/subsys/local

    After change:

    touch /var/lock/subsys/local  
    echo never > /sys/kernel/mm/transparent_hugepage/enabled

  4. Set the Execute permission on /etc/rc.d/rc.local.

    # chmod u+x /etc/rc.d/rc.local

(Only for Linux) Disabling SELinux

For Linux, you must disable SELinux. Garoon does not work properly when SELinux is enabled.

Steps:
  1. Check that SELinux is enabled.

    Execute the following command:

    [root@garoon admin]# getenforce

    One of the following values is returned:

    • Enforcing: Indicates that SELinux is enabled.
    • Permissive: Indicates that SELinux is in debugging mode (where access control is not enforced but log entries are generated in the same way as when SELinux is enabled).
    • Disabled: Indicates that SELinux is disabled.

  2. Disable SELinux.

    When SELinux is enabled, open the SELinux configuration file (/etc/sysconfig/selinux) to change the value of "SELINUX".

    • Before change:
    SELINUX=enforcing
    • After change:
    SELINUX=disabled

  3. Restart the operating system.

(Only for Linux) Installing Libraries Required for Garoon

For Linux, ensure that the libraries required for running Garoon are installed.
For details on the libraries used by Garoon, refer to Necessary Libraries in the Linux Environment (Garoon 6 or later).