Install Orchestrator

Instructions to install Orchestrator 4.1 and upgrade from 4.0.1.

Enable the CodeReady Builder (CRB) repositories

Important: You need to install MySQL 8. For detailed instructions on how to install MySQL 8, refer to MySQL's official documentation.

Attention: Installing or upgrading Orchestrator requires an active internet connection.

Use the appropriate command depending on your OS version:

Red Hat 10

subscription-manager repos --enable codeready-builder-for-rhel-10-$(arch)-rpms

Red Hat 9
For RHEL 9 there are two ways to enable the CRB repository:
1. Using subscription-manager:
```
subscription-manager repos --enable codeready-builder-for-rhel-9-$(arch)-rpms 
```
2. Using the dnf config-manager command:
```
dnf config-manager --set-enabled crb
```

Red Hat 8

subscription-manager repos --enable codeready-builder-for-rhel-8-$(arch)-rpms

Rocky 9 and 10
```
dnf config-manager --set-enabled crb
```

Install dependencies

For all platforms except RHEL 10 and Rocky 8 and 10:

yum install -y cronie gcc gcc-c++ git libffi-devel libxml2-devel libxslt-devel libyaml-devel make mysql-server mysql-devel nginx perl-IPC-Cmd polkit unixODBC unixODBC-devel

Rocky 8

Install all dependencies except libyaml-devel:

yum install -y cronie gcc gcc-c++ git libffi-devel libxml2-devel libxslt-devel make mysql-server mysql-devel nginx perl-IPC-Cmd polkit unixODBC unixODBC-devel

Install libyaml:

yum install -y https://dl.rockylinux.org/pub/rocky/8/Devel/x86_64/os/Packages/l/libyaml-devel-0.1.7-5.el8.x86_64.rpm

RHEL 10 and Rocky 10:
- Install the same dependencies used for RHEL 9 / Rocky 9, except for mysql-devel and mysql-server:
```
yum install -y cronie gcc gcc-c++ git libffi-devel libxml2-devel libxslt-devel libyaml-devel make nginx perl-IPC-Cmd polkit unixODBC unixODBC-devel
```
- Install the MySQL packages:
```
dnf install https://dev.mysql.com/get/mysql80-community-release-el9-1.noarch.rpm
dnf install mysql-community-server mysql-community-devel
```
  Note: If you encounter an error due to a failed GPG check, run the following command before the second one:
  rpm --import https://repo.mysql.com/RPM-GPG-KEY-mysql-2025

Install required packages

Install Ruby (via rbenv)

Clone the rbenv repository.

git clone https://github.com/rbenv/rbenv.git /opt/rbenv

Set RBENV_ROOT environment variable.

export RBENV_ROOT=/opt/rbenv
echo 'export RBENV_ROOT=/opt/rbenv' >> ~/.bashrc

Add rbenv to PATH.

echo 'export PATH="/opt/rbenv/bin:/opt/rbenv/shims:$PATH"' >> ~/.bashrc

Initialize rbenv on shell start.

echo 'eval "$(rbenv init -)"' >> ~/.bashrc
source ~/.bashrc

Clone the ruby-build plugin.

git clone https://github.com/rbenv/ruby-build.git /opt/rbenv/plugins/ruby-build

Install Ruby and set the global version.
```
rbenv install 3.4.1
rbenv global 3.4.1
```

Install Node.js

Set the NVM_DIR environment variable and create the directory.
```
export NVM_DIR=/opt/nvm
mkdir -p /opt/nvm
```

Install nvm.

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

Load nvm into the current shell session.
```
. ~/.bashrc
```
Install the latest LTS version of Node.js.
```
nvm install --lts
```

Set up the MySQL database (clean install only)

Note: For RHEL 10 and Rocky 10, when prompted for a password for the first time, use a temporary password (stored in /var/log/mysqld.log). You cannot enter using a blank password.

Start the MySQL service.
```
systemctl start mysqld
```
Connect to the MySQL shell as root (press Enter again when prompted for password).
```
mysql -uroot -hlocalhost -p
```

