ag@linux:~$

history 11 of 36

How to Install Redmine on CentOS 6 with Apache and Passenger

My notes from installing Redmine 1.4 on CentOS 6.3 with MySQL, Ruby gems, Passenger and an Apache virtual host, with corrected commands.

Written

From my Linux study notes, 2014. Some commands and versions here are old, so please reuse them carefully. Anything marked "added later", and the notes at the end, explain what has changed since.

These are my notes from installing Redmine (a web-based project management and issue tracking tool) on CentOS 6.3.

Before you start

(Added later.)

  • You need root access, or a user with sudo. Run the commands below as root or with sudo.
  • Use a test server first. These steps change the Apache configuration.
  • This guide is for an old setup: CentOS 6, Ruby 1.8 and Redmine 1.4.4. See “Notes for today” at the end before using it on a current system.

Install Redmine on CentOS 6.3

1. Install the required packages (as root)

Terminal window
yum install make gcc gcc-c++ zlib-devel ruby-devel rubygems ruby-libs apr-devel apr-util-devel httpd-devel mysql-devel mysql-server automake autoconf ImageMagick ImageMagick-devel curl-devel

This installs the compilers and development libraries needed to build Ruby gems, plus Apache development files (needed later for Passenger), the MySQL server, and ImageMagick.

2. Install Bundler

The original post said gem install bundle. The gem that provides the bundle command is called bundler, so the correct command is:

Terminal window
gem install bundler

3. Install Redmine

Terminal window
mkdir /var/www/redmine
wget http://rubyforge.org/frs/download.php/76255/redmine-1.4.4.tar.gz

(I am not sure if this method will work for newer versions.)

Added note: the original did not show unpacking the archive. Before the next step the Redmine files need to be extracted into /var/www/redmine, so that /var/www/redmine/config and /var/www/redmine/public exist. For example, from the directory where you downloaded the file:

