Install Pleasanter on Red Hat Enterprise Linux 9.7/10.1
# Pleasanter Installation Manual for Red Hat Enterprise Linux
## Overview
This manual provides the procedures for building a Pleasanter operating environment in the following environment:
| Target | Content |
| :--------- | :---------------------------------------------------------------------------------------------------- |
| OS | Red Hat Enterprise Linux 9.7/10.1 |
| DB | PostgreSQL 18 / MySQL 8.4 |
| Web Server | nginx 1.20.1 |
| Platform | .NET 10.0.100 |
| Pleasanter | When using PostgreSQL: Pleasanter 1.4.0.0 or later<br />When using MySQL: Pleasanter 1.4.9.0 or later |
## Notes
1. When installing version 1.4.6 or later, if CodeDefiner is executed without specifying arguments, it will be set up with Language: English and Time Zone: UTC. Please specify the language and time zone as needed.
2. When installing version 1.4.5 or earlier, the CodeDefiner command for initial installation has been changed. Please refer to the following page:
[About CodeDefiner Procedure Changes for Initial Installation in ver1.4.6 and Later](https://pleasanter.org/ja/manual/codedefiner-changed-steps)
3. MySQL can be used in version 1.4.9.0 or later. Pleasanter versions prior to 1.4.9.0 do not support MySQL.
4. When configuring a separated Web server and DB server setup with MySQL, please refer to "[Configure MySQL to be used in a configuration where the web server and DB server are separated (Ver.1.4.18.0 and later)](mysql-connecting-host-description)" or "[Configure the Web Server and DB Server to Use MySQL Separately](mysql-create-user-by-sql)".
## Prerequisites
1. This manual does not cover OS setup procedures. The OS is assumed to be already set up.
2. For details about the operating environment and specifications, please refer here:
[FAQ: I want to know the operating environment and recommended specifications for Pleasanter](faq-recommended-specifications)
3. Please decide in advance which user will start Pleasanter. The **<User to start Pleasanter>** mentioned in the procedures refers to this user.
4. This procedure explains the case where .NET is installed in /usr/local/bin. If you need to install .NET in a different directory for reasons such as requiring multiple versions of .NET in the same environment, please change the directory specified in ExecStart when executing CodeDefiner or creating the Pleasanter service script according to your installation location.
## Procedures
The setup procedures are as follows:
1. .NET Setup
2. Database Setup:
Perform the following setup for either PostgreSQL or MySQL.
*The order below may not match the actual implementation order.
1. DB Installation
2. DB Administrator Account Settings
3. DB Log Output Settings
4. DB Service Configuration and Auto-start Enablement
5. Settings for Allowing External Access to DB (if applicable)
3. Pleasanter Setup
1. Application Preparation
2. Database Configuration
3. CodeDefiner Execution
4. Pleasanter Startup Verification
5. Pleasanter Service Script Creation
6. Service Registration and Service Startup
4. Reverse Proxy (nginx) Setup
1. SELinux Configuration Changes
2. nginx Installation
3. Reverse Proxy Configuration
4. Allowing Access to Http (80)
5. Pleasanter Operation Verification
## 1. .NET Setup
Execute the following commands to install .NET:
```bash
sudo wget https://dot.net/v1/dotnet-install.sh -O dotnet-install.sh
sudo chmod +x ./dotnet-install.sh
sudo ./dotnet-install.sh -c 10.0 -i /usr/local/bin
dotnet --version
```
For details, please refer to **Scripted Install** on the official page below:
https://learn.microsoft.com/en-us/dotnet/core/install/linux-scripted-manual#scripted-install
Also, if errors occur regarding specific files when executing the dotnet command, please refer to the following page:
https://learn.microsoft.com/en-us/dotnet/core/install/linux-package-mixup?pivots=os-linux-redhat
## 2. Database Setup
Refer to either "PostgreSQL Setup" or "MySQL Setup" below to set up the database.
<details>
<summary style="font-weight:bold">1. PostgreSQL Setup</summary>
The PostgreSQL setup procedure is as follows:
#### 1. PostgreSQL Installation
Execute the following commands to install PostgreSQL:
```bash
sudo dnf install -y https://download.postgresql.org/pub/repos/yum/reporpms/EL-9-x86_64/pgdg-redhat-repo-latest.noarch.rpm
sudo dnf install -y postgresql18-server postgresql18-contrib
```
#### 2. PostgreSQL Database Initialization
Execute the following command to initialize the database. ※ -A: Specifies authentication method, -W: Option to display password input prompt
After execution, a password input prompt will be displayed. Please enter a password. Keep this password safe as it will be used in step 3.2.
```bash
sudo su - postgres -c '/usr/pgsql-18/bin/initdb -E UTF8 -A scram-sha-256 -W'
```
#### 3. PostgreSQL Log Output Settings
Open /var/lib/pgsql/18/data/postgresql.conf and edit the following settings:
```
log_destination = 'stderr'
logging_collector = on
log_line_prefix = '[%t]%u %d %p[%l]'
```
#### 4. PostgreSQL Service Restart and Service Configuration
Execute the following commands to restart the PostgreSQL service and enable automatic startup:
```bash
sudo systemctl restart postgresql-18
sudo systemctl enable postgresql-18
```
#### 5. Settings for Allowing External Access to DB
1. Uncomment the following two lines in /var/lib/pgsql/18/data/postgresql.conf and configure as shown below:
```
# - Connection Settings -
listen_addresses = '*' # what IP address(es) to listen on;
port = 5432 # (change requires restart)
```
2. Add the following line to /var/lib/pgsql/18/data/pg_hba.conf. In the Address field, specify the range of IP addresses from which access is allowed:
```
# TYPE DATABASE USER ADDRESS METHOD
host all all 192.168.1.0/24 scram-sha-256
```
3. After configuration, execute the following command to restart the PostgreSQL service:
```bash
sudo systemctl restart postgresql-18
```
</details>
<details>
<summary style="font-weight:bold">2. MySQL Setup</summary>
The MySQL setup procedure is as follows:
#### 1. MySQL Installation
1. Execute the following commands to install the MySQL package and server:
```bash
sudo dnf install -y https://dev.mysql.com/get/mysql84-community-release-el9-1.noarch.rpm
sudo dnf install mysql-community-server
```
The URL specified in the command is the same as the official repository URL:
https://dev.mysql.com/downloads/repo/yum/
2. Execute the command to display the service status:
```bash
systemctl status mysqld.service
```
3. Verify that the service is stopped by confirming the display of "Active: inactive (dead)" as shown below:
```
○ mysqld.service - MySQL Server
Loaded: loaded (/usr/lib/systemd/system/mysqld.service; enabled; preset: disabled)
Active: inactive (dead)
Docs: man:mysqld(8)
http://dev.mysql.com/doc/refman/en/using-systemd.html
```
#### 2. Enable MySQL Service Auto-start
1. Execute the following command to start the MySQL service:
```bash
sudo systemctl start mysqld
```
2. Execute the following command to enable MySQL service auto-start:
```bash
sudo systemctl enable mysqld
```
#### 3. MySQL User Configuration
1. Add the following setting under [mysqld] in /etc/my.cnf:
```
[mysqld]
skip-grant-tables
```
The configuration file path may differ depending on the OS or MySQL version.
2. Execute the following command to restart the MySQL service:
```bash
sudo systemctl restart mysqld
```
3. Execute the following command to log in to MySQL with the root account (without password specification):
```bash
mysql -u root
```
4. Execute the following SQL to set a password for MySQL's root account:
```sql
flush privileges;
alter user 'root'@'localhost' identified by '<New password for MySQL root account※>';
```
*By default, the MySQL installed in this procedure requires a password with 8 or more characters, including uppercase letters, lowercase letters, numbers, and special characters.
5. Execute the following command to log out from MySQL with the root account:
```sql
quit;
```
6. Delete the description added under [mysqld] in /etc/my.cnf. Do not delete [mysqld] itself:
```
skip-grant-tables
```
7. Execute the following command to restart the MySQL service:
```bash
sudo systemctl restart mysqld
```
8. Execute the following command to verify that you can log in to MySQL with the root account:
```bash
mysql -u root -p
```
9. Execute the following command to log out from MySQL with the root account:
```sql
quit;
```
#### 4. MySQL Log Output Settings
**Error log output is enabled by default in MySQL. If you do not change the default output destination, the following steps are not necessary.**
1. Check the log file path written in log-error under [mysqld] in /etc/my.cnf.
The configuration file path may differ depending on the OS or MySQL version.
```
[mysqld]
log-error=/var/log/mysqld.log
```
2. If you want to change the error log output destination, after editing the my.cnf file, execute the following command to restart the MySQL service:
```bash
sudo systemctl restart mysqld
```
#### 5. Settings for Allowing External Access to DB
Follow the procedures in the following manual to add MySQL users:
・[Configure MySQL to be used in a configuration where the web server and DB server are separated (Ver.1.4.18.0 and later)](mysql-connecting-host-description)
・[Configure the Web Server and DB Server to Use MySQL Separately](mysql-create-user-by-sql)
If you are not separating the Web server and DB server, this is not necessary.
</details>
## 3. Pleasanter Setup
### 1. Application Preparation
1. Execute the following command to create a "web" directory in the root directory ("/"):
```bash
sudo mkdir /web
```
2. Download the latest version of Pleasanter from the [Download Center](https://pleasanter.org/dlcenter).
If you want to install Pleasanter 1.4.23.3 or earlier, download the zip file for your desired version (e.g., Pleasanter_1.4.23.3.zip) from [GitHub](https://github.com/Implem/Implem.Pleasanter/releases).
3. Extract the downloaded zip file and place the extracted "pleasanter" folder in "/web" on the server using a file transfer application such as [WinSCP](https://winscp.net/).
4. Execute the following command to change the owner under the pleasanter directory to the predetermined user who will start Pleasanter:
```bash
sudo chown -R <User to start Pleasanter> /web/pleasanter
```
### 2. Database Configuration
Configure the database connection information in /web/pleasanter/Implem.Pleasanter/App_Data/Parameters/Rds.json. Configuration examples are shown below. Please also refer to the Rds.json manual as needed.
[Set Parameter: Rds.json](rds-json)
<details>
<summary style="font-weight:bold">Rds.json Configuration Example When Using PostgreSQL</summary>
| No | Property Name | Value |
| :-- | :-------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1 | Dbms | "PostgreSQL" |
| 2 | SaConnectionString | "Server=localhost;Port=5432;Database=postgres;UID=postgres;PWD=<font color="Red">XXX</font>"<br>※For the PWD value, enter the password set in "PostgreSQL Database Initialization". |
| 3 | OwnerConnectionString | "Server=localhost;Port=5432;Database=#ServiceName#;UID=#ServiceName#_Owner;PWD=<font color="Red">XXX</font>"<br>※For the PWD value, enter any password. |
| 4 | UserConnectionString | "Server=localhost;Port=5432;Database=#ServiceName#;UID=#ServiceName#_User;PWD=<font color="Red">XXX</font>"<br>※For the PWD value, enter any password. |
```json
{
"Dbms": "PostgreSQL",
"Provider": "Local",
"SaConnectionString": "Server=localhost;Port=5432;Database=postgres;UID=postgres;PWD=<Password set in 'PostgreSQL Database Initialization'>",
"OwnerConnectionString": "Server=localhost;Port=5432;Database=#ServiceName#;UID=#ServiceName#_Owner;PWD=SetAdminsPWD",
"UserConnectionString": "Server=localhost;Port=5432;Database=#ServiceName#;UID=#ServiceName#_User;PWD=SetUsersPWD",
"SqlCommandTimeOut": 0,
"MinimumTime": 3,
"DeadlockRetryCount": 4,
"DeadlockRetryInterval": 1000,
"DisableIndexChangeDetection": true,
"SysLogsSchemaVersion": 1,
"MySqlConnectingHost": "%"
}
```
</details>
<details>
<summary style="font-weight:bold">Rds.json Configuration Example When Using MySQL</summary>
| No | Property Name | Value |
| :-- | :-------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1 | Dbms | "MySQL" |
| 2 | SaConnectionString | "Server=localhost;Port=3306;Database=mysql;UID=root;PWD=<font color="Red">XXX</font>"<br>※For the PWD value, enter the password set in "MySQL User Configuration". |
| 3 | OwnerConnectionString | "Server=localhost;Port=3306;Database=#ServiceName#;UID=#ServiceName#_Owner;PWD=<font color="Red">XXX</font>"<br>※For the PWD value, enter any password. |
| 4 | UserConnectionString | "Server=localhost;Port=3306;Database=#ServiceName#;UID=#ServiceName#_User;PWD=<font color="Red">XXX</font>"<br>※For the PWD value, enter any password. |
| 5 | MySqlConnectingHost | If there are no special requirements, use "%". If you want to restrict access to MySQL, refer to "[Set Parameter: Rds.json](rds-json)" and configure accordingly. |
※By default, the MySQL installed in this procedure requires a password with 8 or more characters, including uppercase letters, lowercase letters, numbers, and special characters.
```json
{
"Dbms": "MySQL",
"Provider": "Local",
"SaConnectionString": "Server=localhost;Port=3306;Database=mysql;UID=root;PWD=<Password set in 'MySQL User Configuration'>",
"OwnerConnectionString": "Server=localhost;Port=3306;Database=#ServiceName#;UID=#ServiceName#_Owner;PWD=Set_0_Admins_0_PWD",
"UserConnectionString": "Server=localhost;Port=3306;Database=#ServiceName#;UID=#ServiceName#_User;PWD=Set_0_Users_0_PWD",
"SqlCommandTimeOut": 0,
"MinimumTime": 3,
"DeadlockRetryCount": 4,
"DeadlockRetryInterval": 1000,
"DisableIndexChangeDetection": true,
"SysLogsSchemaVersion": 1,
"MySqlConnectingHost": "%"
}
```
</details>
### 3. CodeDefiner Execution
Execute the following command to run CodeDefiner as the predetermined user who will start Pleasanter.
This procedure explains the case where .NET is installed in /usr/local/bin. If you need to install .NET in a different directory for reasons such as requiring multiple versions of .NET in the same environment, please change the directory specified when executing CodeDefiner according to your installation location.
※Execute the following command only during initial installation.
```bash
cd /web/pleasanter/Implem.CodeDefiner
sudo -u <User to start Pleasanter> /usr/local/bin/dotnet Implem.CodeDefiner.dll _rds /l "<Language>" /z "<Time Zone>"
```
| Argument | Example Setting | Description |
| :------- | :-------------- | :------------------------------------------------------ |
| /l | ja | Rewrites the DefaultLanguage value in Service.json (※1) |
| /z | Asia/Tokyo | Rewrites the TimeZoneDefault value in Service.json (※1) |
(*1) For language and time zone, please refer to the following manual page:
[FAQ: I want to know the parameter settings for languages and time zones supported by Pleasanter](https://pleasanter.org/manual/faq-supported-language)
For use in a Japanese environment, use the following command:
```bash
cd /web/pleasanter/Implem.CodeDefiner
sudo -u <User to start Pleasanter> /usr/local/bin/dotnet Implem.CodeDefiner.dll _rds /l "ja" /z "Asia/Tokyo"
```
When prompted with "Type "y" (yes) if the license is correct, otherwise type "n" (no).", enter **y**.
### 4. Pleasanter Startup Verification
1. Execute the following command to start Pleasanter as the predetermined user:
```bash
cd /web/pleasanter/Implem.Pleasanter
sudo -u <User to start Pleasanter> /usr/local/bin/dotnet Implem.Pleasanter.dll
```
2. While running, execute the following command in a separate terminal to verify that Pleasanter is running. Press "Ctrl+C" to exit.
* Command to execute:
```bash
curl -v http://localhost:5000/
```
* Execution result:
```
* Trying ::1:5000...
* Connected to localhost (::1) port 5000 (#0)
> GET / HTTP/1.1
> Host: localhost:5000
> User-Agent: curl/7.76.1
> Accept: */*
>
* Mark bundle as not supporting multiuse
< HTTP/1.1 302 Found
< Content-Length: 0
< Date: Tue, 25 Jul 2023 02:42:19 GMT
< Server: Kestrel
< Location: http://localhost:5000/users/login?ReturnUrl=%2F
< X-Frame-Options: SAMEORIGIN
< X-XSS-Protection: 1; mode=block
< X-Content-Type-Options: nosniff
<
* Connection #0 to host localhost left intact
```
### 5. Pleasanter Service Script Creation
Create /etc/systemd/system/pleasanter.service with the following content. For **User**, specify the predetermined user who will start Pleasanter.
This procedure explains the case where .NET is installed in /usr/local/bin. If you need to install .NET in a different directory for reasons such as requiring multiple versions of .NET in the same environment, please change the directory specified in ExecStart according to your installation location.
```
[Unit]
Description = Pleasanter
Documentation =
Wants=network.target
After=network.target
[Service]
ExecStart = /usr/local/bin/dotnet Implem.Pleasanter.dll
WorkingDirectory = /web/pleasanter/Implem.Pleasanter
Restart = always
RestartSec = 10
KillSignal=SIGINT
SyslogIdentifier=dotnet-pleasanter
User = <User to start Pleasanter>
Group = root
Environment=ASPNETCORE_ENVIRONMENT=Production
Environment=DOTNET_PRINT_TELEMETRY_MESSAGE=false
[Install]
WantedBy = multi-user.target
```
### 6. Service Registration and Service Startup
Execute the following commands to start the Pleasanter service and enable automatic startup:
```bash
sudo systemctl daemon-reload
sudo systemctl enable pleasanter
sudo systemctl start pleasanter
```
## 4. Reverse Proxy (nginx) Setup
Configure the reverse proxy to allow access via Port 80 like a normal web server.
### 1. SELinux Configuration Changes
Execute the following command:
```bash
getenforce
```
#### a. If "Command 'getenforce' not found.", "Permissive", or "Disabled" is displayed
Proceed to "2. nginx Installation".
#### b. If "Enforcing" is displayed
Execute the following command:
```bash
sudo setsebool -P httpd_can_network_connect on
```
※By changing the above boolean value in SELinux, all network connections via scripts and modules will be allowed on that server.
### 2. nginx Installation
Execute the following commands to install nginx:
```bash
sudo dnf install -y nginx
sudo systemctl enable nginx
```
### 3. Reverse Proxy Configuration
1. Create /etc/nginx/conf.d/pleasanter.conf with the following content. In the server_name line, specify the hostname or IP address of the server that will actually be accessed:
```
server {
listen 80;
server_name 192.168.1.100;
client_max_body_size 100M;
location / {
proxy_pass http://localhost:5000;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection keep-alive;
proxy_set_header Host $host;
proxy_cache_bypass $http_upgrade;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}
```
2. After creating the file, execute the following command to restart the service:
```bash
sudo systemctl restart nginx
```
### 4. Allowing Access to Http (80)
Execute the following commands to configure access permission settings for Http (port: 80) to allow clients to access the Web service:
```bash
sudo firewall-cmd --permanent --add-port=80/tcp
sudo firewall-cmd --reload
```
## 5. Pleasanter Operation Verification
1. After starting Pleasanter, on the Pleasanter login screen, enter "Login ID: Administrator" and "Initial Password: pleasanter", then click the "Login" button.
2. After logging in, you will be prompted to change the password for the "Administrator" user. Enter any password and click the "Change" button.
### If Not Redirecting Correctly
Please verify that the nginx configuration is correct. Subtle differences such as the presence or absence of "/" in the description can change the behavior.
### If the Pleasanter Screen Does Not Open
If you completed all the above steps without any errors but when accessing via browser you see a page like "Welcome to nginx!" (not an error display), there is a possibility that the browser's security settings are preventing transition to the Pleasanter login screen.
Please check your browser's security settings.
## Supported Versions
| Supported Version | Content |
| :---------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1.4.9.0 or later | MySQL support added |
| 1.4.10.0 or later | Resolved issue where Owner and User connections may be rejected by MySQL access control features<br>※Also added link to "[Configure the Web Server and DB Server to Use MySQL Separately](mysql-create-user-by-sql)" in notes |
| 1.4.18.0 or later | Added functionality to specify hosts other than localhost (same server as DB) as the connection source host to MySQL DB |
| 1.5.0.0 or later | .NET 10 and PostgreSQL 18 support added |
## Related Information
[FAQ: I want to install Pleasanter 1.3.43.0 or earlier in a Linux environment with PostgreSQL version 14 or earlier.](faq-postgresql-14-intall-pleasanter-for-linux)
