Redmine Cookbook

Make sure that you have sudo or root access to the server. If you don't have them, you may want to jump to Installing from a source on Ubuntu recipe, which explains how to install and run Redmine from the user's home directory.

After updating your system, go ahead and try a simple install:

sudo apt-get install redmine-mysql redmine

After running this command on a blank Linux server box, you may get a large number of dependencies to install. Just click <Yes> or press ENTER.

This process is going to take some time depending on your server and network capacity. The next screen that you get asks you to configure Redmine automatically; choose <Yes>.

If prompted for database configuration, choose MySQL. On the next several screens, provide the administration password that you wrote down and the database name for your Redmine installation; then, your username and password follows, which are used by Redmine.

After providing these credentials (which you should write down somewhere safe) and waiting for the apt-get script to finish, you 'll find your Redmine installed in the following folder:

/usr/share/redmine

To find out which version you installed, run the following:

more /usr/share/redmine/lib/redmine/version.rb

You will get something like this:

Your exact version is either Major, Minor, or Tiny, and in this case, it is Redmine 2.4.2 (shipped with Ubuntu 14.04.3). You will notice that the same version is used for Ubuntu versions. This rule applies for most open-software projects nowadays.

Apt-get installations are supposed to help administrators save time on common administration tasks. Aptitude is a Linux package manager that comes shipped with Ubuntu and Ubuntu-like systems; it downloads precompiled binaries and runs configuration scripts. In this case, first we update and upgrade our Ubuntu system, then we install MySQL and Redmine. Aptitude automatically installs the required dependencies and configures the system for us.

If you want to install a newer version of Redmine than the default one that is provided in the official Ubuntu channels or you want to update an existing one, you will want to add the following repository to your system. To add it, run the following:

sudo add-apt-repository ppa:ondrej/redmine
sudo apt-get update && sudo apt-get upgrade

You must run this step first. However, the ondrej/redmine repository does not always keep track of the latest Redmine releases. If you want to have the latest release and easily update it, read the next recipe.

For more information on WEBrick server take a look at its documentation at http://ruby-doc.org/stdlib-2.0.0/libdoc/webrick/rdoc/WEBrick.html.

When downloading and installing a custom version of Redmine, make sure that you have the required prerequisites installed on your Ubuntu server. At the time of writing this recipe, the current version of Redmine is 3.2.0. You will find the list of supported prerequisites on the Redmine homepage:

http://www.redmine.org/projects/redmine/wiki/RedmineInstall

If you are using Ubuntu 14.04.03, then you are ready to go with Redmine 3.2.x; if you install Ruby and Rails, use the following command:

sudo apt-get install ruby ruby-railties-4.0 ruby-dev build-essential zlib1g-dev libmysqlclient-dev

Use the following command to check your Ruby and Rails version type:

ruby –v
ruby 1.9.3p484 (2013-11-22 revision 43786) [x86_64-linux]
rails –v
Rails 4.0.2

On the console output, you can read your versions and compare them to the supported ones listed on the Redmine website. Currently, we can confirm that we are ready to go with Redmine 3.2.0, as follows:

First, let's confirm that we are not using the system as a root user by opening the console and typing the following: whoami

The output should be some other username than root.

This method assumes that Redmine will be installed in the user's /home/username/redmine directory. It can be used on shared hosting accounts if the Redmine prerequisites are already installed. At first, we made sure that the prerequisites were installed, then we grabbed the Redmine source either by downloading and extracting it manually or by SVN checkout. Then, we updated Ruby gems and installed bundler. Gem is a package manager for Ruby, and it is used to download and install the required Ruby libraries from the Internet. Bundler makes sure that all the gems required by an application are downloaded and installed. Then, we configured credentials for database access (in this case MySQL) and proceeded with bundling Redmine. The bundle command in Step 5 fetches gems that are specified in Gemfile, omitting the gems that are required for development, test, postgresql, sqlite, and rmagick. Then, we called bundle exec rake generate_secret_token, which generated the hashing code that was required for cookie authentication. After this, we created database tables, and we populated them with the default data that is language/locale -dependent. The last step was to create the necessary folders and set permissions. At the end, we tested the Redmine installation with WEBrick.