Terminal window
tar -xzf redmine-1.4.4.tar.gz
cp -r redmine-1.4.4/* /var/www/redmine/

RubyForge has since shut down, so this download link no longer works. Get Redmine from the official site instead: https://www.redmine.org/

4. Install the Ruby dependencies

Terminal window
cd /var/www/redmine
bundle install --without postgresql sqlite test development

The original had - -without with a space; the option is --without (two hyphens, no space). It tells Bundler to skip the gem groups for PostgreSQL, SQLite, testing and development, because we are using MySQL in production.

5. Start MySQL

Terminal window
service mysqld start

6. Secure MySQL

Terminal window
mysql_secure_installation

This interactive script lets you set the MySQL root password, remove anonymous users, disallow remote root login and remove the test database.

7. Create the database and user for Redmine

Terminal window
mysql -p
create database redmine character set utf8;
grant all privileges on redmine.* to 'redmine'@'localhost' identified by 'my_password';
flush privileges;
quit

Replace my_password with a strong password of your own.

8. Configure the Redmine database connection

Terminal window
cd /var/www/redmine/config
cp database.yml.example database.yml

In database.yml, change the password for the production section to the password you set in step 7 (and check that the database name and username are redmine).

9. Create and populate the database with Rake

Terminal window
cd /var/www/redmine
rake generate_session_store
rake db:migrate RAILS_ENV="production"
rake redmine:load_default_data RAILS_ENV='production'

The original had RAILS_ENV-"production" (a hyphen); it must be RAILS_ENV="production" with an equals sign.

  • generate_session_store creates the secret used to sign session cookies (this is the Redmine 1.x task name).
  • db:migrate creates the tables.
  • redmine:load_default_data loads the default roles, trackers and statuses. It asks you to choose a language.

10. Configure iptables and SELinux according to your needs

At minimum, port 80 must be open in the firewall for Apache. See the safety note in “Notes for today” about SELinux.

11. Install Passenger

Terminal window
gem install passenger

12. Build the Passenger Apache module

Terminal window
passenger-install-apache2-module

At the end, this installer prints the exact LoadModule, PassengerRoot and PassengerRuby lines for your system. Use those lines in the next step, because the path depends on your Passenger and Ruby versions.

13. Apache configuration

Terminal window
cd /etc/httpd
mv conf.d available
mkdir conf.d
vi /etc/httpd/conf.d/redmine.conf

Added note: mv conf.d available moves every existing file in /etc/httpd/conf.d out of use (on CentOS 6 this includes files such as welcome.conf and, if installed, php.conf and ssl.conf). That is fine on a server used only for Redmine, but on a shared server it will disable other sites and modules.

Paste the following into redmine.conf:

# Loading Passenger
LoadModule passenger_module /usr/lib/ruby/gems/1.8/gems/passenger-3.0.13/ext/apache2/mod_passenger.so
PassengerRoot /usr/lib/ruby/gems/1.8/gems/passenger-3.0.13
# Please check your Passenger version and change it here
PassengerRuby /usr/bin/ruby


<VirtualHost *:80>
    ServerName www.yourname.com
    DocumentRoot /var/www/redmine/public
    <Directory /var/www/redmine/public>
        # This relaxes Apache security settings.
        AllowOverride all
        # MultiViews must be turned off.
        Options -MultiViews
        allow from all
    </Directory>
    ErrorLog "|/usr/sbin/rotatelogs /etc/httpd/logs/redmine-error.%Y-%m-%d.log 86400"
    CustomLog "|/usr/sbin/rotatelogs /etc/httpd/logs/redmine-access.%Y-%m-%d.log 86400" "%h %l %u %t %D \"%r\" %>s %b \"%{Referer}i\" \"%{User-Agent}i\""
</VirtualHost>

Changes from the original:

  • A space was missing between passenger_module and the path in the LoadModule line.
  • In the original, Options -MultiViews and allow from all were on the same line as the # MultiViews must be turned off. comment, so Apache would have ignored them. They are now on their own lines.
  • The quotes inside the CustomLog format string are now escaped (\"). Without this, Apache reads the first inner quote as the end of the string and reports a syntax error.
  • Replace www.yourname.com with your own domain name, and replace the three Passenger lines with the ones printed in step 12.

rotatelogs writes a new log file each day (86400 seconds), so the logs do not grow forever.

14. Edit the main Apache configuration

Terminal window
vi /etc/httpd/conf/httpd.conf
  • Uncomment (remove the # from) NameVirtualHost *:80. The original said *.80; it must be a colon.
  • Uncomment, or add, Include conf.d/redmine.conf.

Added note: the default CentOS 6 httpd.conf already contains Include conf.d/*.conf, which loads every .conf file in conf.d, including redmine.conf. If that line is present you do not need a separate include line.

15. Give Apache permission on the Redmine folder

Terminal window
chown -R apache:root /var/www/redmine
httpd -t

httpd -t checks the Apache configuration for syntax errors without restarting. If it prints Syntax OK, restart Apache to load the new configuration:

Terminal window
service httpd restart

Then open http://www.yourname.com/ (your domain) in a browser. On Redmine the default administrator login is admin with password admin; change it straight away.

That’s it, good luck.

Notes for today

  • CentOS 6 is end of life. It reached end of life on 30 November 2020 and gets no security updates. Rocky Linux and AlmaLinux are the common free replacements; Debian and Ubuntu are alternatives.

  • Redmine 1.4 is very old. Current Redmine releases need a modern Ruby and use different setup commands (for example, generate_session_store was replaced in later versions). Follow the official installation guide for the version you download: https://www.redmine.org/

  • Commands on newer systems:

    • service mysqld start became systemctl start mysqld (or mariadb on systems that ship MariaDB). Use systemctl enable to start it at boot.
    • yum became dnf on newer Red Hat-family systems (yum still works as an alias).
    • iptables service scripts became firewalld. To open HTTP: sudo firewall-cmd --permanent --add-service=http then sudo firewall-cmd --reload.

  • MySQL 8.0 no longer accepts IDENTIFIED BY inside GRANT. Create the user first, then grant:

    CREATE USER 'redmine'@'localhost' IDENTIFIED BY 'my_password';
    GRANT ALL PRIVILEGES ON redmine.* TO 'redmine'@'localhost';

    For MySQL 8.0 and newer, utf8mb4 is the recommended character set rather than utf8.

  • Apache 2.4 (CentOS 7 and later) replaced allow from all with Require all granted, and NameVirtualHost is no longer needed.

  • SELinux: step 10 leaves this open. Disabling SELinux is a common shortcut but removes a layer of protection. Keep it enforcing where you can and fix the specific denial (check /var/log/audit/audit.log) instead.

  • Permissions: chown -R apache:root gives the web server ownership of every Redmine file, including the configuration that holds the database password. It works, but a tighter setup only lets Apache write to the directories Redmine needs to write to (such as files, log and tmp).