1. Guides & Tutorials
  2. Applications
  3. Project Management
  4. How to Install and Configure Redmine on Ubuntu 16.04

How to Install and Configure Redmine on Ubuntu 16.04

Updated by Linode Written by Angel Guarisma

Contribute on GitHub

Report an Issue | View File | Edit File

How to Install and Configure Redmine on Ubuntu

What is Redmine?

Redmine is a project management web app that allows users to manage projects flexibly while offering robust tracking tools and an extensive library of plug-ins. This free and open source solution offers an alternative to paid project management tools and includes support for wikis, forums, calendars, and data visualization tools.

This guide will show you how to install and set up Redmine on Ubuntu 16.04 through the Passenger application server connected to NGINX.

Before You Begin

Note
The steps in this guide require root privileges. Be sure to run the steps below as root or with the sudo prefix. For more information on privileges, see our Users and Groups guide.

Install Dependencies

sudo apt install build-essential mysql-server ruby ruby-dev libmysqlclient-dev imagemagick libmagickwand-dev

Configure MySQL

MySQL needs to be configured so that Redmine can store data. You can log in to the root account of your database using the password that you set when you installed mysql-server.

 mysql -u root -p

  1. After logging in, create a new database and database user:

    CREATE DATABASE redmine;
CREATE USER 'redmine'@'localhost' IDENTIFIED BY 'password';
GRANT ALL PRIVILEGES ON redmine.* TO 'redmine'@'localhost';
FLUSH PRIVILEGES;
quit;

Install Ruby

Redmine requires Ruby to run. Use the Ruby Version Manager (RVM) to install Ruby 2.2.3.

  1. Curl the latest version of RVM.

    gpg --keyserver hkp://keys.gnupg.net --recv-keys 409B6B1796C275462A1703113804BB82D39DC0E3
curl -sSL https://get.rvm.io | bash -s stable
source ~/.rvm/scripts/rvm

  2. Users of RVM must be in the rvm group. Create this group, add a user, log out, and log back in:

    sudo groupadd rvm
sudo usermod -a -G rvm username
exit

  3. Check the requirements for the install, and install Ruby (version 2.2.3):

    rvm requirements
rvm install 2.2.3
rvm use 2.2.3 --default

Install Passenger and NGINX

Passenger is an application server that runs your web application then communicates with the web server. The project has well-written documentation on installing Passenger and NGINX on Ubuntu 16.04 with an apt repository.

  1. Install the Passenger PGP key and HTTPS support for the package manager:

    sudo apt install -y dirmngr gnupg
sudo apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys 561F9B9CAC40B2F7
sudo apt install -y apt-transport-https ca-certificates

  2. Add the Passenger APT repository:

    sudo sh -c 'echo deb https://oss-binaries.phusionpassenger.com/apt/passenger xenial main > /etc/apt/sources.list.d/passenger.list'
sudo apt update

  3. Install Passenger and NGINX

    sudo apt install -y nginx-extras passenger

Configure NGINX

Passenger has now installed NGINX with Passenger compiled in. You have to configure NGINX to make sure it uses Passenger correctly:

  1. Uncomment the include /etc/nginx/passenger.conf; line in /etc/nginx/nginx.conf. Edit your config file to resemble the one below:

    /etc/nginx/nginx.conf 
     1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

    ##
# Phusion Passenger config
##
# Uncomment it if you installed passenger or passenger-enterprise
##

include /etc/nginx/passenger.conf;

##
# Virtual Host Configs
##