This recipe taught you how to install Redmine in the home directory for a user using system-wide Ruby. Take a look at the final recipe Using custom Ruby for Redmine if you need custom Ruby and can't tamper with the system at all (usually on shared hosting). Also, you now need a server in front of your Redmine installation. Later recipes will teach you how to use Apache, Nginx, or Puma as web-servers.

You can find alternative methods that are customized for different operating systems on the Redmine website:

http://www.redmine.org/projects/redmine/wiki/HowTos

Make sure that the Windows server is properly installed with all the default libraries and required drivers. This recipe is based on Microsoft SQL server, and it assumes that you already have it installed. If you need to install it, make sure that you add the proper roles to the server first and include .NET 3.5 (required for SQL server 2014). Any type of MSSQL can be used (Express, Standard, Enterprise, and so on). Prepare a database named Redmine, and create a user for it. Prior to your Redmine installation, make sure that you have enabled SQL Server's TCP IP connectivity options by following the instructions that are provided here:

http://dba.stackexchange.com/questions/62165/i-cant-connect-to-my-servers-sql-database-via-an-ip-address

This will ensure that you have prepared your SQL server successfully.

After a successful installation, in your Start menu, a new shortcut named Start Command Prompt with Ruby should be visible. Once clicked, you can type ruby –v and confirm that Ruby is successfully installed.

Next, we need to install the DevKit 4.7.2 minigw 64-bit version by performing the following steps:

If everything is okay, you should get a screen that looks like this:

After this, Redmine should be accessible via http://localhost:3000.

For a Windows installation to work, we need a proper Ruby version and a Microsoft SQL server. It is not obligatory to use the Microsoft SQL Server, but this recipe uses it just from the perspective of trying to stick with Microsoft technologies. First, we set up a blank database and user for Redmine on the MSSQL server, and we make sure that it is working and able to connect via TCP/IP correctly. After this, we download and install a precompiled binary Ruby and DevKit that fits our chosen Ruby version. Then, we update Ruby gems and install bundler. After downloading and configuring database parameters for Redmine, we proceed by bundling Redmine, generating a session store token, and populating the database. After this, our installation is done, and we can test it with WEBrick.

Now that you have Redmine successfully installed, running it requires a different recipe. To run Redmine on Windows, there are a few options that you can use, such as Apache + Fcgi, Nginx, or Puma.

The next recipe Using Puma and IIS on Windows is a very nice and flexible way to run Redmine.

First, install Redmine as explained in the previous recipe.

Then, we need the OpenSSL Developer Package (this contains header files and binaries), which can be downloaded from http://packages.openknapsack.org/openssl/openssl-1.0.0k-x64-windows.tar.lzma. Considering that we followed the previous recipe precisely, if you need a different SSL version, you can obtain it from https://www.openssl.org. Now, perform the following steps:

Once you have installed Redmine and its prerequisites, as explained in this recipe, proceed by installing the Puma server by typing the following:

gem install puma -- --with-opt-dir=c:\ruby\openssl

Testing Puma

This recipe assumes that your Redmine is installed, as explained in the, Installation on Windows servers recipe.

Run the following command from Redmine's directory in the command prompt:

puma -e production -p 3000

You should get a screen that looks like the following:

Navigating to http://127.0.0.1:3000 on your browser should open Redmine screen.

At first, we needed some prerequisites to install Puma because the gem to install Puma compiles it on your machine, and it requires proper OpenSSL library headers and binaries to compile. This is the reason why OpenSSL and dev tools are required. Then, the Puma installation is tested just by typing puma -e production -p 3000. To ensure that Puma starts after the Windows server restarts, Task Scheduler is used, and it schedules Puma to start on boot through a BAT file. In a bat file, command –t 8,32 tells Puma to start with a minimum of 8, and a maximum of 32 threads. You can adjust these values to fit your configuration. After this, we installed two Microsoft original modules to the IIS server and added a reverse proxy rule to forward all requests to 127.0.0.1:3000 where the Puma server is listening. We used the default IIS site, but this rule works with any or multiple IIS sites.

This recipe can be easily adopted to use Puma behind Nginx or Apache on both Windows and Linux systems. Also Thin or Unicorn can be used instead of Puma.

Check out the Puma website for updates, additional configurations and fine-tuning:

http://puma.io/

Once the prerequisites are installed, and Redmine is confirmed as working with WEBrick, then navigate to /home/youruser/redmine/public and type the following commands:

