Installing from a source on Ubuntu

There are two common ways to obtain a Redmine source: through Subversion Client (SVN) or by downloading the compressed source code from a website.

Also, there are two common ways to install Redmine: under a Linux user account, or system-wide. The previous recipe installed Redmine system-wide. This recipe covers the installation of Redmine under an ordinary user account in the user's home directory, which is the recommended way to install Redmine.

Getting ready

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:

Database configuration

You also need to have a MySQL, PostgreSQL, or SQLite database that is going to be used with Redmine. If you are creating a MySQL, or PostgreSQL database manually, make sure that you create a UTF-8 database with a UTF-8 general_ci collation. To create a MySQL database, perform the following:

1. Login to MySQL with a user that has sufficient privileges to create databases:

   mysql –u root –pmy_password
   

2. Create a UTF-8 database as follows; please keep in mind that you can choose any database name:

   CREATE DATABASE redmine CHARACTER SET utf8 COLLATE utf8_general_ci;
   

3. Create a user with a password (write it down in a safe place):

   CREATE USER 'redmine'@'localhost' IDENTIFIED BY 'my_password';
   

4. Give your user privileges, as follows:

   GRANT ALL PRIVILEGES ON redmine.* TO 'redmine'@'localhost';
   

How to do it…

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.

Obtaining the Redmine source files

Firstly, obtain the Redmine source, either by downloading it to your computer, unpacking it, and uploading it to /home/your_user/redmine, or by following the methods that are illustrated next.

Downloading and extracting the Redmine source files

The wget tool is installed by default on the Ubuntu server; so, in order to use it to get the Redmine source, we perform the following tasks:

1. Navigate to your user's home directory by typing the following:

   cd ~
   

2. Utilize the wget tool to obtain a compressed Redmine source, as follows:

   wget http://www.redmine.org/releases/redmine-3.2.0.tar.gz
   

3. Unpack the archive:

   tar xvf redmine-3.2.0.tar.gz && mv redmine-3.2.0 redmine
   

4. Remove the downloaded archive file:

   rm redmine-3.2.0.tar.gz
   

The SVNcheckout method

Many administrators who plan to upgrade Redmine often prefer to grab the code via SVN because it allows code to be automatically updated while preserving local changes with a simple SVN update command. To use this method, perform the following steps:

1. Navigate to your user's home directory by typing the following:

   cd ~
   

2. Create a directory for Redmine, as follows:

   mkdir redmine
   

3. Check out Redmine from its official repository, as follows:

   svn co https://svn.redmine.org/redmine/branches/3.2-stable redmine
   

Redmine installation

After any of the previous methods, you should end up with the latest Redmine source in your home directory:

1. To proceed with the installation, use the following command:

   sudo gem update && sudo gem install bundler
   

   Tip

   If you are behind a proxy, the command to run gem commands behind a proxy is as follows:

   gem command_name –http-proxy http://your_proxy:port
   

2. Copy the default database settings to file without the .example extension:

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

3. Edit the database settings using your favorite editor, in this case, nano:

   nano redmine/config/database.yml
   

4. You can edit production settings, or those for any other environment type, (for production, replace the values with your credentials):

   production:
    adapter: mysql2
    database: redmine
    host: localhost
    username: redmine
    password: my_password
    encoding: utf8

5. Now, let's run bundler from the directory from which we extracted Redmine:

   bundle install --without development test postgresql sqlite rmagick
   

6. After completing the bundler installation, you need to run several commands that are required by Redmine, as follows:

   bundle exec rake generate_secret_token
   

7. Proceed by populating the Redmine database as follows:

   bundle exec rake db:migrate RAILS_ENV=production
   

8. Load the default data, and choose a proper locale for default data:

   bundle exec rake redmine:load_default_data RAILS_ENV=production
   

9. Now, create the required directories:

   mkdir -p tmp tmp/pdf public/plugin_assets
   

10. Change permissions accordingly:

    chmod -R 755 files log tmp public/plugin_assets
    

11. Now, you can test the installation by running Redmine through a rails server:

    bundle exec rails server webrick -e production –b your_server_ip
    

12. Test whether Redmine is properly installed by opening the browser and typing http://your_server_ip:3000/. The Redmine home page should be loaded.

How it works…

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.

See also

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