Introduction

In business, there are always several projects that require monitoring, management of tickets, documents, time spent, etc. Some paid software do very well this work but still a cost. To overcome this, there are open source project managers, whose Redmine belongs.

It has the advantage of discussing with many other servers (such as Gitlab or Jenkins) and has a lot of features. Many plugins are also available and you can create yourself.

Tutorial Prerequisites

We’ll see how to install Redmine in its latest stable version (currently 3.2). Installing the base server to a production server, with its Web server and service.

For that we will have make sure you have the following prerequisites :

An Ubuntu machine (or Debian-like) with root access

The curl program installed (sudo apt-get install curl)

Knowledge of Linux and patience …

Redmine Prerequisites

Redmine needs a lot of things to work. It uses Ruby and MySQL (or other database), and the Gem programs, Bundler and several other outbuildings. It is always important to consult prerequisite Redmine before embarking on an installation.

As you can see, Redmine supports quite a different version of Ruby and SQL database. What is practical without being. Ruby and Rails are sensitive enough when we blend multiple versions or their libraries, some versions of Ruby have known bugs…

In this tutorial, we will use Ruby 2.1 and MySQL to install Redmine 3.X.

Create a dedicated user

For reasons of good practice, it is always better to create a user who will take care of the created service. Personally, I created a user who is named redmine to keep a logical but it’s not an obligation.

I also chose to put his HOME in a different directory from the usual HOME (/ home /) but this is not compulsory too.

Install Ruby

To install Ruby, we could go through packages provided by your distribution. But it is not necessarily up to date and offer perhaps not recent enough version to install Redmine 3.X. I suggest you go through RVM.

The advantage with RVM is that it allows you to easily manage your versions of Ruby and especially to be able to update them in no time.

Note : It is possible that getting RVM differs on Debian or other distribution. For Ubuntu I had to force port 80 and point to keyserver.ubuntu. Official documentation recommends point to the key server : hkp://keys.gnupg.net.

That’s done, rvm is installed. As said in the installation, to start using it you have to type the following command :

source /usr/local/home/redmine/.rvm/scripts/rvm

Now that you have rvm installed, you can see the different versions of Ruby available by typing rvm list known. It only remains to indicate what version of Ruby you want to install with the command :

rvm install 2.1.5

The program will ask the root password to continue installation and install all alone required dependencies (gcc, g++, make, zlib, etc.). If all goes well, you should have Ruby installed. You can check by typing ruby --version.

Install MySQL

To install MySQL, it’s much easier. Simple installation by deposits will be sufficient, and a library in addition to the adapter mysql2.

Note : again the SQL user and the base are called redmine but this is not mandatory. Feel free to call them as you like, as long as you will apply the changes accordingly in the configuration files.

Configure SQL for Redmine

Redmine works with configuration files with the extension .yml. And its creators are nice, they put examples everywhere. What interests us now is say to Redmine on which Database it should work, so we will copy the conf/database.yml.example :

cd ~/redmine
cp config/database.yml.example config/database.yml

Open the copied file (vi config/database.yml) and edit it to suit your configuration. In our example, it should look like this :

# Examples for PostgreSQL, SQLite3 and SQL Server can be found at the end of the file.
# Indent lines have to be 2 spaces (not tabulation).
production:
adapter: mysql2# adapter use
database: redmine# name of database
host: localhost# hostname
username: redmine# SQL user
password: "your_password"# user password
encoding: utf8# database encoding

Personally, I deleted other configurations that were not useful to me, and I can find them on the sample file.

Install dependencies

Now Redmine needs Bundler to operate and manage the dependencies of its Gems. To install Bundler :

cd ~/redmine
gem install bundler

Then, with Bundler you will be able to install Redmine Gems :

bundle install --without development test rmagick

If all goes well, you should see several installation lines (of different gems) and at the end the following lines :

Bundle complete! XX Gemfile dependencies, XX gems now installed.
Gems in the groups development, test and rmagick were not installed.
Use `bundle show [gemname]` to see where a bundled gem is installed.

Note : as you could see, we tell Bundler not install gems to RMagick. This gem is optional and used to use ImageMagick to manipulate PDF and PNG to export data. If you still want to install it, make sure you have the required dependencies before you run bundle install. For Ubuntu, you need to install the packages imagemagick and libmagickwand-dev beforehand.