Set the root password and create remote access user.

ALTER USER 'root'@'localhost' IDENTIFIED BY '<YOUR_PASSWORD>';
CREATE USER IF NOT EXISTS 'root'@'%' IDENTIFIED BY '<YOUR_PASSWORD>';

Grant all privileges to root user for both localhost and remote access.

GRANT ALL ON *.* TO 'root'@'localhost';
GRANT ALL ON *.* TO 'root'@'%';

Flush privileges.
```
flush privileges;
```
Exit the MySQL shell.
```
exit
```
Enable MySQL to start on boot.
```
systemctl enable mysqld
```

Install Orchestrator

Use the appropriate command depending on whether you're performing a clean install or an upgrade:
- For clean install, run:
```
rpm -Uvh ibm-aspera-orchestrator-*.rpm
```
- If you're upgrading from Orchestrator 4.0.1, run:
```
rpm -Uvh ibm-aspera-orchestrator-*.rpm --replacefiles 
```
  Note: After running the upgrade command, the MySQL service may stop. Start the MySQL service before you continue with the installation:
```
systemctl start mysqld
```
Confirm that ruby and node can be run by the aspweb user:
- If the machine is only used to run Orchestrator:
```
chown -R aspweb:aspweb /opt/nvm
chown -R aspweb:aspweb /opt/rbenv
```
- If the machine is self-managed and has its own custom setup, you'll have to make sure that any group that owns those folders also gives access to the aspweb user.

Set up Orchestrator

Run the following command to set up Orchestrator:
```
orchestrator setup 
```
Fill out the following fields with the corresponding information:
- Enter the Orchestrator database host. Default: 127.0.0.1. Press Enter to accept the default, or enter a remote database host if applicable.
- Enter the Orchestrator database port. Default: 3306. Press Enter to accept the default, or enter a custom port if your database uses a different one.
- Enter the Orchestrator database username.
- Enter the Orchestrator database password and confirm it when prompted.
- Enter the Orchestrator database secret. Press Enter to auto-generate a new secret, or enter a specific secret string.
- Enter the Orchestrator webapp admin user's password. This password will be used to log in to the Orchestrator UI as the admin user.
- Enter the complete URL for this IBM Aspera Orchestrator instance. This should be the IP address or fully qualified domain name of the server.
- When prompted to confirm the settings, type y to proceed with setup or n to re-enter the values.
Start Orchestrator:
```
orchestrator start
```

Start nginx

Note: You should use your own SSL certificate for secure connections. The self-signed certificate should only be used as a fallback option.

Stop Apache to prepare for the Nginx setup (you only need to do this if you're upgrading to 4.1.0 and using Nginx). Run the following commands to stop Apache and ensure the ashttpd process is terminated:
```
asctl apache:stop
```
If the previous command fails to stop the process, run pkill -9 ashttpd instead.
Add nginx user to the aspweb group.
```
usermod -a -G aspweb nginx
```

Create the SSL configuration directory.

mkdir -p /opt/aspera/orchestrator/config/ssl

Navigate to the SSL configuration directory.
```
cd /opt/aspera/orchestrator/config/ssl
```

Generate a self-signed certificate.

openssl req -newkey rsa:2048 -sha256 -nodes -x509 -days 3652 -subj "/CN=$(hostname)" -keyout key.pem -out cert.pem

Generate Diffie-Hellman parameters.
```
openssl dhparam -out dhparam.pem 2048
```

Change ownership of the SSL directory to aspweb.

chown -R aspweb:aspweb /opt/aspera/orchestrator/config/ssl

To apply your required settings (for example, host), copy the sample configuration file before editing it. Confirm overwrite if prompted.
```
cp /opt/aspera/orchestrator/config/nginx/nginx.conf.sample /etc/nginx/nginx.conf
```
Enable the Nginx service to start on boot.
```
systemctl enable nginx
```
Start the Nginx service.
```
systemctl start nginx
```