include /etc/nginx/conf.d/*.conf;

  2. Copy the default nginx site configuration file. The working configuration file in this guide will be /etc/nginx/sites-available/default:

    cp /etc/nginx/sites-available/default /etc/nginx/sites-available/default.orig

  3. Change the root directory for the website, and add additional Passenger configurations. To do this, add these lines to the server{} block of the file:

    /etc/nginx/sites-available/default 
    1
2
3

    root /data/redmine/redmine/public;
passenger_enabled on;
client_max_body_size 10m;

  4. In the same file, comment out the #location section:

    /etc/ningx/site-available/default 
    1
2
3
4
5

    #location / {
# First attempt to serve request as file, then
# as directory, then fall back to displaying a 404.
    #try_files $uri $uri/ =404;
#}

  5. Change the permissions for /var/www:

    sudo mkdir /var/www
sudo chown -R www-data /var/www

  6. Restart nginx:

    sudo systemctl restart nginx

  7. Validate the installation of Passenger and NGINX:

    sudo /usr/bin/passenger-config validate-install

    Press enter when the first option is selected:

      
 If the menu doesn't display correctly, press '!'

‣ ⬢  Passenger itself
  ⬡  Apache

  -------------------------------------------------------------------------

* Checking whether this Passenger install is in PATH... ✓
* Checking whether there are no other Passenger installations... ✓
Everything looks good. :-()

  8. Finally, check if NGINX has started the Passenger core process:

    sudo /usr/sbin/passenger-memory-stats

    If Passenger was installed with NGINX correctly, your output should resemble:

      
--------- NGINX processes ----------
PID   PPID  VMSize    Private  Name
------------------------------------
6399  1     174.9 MB  0.6 MB   nginx: master process /usr/sbin/nginx -g daemon on; master_process on;
6404  6399  174.9 MB  0.7 MB   nginx: worker process
### Processes: 2
### Total private dirty RSS: 1.23 MB


---- Passenger processes -----
PID   VMSize    Private  Name
------------------------------
6379  441.3 MB  1.2 MB   Passenger watchdog
6382  660.4 MB  2.9 MB   Passenger core
6388  449.5 MB  1.4 MB   Passenger ust-router
### Processes: 3

Install Redmine

  1. Create a redmine user and add the new user to the sudo group:

    sudo adduser --system --shell /bin/bash --gecos 'Redmine Administrator' --group --home /data/redmine redmine; sudo usermod -a -G rvm redmine
sudo adduser redmine sudo

  2. Log in as the redmine user:

    su -
passwd redmine
su redmine
cd

  3. Download the Redmine tarball as the new user. Extract it and rename the directory to redmine for convenience:

    wget https://www.redmine.org/releases/redmine-3.4.4.tar.gz
tar -zxvf redmine-3.4.4.tar.gz
mv redmine-3.4.4 redmine

  4. Add the database information created earlier to Redmine’s config file. Only complete the section marked “Production,” as you will not be using the development or test environments.

    cd redmine
cp -pR config/database.yml.example config/database.yml
emacs config/database.yml

  5. In the redmine directory, install the Ruby dependencies:

    sudo gem install bundler
sudo bundle install --without development test

  6. After the installation finishes, you need to use Rake to start the server:

    bundle exec rake generate_secret_token
RAILS_ENV=production bundle exec rake db:migrate
RAILS_ENV=production bundle exec rake redmine:load_default_data

  7. Restart NGINX, and navigate to your server’s IP address and you will be greeted by the Redmine application:

    sudo systemctl restart nginx

    Login

Redmine

The default login and password for Redmine are:

 Login: admin
 Password: admin

After logging in for the first time, you will be prompted to change your credentials. Replace them with something secure.

Install a Plug-in

Redmine is built to be used with plug-ins. Plug-ins are installed to redmine/plugins. This section will demonstrate installing a plug-in by installing scrum2b, a plug-in for managing a Scrum/Agile workflow.

If not installed, install git or download the plug-in directly through the Github website:

sudo apt install git

  1. Move to redmine/plugins and clone the plug-in:

    cd plugins
git clone https://github.com/scrum2b/scrum2b

  2. Use Bundle to install the plug-in, then restart NGINX:

    bundle install
sudo systemctl restart nginx

  3. Navigate to Redmine in your browser. Log in, click admin then click plugins

    scrum2b

Next Steps

You now have a working Redmine setup on your Linode. If you plan on using it in production, explore plug-ins that will be useful for your team. Take a look at some of the guides below to customize Redmine for your team.

More Information

You may wish to consult the following resources for additional information on this topic. While these are provided in the hope that they will be useful, please note that we cannot vouch for the accuracy or timeliness of externally hosted materials.

Join our Community

Find answers, ask questions, and help others.

This guide is published under a CC BY-ND 4.0 license.