Generate an encryption key

This step will enable Rails to have a key to encrypt cookies from your sessions. To generate this key type the following command :

bundle exec rake generate_secret_token

Creating the Schema Base

Redmine will have then need to structure its database to work. It should match your environment, the environment here is production.

Permissions Files

If you have not created your redmine HOME folder in the user or you made a different way, you must ensure that user have rights to the following folders: files , log, tmp and public/plugin_assets.

Congratulations ! You finally have a redmine’s server that is ready !

Test Installation

To test your Redmine server, you will now execute the following command :

bundle exec rails server webrick -e production

Warning : This command is only used to test the installation and should not be used in “production” ! We will see later how to mount the Redmine service.

Open your browser and point to the following address : http://localhost:3000/. If you have a console, download the index of that address (wget http://localhost:3000/).

Tip : if you made this tutorial on a virtual machine that has no GUI (there’s a good chance that’s the case !), you can ensure that the localhost server becomes yours. Mount an SSH tunnel between your PC and the server, with port forwarding (here the port is 3000). Here’s an example : ssh -L 3000:127.0.0.1:3000 login@ip_server. Then point to address http://localhost:3000 with your browser and you should arrive on Redmine interface !

To log, just use the following identifiers :

Login: admin

Password: admin

I advise you to change it later, of course.

You can stop the server by typing Ctrl-C.

Create Redmine Service

You finally have an operational Redmine server … But against it is only accessible on the local loop of the server (localhost) and involves going on port 3000. In addition, it shows us that we can’t use Redmine this way in production. In short, all this is not very pretty.

We will create a service using the unicorn gem and a Web server with Nginx.

Install Unicorn

To use unicorn, we must first install it. Do not touch the Gemfile Redmine and instead use the Gemfile.local file dedicated to this kind of manipulation. Add unicorn gem to that file ( vi Gemfile.local) :

gem'unicorn'

Then re-launch Bundler to install the new gem :

bundle install --without development test rmagick

You should see the installation of new gems (unicorn and its dependencies).

Configuration of Unicorn

Unicorn will now need a configuration file named unicorn.rb. We will place the file in the folder config Redmine (vi config/unicorn.rb) and add the following lines :

Web Server Installation

It remains only to install and configure a virtual server for our Redmine server. We use Nginx as a Web Server.

Installing Nginx

To install Nginx :

sudo apt-get install nginx

Web Server Configuration

Once installed, we will configure the Web server. To avoid conflicts with the default server, you can either delete the default file located in /etc/nginx/sites-available/ or comment lines with ports 80 :

# Name and define socket
upstreamredmine_unicorn{serverunix:/var/run/redmine/redmine-unicorn.sockfail_timeout=0;}# Define server
server{listen80defaultdeferred;client_max_body_size4g;# Name of server and his root folder
server_nameredmine.local.fr;root/usr/local/home/redmine/redmine/public;keepalive_timeout5;try_files$uri/index.html$uri.html$uri@app;# Configuration of proxy
location@app{proxy_set_headerX-Forwarded-For$proxy_add_x_forwarded_for;proxy_set_headerHost$http_host;proxy_redirectoff;proxy_passhttp://redmine_unicorn;}error_log/var/log/nginx/error.logdebug;error_page500502503504/500.html;location=/500.html{root/usr/local/home/redmine/redmine/public;}}

Save and quit. Now your virtual host is configured, you have just to restart Nginx :

sudo service nginx restart

Congratulations ! You should be able to access your production server via the following URL : http://redmine.local.fr.

Some solutions to common errors

If you have only the home page Nginx:

Make sure you have commented (or deleted) the server default.

Check that your nginx redmine configuration file is not wrong (it may lack a ; at end of line for example).

If you have a blank page or error :

Check the logs of nginx: sudo tail -f /var/log/nginx/error.log

Do not forget to restart Nginx each changes on its configuration files.

Conclusion

You now know how to make a Redmine server. Redmine then has many configurations such as rights, dependencies between projects, various tickets, custom fields, etc. It also has a catalog of plugins well supplied, including one that lets you synchronize your Redmine users via Active Directory. Or a plugin that will allow you to link Redmine tickets to Git commits (or Gitlab server).