cd /home/youruser/redmine/public
mv dispatch.fcgi.example dispatch.fcgi
chmod 755 dispatch.fcgi
mv htaccess.fcgi.example .htaccess

Create a new virtual host for Apache, or edit the default host. We will create a new host called redmine.yoursite.com:

sudo nano /etc/apache2/sites-available/redmine.yoursite.com

Enter the following contents:

<VirtualHost *:80>
        ServerName redmine.yoursite.com
        DocumentRoot /home/youruser/redmine/public
        <Directory /home/youruser/redmine/public >
                Options Indexes ExecCGI FollowSymLinks
                Order allow,deny
                Allow from all
                AllowOverride all
        </Directory>
        ErrorLog /var/log/apache2/yoursite_error.log
        CustomLog /var/log/apache2/yoursite_access.log combined
</VirtualHost>

Enable your new website and restart Apache:

sudo a2ensite redmine.yoursite.com
sudo service apache2 restart

After restarting, your Redmine should be ready and accessible through http://redmine.yoursite.com provided DNS is set properly or at least hosts file for testing purposes.

At first, we installed mod_fcgid for Apache, then we prepared dispatch.fcgi; .htaccess, dispatch.fcgi is used by mod_fcgid through Apache and Ruby to run Redmine. htaccess tells Apache what to do with dispatch.fcgid. After this, we created a new virtual server for Apache. This may be done through an Apache management tool, such as Webmin for example, but then the value needs to be entered through an entry form or edited like we did from the command line in this recipe. After creating a virtual server, we enabled it and tested Redmine.

If you get an error such as, Rails application failed to start properly, try some of the troubleshooting recipes from Chapter 9, Troubleshooting (the Troubleshooting Apache installations section.)

The official mod_fcgid website is http://httpd.apache.org/mod_fcgid/.

More on Apache administration can be found at https://httpd.apache.org/docs/2.2/vhosts/name-based.html.

Make sure that you have Apache and passenger installed:

sudo apt-get install apache2 libapache2-mod-passenger

To configure Passenger, perform the following steps:

After restarting Apache, your Redmine installation should be ready to access by going to http://your_server/redmine.

First, you installed Apache web server and Phusion Passenger as a Ruby application server, which runs as an Apache module. Then you edited Apache's configuration file for Passenger by adding the default user to be www-data. After this, we created a symbolic link from Redmine's public directory to the web server's root directory. Then, we edited the virtual server's config to serve this particular directory with two Redmine-related configs – RailsBaseURI/redmine, —which tells Ruby on Rails to access Redmine via the /redmine subfolder, and PassengerResolveSymlinksInDocumentRoot tells Passenger to follow symlink to find a Rails application through the symlink path. Instead of this, you could have written the following:

PassengerAppRoot /usr/share/redmine/

Redmine would work the same way.

The best way to run Redmine or any other web-exposed software is to run it as a restricted user from its home directory and adjust Apache or any other web server to serve data from this directory. Running Redmine as a subdomain such as http://redmine.yoursite.com, is done by creating an ordinary subdomain, and an Apache virtual host file for this subdomain with the settings that are provided in this recipe.

If you stumble upon an error such as 403 (forbidden), error 500, or if you see Ruby code on the screen or the Passenger error screen, but you have followed the preceding steps exactly, refer to Troubleshooting Apache installations section in Chapter 9, Troubleshooting.

If you need to run Redmine as sub-uri, then take a look at http://www.redmine.org/projects/redmine/wiki/HowTo_Install_Redmine_in_a_sub-URI.

Install Redmine from a repository, as explained in the Installing Redmine on Ubuntu recipe. If you are using Windows, then install Redmine by following the Windows installation recipe.

First, install Nginx and Thin by typing the following:

sudo apt-get install nginx thin

As we are using Ubuntu, the Aptitude installer will install Nginx and its required libraries for us, perform basic configuration, and start it. To test that it is installed and working correctly, navigate to your server's IP and you should see Nginx's welcome screen:

sudo su

thin config --config /etc/thin1.9.1/redmine.yml --chdir /usr/share/redmine --environment production --socket /var/run/redmine/sockets/thin.sock --daemonize --log /var/log/thin/redmine.log --pid /var/run/thin/redmine.pid --user www-data --group www-data --servers 1 --prefix /redmine

