Redmine

h1. HowTo Install Redmine on Ubuntu step by step

p. This tutorial walks you step-by-step through installing Redmine on a clean/fresh Ubuntu 12.04 installation.  This is intended to be a complete cookbook method for getting Redmine installed and running.  It makes no assumptions about other things being installed or configured.  Since I have had some issues when using the graphical package managers, we will be doing this from the command line prompt to keep things as clear and clean as possible.

p. I recommend that you install any Ubuntu updates prior to beginning this process.  There are almost always some waiting to be installed after the system is first set up.

p. There are several support packages that we will install first.  The first two lines are pretty simple if you just follow the prompts and accept the defaults.  Installing mysql takes just a little more, so the details are spelled out.

<pre>$ sudo apt-get install apache2 libapache2-mod-passenger

$ sudo apt-get install git subversion

$ sudo apt-get install mysql-server mysql-client 

</pre>

p. The installation process for mysql is going to prompt you for a password for the "root" access for the database server, then ask you to confirm the password in a follow-up screen.  This sets the database adminstration password.

<pre>Package configuration                                                           

  ┌────────────────────┤ Configuring mysql-server-5.5 ├─────────────────────┐   

  │ While not mandatory, it is highly recommended that you set a password   │   

  │ for the MySQL administrative "root" user.                               │   

  │                                                                         │   

  │ If this field is left blank, the password will not be changed.          │   

  │                                                                         │   

  │ New password for the MySQL "root" user:                                 │   

  │                                                                         │   

  │ _______________________________________________________________________ │   

  │                                                                         │   

  │                                 <Ok>                                    │   

  │                                                                         │   

  └─────────────────────────────────────────────────────────────────────────┘   

</pre>

<pre>

  ┌────┤ Configuring mysql-server-5.5 ├──────────┐

  │                                              │

  │ Repeat password for the MySQL "root" user.   │

  │                                              │

  │                                              │

  │ ____________________________________________ │

  │                                              │

  │                   <Ok>                       │

  │                                              │

  └──────────────────────────────────────────────┘

</pre>

p. Now it is time to install redmine itself.  

<pre>

$ sudo apt-get install redmine redmine-mysql

</pre>

p. You want to allow dbconfig-common to configure the database when prompted so select *Yes* from the prompt in the panel below.

<pre>

Package configuration                                                           

 ┌──────────────────────────┤ Configuring redmine ├──────────────────────────┐  

 │                                                                           │  

 │ The redmine/instances/default package must have a database installed and  │  

 │ configured before it can be used.  This can be optionally handled with    │  

 │ dbconfig-common.                                                          │  

 │                                                                           │  

 │ If you are an advanced database administrator and know that you want to   │  

 │ perform this configuration manually, or if your database has already      │  

 │ been installed and configured, you should refuse this option.  Details    │  

 │ on what needs to be done should most likely be provided in                │  

 │ /usr/share/doc/redmine/instances/default.                                 │  

 │                                                                           │  

 │ Otherwise, you should probably choose this option.                        │  

 │                                                                           │  

 │ Configure database for redmine/instances/default with dbconfig-common?    │  

 │                                                                           │  

 │                    <Yes>                       <No>                       │  

 │                                                                           │  

 └───────────────────────────────────────────────────────────────────────────┘  

</pre>

p. Then you want to provide the "root" password for the database, so that the installer can create the redmine database.  This is the password set when you installed mysql.

<pre>

Package configuration                                                           

 ┌──────────────────────────┤ Configuring redmine ├──────────────────────────┐  

 │ Please provide the password for hte administrative account with which     │  

 │ this package should create its MySQL database and user.                   │  

 │                                                                           │  

 │ Password of the database's administrative user:                           │  

 │                                                                           │  

 │ ******__________________________________________________________________  │  

 │                                                                           │  

 │                   <Ok>                       <Cancel>                     │  

 │                                                                           │  

 └───────────────────────────────────────────────────────────────────────────┘  

</pre>

p. Tell the redmine installer we are using mysql for this installation by highlighting "mysql" from the list of database choices:

<pre>

Package configuration                                                           

 ┌──────────────────────────┤ Configuring redmine ├──────────────────────────┐  

 │ The redmine/instances/default package can be configured to use one of     │  

 │ several database types. Below, you will be presented with the available   │  

 │ choices.                                                                  │  

 │                                                                           │  

 │ Database type to be used by redmine/instances/default:                    │  

 │                                                                           │  

 │                                  sqlite3                                  │  

 │                                  pgsql                                    │  

 │                                  mysql                                    │  

 │                                                                           │  

 │                                                                           │  

 │                    <Ok>                        <Cancel>                   │  

 │                                                                           │  

 └───────────────────────────────────────────────────────────────────────────┘  

</pre>

p. Now you are asked to provide a password that will be used to protect the redmine database.  Redmine itself will use this when it wants to access mysql.

<pre>

Package configuration                                                           

 ┌──────────────────────────┤ Configuring redmine ├──────────────────────────┐  

 │ Please provide a password for redmine/instances/default to register with  │  

 │ the database server.  If left blank, a random password will be            │  

 │ generated.                                                                │  

 │                                                                           │  

 │ MySQL application password for redmine/instances/default:                 │  

 │                                                                           │  

 │ *******__________________________________________________________________ │  

 │                                                                           │  

 │                    <Ok>                        <Cancel>                   │  

 │                                                                           │  

 └───────────────────────────────────────────────────────────────────────────┘ 

</pre>

Now confirm the redmine password.

<pre>

Package configuration                                                           

   ┌────┤ Configuring redmine ├─────┐                       

   │                                │                       

   │                                │                       

   │ Password confirmation:         │                       

   │                                │                       

   │ *******_______________________ │                       

   │                                │                       

   │     <Ok>         <Cancel>      │                       

   │                                │                       

   └────────────────────────────────┘   

</pre>

p. You need to modify two files for apache.  The first is /etc/apache2/mods-available/passenger.conf which needs the text *PassengerDefaultUser www-data* added as seen here:

<pre>

<IfModule mod_passenger.c>

  PassengerDefaultUser www-data

  PassengerRoot /usr

  PassengerRuby /usr/bin/ruby

</IfModule>

</pre>

Now create a symlink to connect Redmine into the web document space:

<pre>

$ sudo ln -s /usr/share/redmine/public /var/www/redmine

</pre>

p. And modify /etc/apache2/sites-available/default to insert the following with the other <Directory> sections so that apache knows to follow the symlink into Rails:

<pre>

<Directory /var/www/redmine>

	RailsBaseURI /redmine

	PassengerResolveSymlinksInDocumentRoot on

</Directory>

</pre>

Now restart apache:

<pre>

$ sudo service apache2 restart

</pre>

p. You should now be able to access redmine from the local host

<pre>$ firefox http://127.0.0.1/redmine

</pre>

p. In the upper right corner of the browser window you should see the "Sign in" link.  Click that and enter "admin" at both the *Login:* and *Password:* prompts.  Note: _this is not the password you set during the installation process_.  Click the *Login* button.

p. I recommend that the next thing you do is to click on *My account* in the upper right corner and change that password.  In the page that is displayed there should be a *Change password* link in the upper right of the white area of the page.  Click to change the password.