How to Install a Redmine® Web Application
Last modified: January 18, 2021
Overview
- Because cPanel, L.L.C. doesn’t develop or ship Redmine®, cPanel Technical Support can’t help you with it.
- We recommend that only experienced system administrators perform these steps.
- We are not responsible for any data loss.
This document explains how to install the Redmine® web application. Redmine is a project management web application that functions on the Ruby platform. You can register the Redmine application in cPanel’s Application Manager interface (cPanel >> Home >> Software >> Application Manager).
In this document, the instructions use the following examples:
user
represents the cPanel user.redmine-X.X.X.tar.gz
represents the most recentredmine
version.greenmine
represents the Redmine web application’s name.
If your system runs CentOS 6, change ruby27
to ruby24
in the provided commands. CentOS 6 does not support Ruby 2.7.
Getting started
Before you follow the steps outlined in this documentation, note the following:
The cPanel account must possess compiler access in WHM’s Compiler Access interface (WHM >> Home >> Security Center >> Compiler Access). If the account does not possess compiler access, the system will return an error similar to the following message:
make: execvp: gcc: Permission denied
We recommend that you perform the steps in this document via the command line as a cPanel user unless the step specifies otherwise. You can also perform these steps in cPanel’s Terminal interface (cPanel >> Home >> Advanced >> Terminal).
Pre-installation settings
Before you begin, ensure that you remove the operating system-provided Ruby installation. Then, install Ruby via the following RPMs:
ea-ruby27-mod_passenger
Note:If you enable this module, the system disables Apache’s
mod_userdir
module.ea-ruby27-ruby-devel
ImageMagick-devel
ea-apache24-mod_env
Note:This module allows you to add environment variables when you register your application. For more information about environment variables, read our Application Manager documentation.
To install these RPMs, use WHM’s EasyApache 4 interface (WHM >> Home >> Software >> EasyApache 4) or run the following command as the root
user:
yum install ea-ruby27-mod_passenger ea-ruby27-ruby-devel ImageMagick-devel ea-apache24-mod_env
Install the bundler Ruby gem
- Installing the bundler as a non-
root
user will cause the application to fail. If the/bin/bundler
directory exists in a user’s home directory, it was not installed by theroot
user. - Fork bomb protection can cause the bundler to fail. Disable fork bomb protection in WHM’s Shell Fork Bomb Protection interface (WHM >> Home >> Security Center >> Shell Fork Bomb Protection) if you receive an error that resembles the following:
Retrying fetcher due to error (2/4): ThreadError can't create Thread: Resource temporarily unavailable
To install the bundler
Ruby gem, run the following command as the root
user:
scl enable ea-ruby27 'gem install bundler --user-install'
Install the bundler without the SCL utility
If you do not want to use the Software Collection Library (SCL) utility, perform the following steps:
Log in to the server as the
root
user.Add the
source /opt/cpanel/ea-ruby27/enable
line to your shell’src
file (for example, the/home/user/.bashrc
file).Log out of your terminal session, then log back in again. You can also create a new terminal session.
Run the
gem install bundler --user-install
command.
Extract the Redmine archive file
The following steps require the wget
software package.
After you install the bundler
and rake
Ruby gems, download the application and extract the archive file. To do this, perform the following steps:
Access the Redmine website in a web browser.
Download the most recent
.tar.gz
file from the Stable Releases section. To do this, run the following command:
wget url http://www.redmine.org/releases/redmine-X.X.X.tar.gz
Extract the
.tar.gz
file’s contents. To do this, run the following command:tar xvzf redmine-X.X.X.tar.gz
After you extract the
.tar.gz
file, rename the file to your Ruby application’s name. To do this, run the following command:mv /home/user/redmine-X.X.X /home/user/greenmine
Create the database and database users
After you extract the Redmine archive file, create the application’s database and configure the database users.
- In the following steps, if database prefixing is enabled, you must prefix the database username with the account prefix and an underscore (
_
). For example,user_
for theuser
cPanel account. - You can also use cPanel’s MySQL Database Wizard interface (cPanel >> Home >> Databases >> MySQL Database Wizard) to create databases and database users.
To do this, perform the following steps:
Create production and development databases the UAPI
Mysql::create_database
. For example:/usr/local/cpanel/bin/uapi Mysql create_database name=user_greenmine
Create the database users via the UAPI
Mysql::create_user
function. For example:/usr/local/cpanel/bin/uapi Mysql create_user name=user_greenmine password=123456luggage
Assign the database user’s privileges via the UAPI
Mysql::set_privilges_on_database
function. For example:/usr/local/cpanel/bin/uapi Mysql set_privileges_on_database user=user_greenmine database=production_greenmine privileges=ALL
Copy the contents of the
/home/user/greenmine/config/database.yml.example
file to the/home/user/greenmine/config/database.yml
file.Open the
/config/database.yml
file with a text editor.Add the database names, usernames, and passwords information to the file. The file will resemble the following example:
Click to view...1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19
# Default setup is given for MySQL with ruby1.9. # Examples for PostgreSQL, SQLite3 and SQL Server can be found at the end. # Line indentation must be 2 spaces (no tabs). production: adapter: mysql2 database: user_production_greenmine host: localhost username: user password: "123456luggage" encoding: utf8 development: adapter: mysql2 database: user_development_greenmine host: localhost username: user password: "123456luggage" encoding: utf8
Install your Ruby Gems
To install the Ruby Gems that reside in the /home/user/greenmine/Gemfile
file, change to the /home/user/greenmine
directory and run the following command:
scl enable ea-ruby27 'bundle install'
Create a secret key
After you install your Ruby Gems, create a secret key, which the system uses to encode cookies. To generate this key, run the following command:
scl enable ea-ruby27 'rake secret'
This command returns a key hash that resembles the following example:
0d3f00336c10ac419f9ed08b4448dc1e652179b86eb1c434d3e4cf68b15aa92fbac1dc1f24a19b150b63a133fe4e89b8fb79ca5e78026bcbcf8ce183f5c9ca8c
After you create the secret key, create the /home/user/greenmine/config/secrets.yml
file. Then, add the following content, where secretkey
is the key hash that the scl enable ea-ruby27 'rake secret'
command returned:
|
|
Create the database structure
After you add the security key to the /home/user/greenmine/config/secrets.yml
file, create the database structure. To do this, change to the /home/user/greenmine
directory and run the following command:
RAILS_ENV=production scl enable ea-ruby27 'bundle exec rake db:migrate'
The output will resemble the following partial example:
|
|
Create the data configuration
After you create the database structure, create the database’s default configuration data set. To do this, perform the following steps:
Run the following command:
RAILS_ENV=production scl enable ea-ruby27 'bundle exec rake redmine:load_default_data'
When the system prompts you, select the database’s locale. To do this, enter your chosen locale’s two letter abbreviation in the command line.
Set the file system permissions
After you create the database’s data configuration, set the file system permissions. To do this, change to the /home/user/greenmine
directory and run the following commands:
mkdir -p tmp tmp/pdf public/plugin_assets
chmod -R 755 files log tmp public/plugin_assets
Register the application
After you set the file permissions, register your web application. To do this, use cPanel’s Application Manager interface (cPanel >> Home >> Software >> Application Manager) to register the web application.
You can also use UAPI’s PassengerApps::register_application
function. For example:
/usr/local/cpanel/bin/uapi PassengerApps register_application name="greemine" path="/home/user/greenmine" domain="myredminedomain.tld" deployment_mode="production" base_uri="/greenmine" enabled="1"
Restart Apache
This step is optional. UAPI’s register_application
function performs an Apache restart, but may not execute immediately.
After you register the Apache configuration, restart Apache as the root
user with the /usr/local/cpanel/scripts/restartsrv_httpd
command. After Apache restarts, you can access the Redmine web application in cPanel’s Application Manager interface (cPanel >> Home >> Software >> Application Manager).