mkdir /var/run/redmine /var/run/redmine/sockets/ /var/run/thin/ /var/log/thin/
chown www-data:www-data /var/run/redmine/sockets/ /var/run/thin/
nano /etc/logrotate.d/thin

/var/log/thin/*.log {
        daily
        missingok
        rotate 52
        compress
        delaycompress
        notifempty
        create 640 root adm
        sharedscripts
        postrotate
                /etc/init.d/thin restart >/dev/null
        endscript
}

pre-start script
    mkdir -p -m0755 /var/run/redmine
    mkdir -p -m0755 /var/run/redmine/sockets
    mkdir -p -m0755 /var/run/thin
    chown www-data:www-data /var/run/redmine/sockets
    chown www-data:www-data /var/run/thin
end script

nano /etc/nginx/sites-available/redmine

upstream redmine_thin_servers {
  server unix:/var/run/redmine/sockets/thin.0.sock;
  # Add additional copies if using multiple Thin servers
  #server unix:/var/run/redmine/sockets/thin.1.sock;
}

server {

  listen   80; ## listen for ipv4
  listen   [::]:80 default ipv6only=on; ## listen for ipv6

  # Set appropriately for virtual hosting and to use server_name_in_redirect
  server_name  localhost;
  server_name_in_redirect off;

  access_log  /var/log/nginx/localhost.access.log;
  error_log  /var/log/nginx/localhost.error.log;

  # Note: Documentation says proxy_set_header should work in location
  #       block, but testing did not support this statement so it has
  #       been placed here in server block
  include /etc/nginx/proxy_params;
  proxy_redirect off;
  # Note:  Must match the prefix used in Thin configuration for Redmine
  #        or / if no prefix configured
  location /redmine {
    root   /usr/share/redmine/public;

    error_page 404  404.html;
    error_page 500 502 503 504  500.html;

    # Uncomment below lines if using HTTPS
    # Note1:  Change $host to SSL CN if multiple host names used
    # Note2:  Adjust prefix, if different in Thin Redmine config
#rewrite ^/redmine/login(.*) https://$host$request_uri permanent;
    #rewrite ^/redmine/my/account(.*) https://$host$request_uri permanent;
    #rewrite ^/redmine/my/password(.*) https://$host$request_uri permanent;
    #rewrite ^/redmine/admin(.*) https://$host$request_uri permanent;

    try_files $uri/index.html $uri.html $uri @redmine_thin_servers;
  }

  location @redmine_thin_servers {
    proxy_pass http://redmine_thin_servers;
  }
}

ln –s /etc/nginx/sites-available/redmine /etc/nginx/sites-enabled/redmine

nano /usr/share/redmine/config/routes.rb

Redmine::Utils::relative_url_root = "/redmine"

RedmineApp::Application.routes.draw do

service thin restart
service nginx restart

First, we performed a Redmine installation on an Ubuntu system, as explained in the recipe Installing Redmine on an Ubuntu server. Then, we installed the required servers: Thin and Nginx. Thin is a dedicated Ruby apps server, and Nginx is a dedicated web and reverse-proxy server. This way, we have multilayer architecture, allowing us to have, for example, one Nginx and multiple thin instances. In this case, it is connected through a Unix socket but more advanced versions of TCP upstream can be used to run multiple servers on multiple machines and load-balance this way.

Line thin config --config /etc/thin1.9.1/redmine.yml --chdir /usr/share/redmine --environment production --socket /var/run/redmine/sockets/thin.sock --daemonize --log /var/log/thin/redmine.log --pid /var/run/thin/redmine.pid --user www-data --group www-data --servers 1 --prefix /redmine uses the thin server to create config file.

After this, we create the necessary folders, set permissions, and add thin to logrotate. Nginx is already there, so we only add thin.

You can use this recipe to set up Nginx and Thin on Windows; the only difference is Windows can't be daemonized. You need to start thin manually; set up a batch or registry file to do it. Also, the TCP port should be used instead of a Unix port.

Redmine can be forced to use SSL all the time through Nginx configuration. To do so, uncomment the SSL lines in Nginx config and copy and paste the server section, set the listen ports to 443, and add the path to your SSL key and certificate:

  ssl  on;
  ssl_certificate  /etc/ssl/certs/ssl-cert-snakeoil.pem;
  ssl_certificate_key  /etc/ssl/private/ssl-cert-snakeoil.key;

A comparison of Ruby web servers can be found at:

http://www.madebymarket.com/blog/dev/ruby-web-benchmark-report.html

Installing optional components is operating system-dependent. This recipe covers the installation of requirements on Ubuntu.

sudo apt-get install ImageMagick libmagickwand-dev

bundle install --with rmagick --without development test postgresql

Installing SCM binaries

Redmine uses several SCM binaries so that it can track code-issue relation in most of the popular Source Control Management (SCM) scenarios. Don't confuse this with Software Configuration Management.

On Ubuntu, installing all supported SCM binaries is extremely simple. Just open up a terminal and type the following:

sudo apt-get install subversion darcs mercurial cvs bzr git

After installation, restart your Redmine and navigate to Administration | Settings | Repositories.

You should get a screen that looks similar to this:

The green check sign and version number indicates that the repository client binary is installed and usable.

Redmine is a complex Ruby on Rails (ROR) application that utilizes a wide variety of Ruby libraries that are required for Redmine to perform various tasks, such as exporting to PDF, connecting to a repository or manipulating images. In this recipe, we covered the installation of ImageMagick and its development libraries, which are optional but required. For example, SCM binaries are used and can be configured on a per-project basis, so you can track multiple repositories on different servers and on different SCM platforms.

Subversion along with Git is really popular and widely used by many developers and teams. Redmine can create repositories for you automatically. Additional recipes and how tos can be found at the bottom of Redmine wiki HowTos:

http://www.redmine.org/projects/redmine/wiki/HowTos.

First, you need to install Ruby Version Manager (RVM). To use it, you need to have some basic build tools installed on your Linux box. If it's a shared hosting server, most likely these tools are already installed; if they are not, then ask root administrators to install basic build tools or look for another server where you can get sudo or root access.

curl -SSL https://rvm.io/mpapis.asc | gpg --import -

gem: --no-rdoc --no-ri

nano ~/.gemrc

yum groupinstall -y development

curl -L get.rvm.io | bash -s stable

source ~/.rvm/scripts/rvm

rvm -v

Once we have installed RVM, we use it to install the required Ruby version.

First, we ensure RVM is working properly after installation by typing the following:

rvm reload

Then, we install a custom Ruby version; at the time of writing this book it is 2.2.1, which is supported by Redmine 3.X versions:

rvm install ruby-head

Then, we proceed with the Redmine installation, as explained in the recipe, Installing from a source on Ubuntu.

After this, running Redmine with Passenger, you need to add the following line to your virtual server's configuration:

PassengerRuby /home/your_user/.rvm/gems/ruby-2.1.0/wrappers/ruby

Replace your_user and the Ruby version with your actual username; text after PassengerRuby is actually an output of the following command:

which ruby

After this, reload Apache. If you are on a shared hosting, Apache probably reloads automatically once your server's virtual configuration is edited; if you have root access, you need to reload it manually.

Redmine should now work, if it's not working or throwing some errors, try looking at Chapter 9, Troubleshooting.

First, we installed Ruby Version Manager (RVM) and its required prerequisites, which is usually a set of basic build tools that are required to compile some binary packages on Linux systems. Then, we used RVM to install a custom version of Ruby. RVM lets users have multiple Ruby versions on the system and switch to the default Ruby among them. However, most users are probably going to need only one custom Ruby version available in their home directory, which is going to be used by Redmine. Once Ruby was installed, we proceeded with the Redmine installation from the source by following the recipe Installing from a source on Ubuntu. Then, we configured Phusion Passenger and Apache by following the recipe Running Redmine with Phusion Passenger but with one variation: we needed to tell Phusion Passenger which Ruby version to use to run Redmine installed in our custom home directory.

You can experiment with different RVM and Ruby versions and have multiple Redmines installed on the same server by following this recipe. This can also be used to upgrade Redmine without ruining your server if you need the system Ruby version to be used by some other applications. In this case, create a new user, install Redmine under this user's home directory, and migrate data from your old installation. Or just copy the whole directory and perform an upgrade also by upgrading the old database.

If you need to use a different version of RVM for some reason, follow the tutorials available on RVM's website: https://rvm.io/rvm/install.