Redmine is a robust project management solution for software development teams to use.  Some of the features that Redmine offers are SVN integration, Issue tracking, RSS feeds, and LDAP Authentication.  Below I will detail the installation process, and pre-installation requirements for setting up and configuring your own Redmine server.

Before we begin though you should be comfortable with the following:

  • linux command line
  • using sudo
  • using vim or vi (we are not doing much, just editing and saving)

For this tutorial, all commands are done using superuser (sudo su), or you can prefix sudo to each command.

Package Installations

Optional Installs

Since this tutorial is for a completely new install of Ubuntu with no additional packages selected during installation, there are a few packages that need to be installed.

Install Vim

Throughout this tutorial, I will be using vim to edit files.  If you are unfamiliar with vim or vi you may want to use another file editor.

  1. Install Vim
    apt-get install vim

Install SSH

If SSH has not been installed on the Ubuntu server you are using, it is recommend that you install it.  Although not necessary, it makes the rest of the tutorial easier.

  1. Install SSH
    apt-get install ssh
  2. Configure SSH to deny root logon.
    vim /etc/ssh/sshd_config

    Change the line

    PermitRootLogin yes

    to

    PermitRootLogin no
  3. Restart SSH
    /etc/init.d/sshd restart

Now you will be able to connect to your Ubuntu server using an ssh client like putty.

Required Installs

Since Redmine will be working with subversion, Apache, PostgreSQL (you can use MySQL if you like), ruby, rails, passenger, etc; there are a lot of packages to install.

Apt-get Installs

  1. Install the following packages using apt-get install
    • apache2-threaded-dev
    • build-essential
    • libapache2-mod-passenger
    • libapache2-mod-perl2
    • libapache2-svn
    • libapache-dbi-perl
    • libauthen-simple-ldap-perl
    • libcurl4-openssl-dev
    • libdbd-pg-perl
    • libdbd-pg-ruby1.8
    • libdigest-sha1-perl
    • libgemplugin-ruby1.8
    • libmagick9-dev
    • libruby1.8-extras
    • php5
    • php5-curl
    • php5-dev
    • php5-pgsql
    • postgresql
    • rails
    • rake
    • ruby1.8-dev
    • rubygems1.8
    • sendmail
    • subversion

Gem Installs

Redmine runs with ruby on rails and uses several ruby gems.  To install these gems, run the following commands.

  1. gem install rails -v=2.3.5
  2. gem install rack -v=1.0.1 (should been installed by the previous command)
  3. gem install rmagick
  4. gem install passenger
  5. gem install pg
  6. gem install -v=0.4.2 i18n

Redmine Install

This section details the installation and configuration setups for the command line part the installation.

PostgreSQL database setup

  1. Sudo as the user postgres and connect to the default database
    sudo –u postgres psql postgres
  2. Create the redmine database user “redmine”
    CREATE ROLE redmine LOGIN ENCRYPTED PASSWORD 'somePassword' NOINHERIT VALID UNTIL 'infinity';
  3. Create the database for Redmine called redmine
    CREATE DATABASE redmine WITH ENCODING='UTF8' OWNER=redmine;
  4. Exit out of psql
    \q

Installing Redmine Files

  1. Create the Redmine install directory
    mkdir /opt/redmine
  2. Checkout the stable Redmine installation
    svn co http://redmine.rubyforge.org/svn/branches/1.1-stable /opt/redmine
  3. Enter the Redmine installation directory
    cd /opt/redmine
  4. Setup permissions for Apache
    chown -R www-data:www-data files log tmp public/plugin_assets/
    chmod -R 755 files log tmp public/plugin_assets/

Configure the Redmine Database Settings

  1. Change directory to the config directory
    cd /opt/redmine/config
  2. Create the database configuration file
    cp database.yml.example database.yml
  3. Edit the database configuration file
    vim database.yml
  4. Make the production setting look like this
    production:
      adapter: postgresql
      database: redmine
      host: localhost
      username: redmine
      password: your_redmine_database_password
      encoding: utf8
  5. Save the file (press esc, type :wq, press enter)

Configure the Redmine Email Settings

  1. Change directory to the config directory
    cd /opt/redmine/config
  2. Create the email configuration file
    cp email.yml.example email.yml
  3. Edit the email configuration file
    vim email.yml
  4. Make the production setting look like this
    production:
      delivery_method::sendmail
      #smtp_settings:
      #address: smtp.example.net
      #port: 25
      #domain: example.net
      #authentication::login
      #user_name: "redmine@example.net"
      #password: "redmine"
  5. Save the file

Setup the Redmine Database

  1. Change directory to /opt/redmine
    cd /opt/redmine
  2. Generate the session store
    rake generate_session_store
  3. Migrate the database (this is a command to run)
    RAILS_ENV=production rake db:migrate
  4. Load the default information into the database
    RAILS_ENV=production rake redmine:load_default_data
  5. You will be prompted for what language you would like to use.  Press enter for English.
  6. Press Enter again

Apache Configuration

Setup passenger

  1. Enable Passenger
    a2enmod passenger
  2. Edit the Passenger configuration file
    vim /etc/apache2/mods-available/passenger.conf
  3. Add the line
    PassengerDefaultUser www-data

Link the Redmine.pm file

  1. Change directory to Apaches perl module directory
    cd /usr/lib/perl5/Apache
  2. Create a softlink to the Redmine.pm file
    ln -s /opt/redmine/extra/svn/Redmine.pm Redmine.pm

Link to the Redmine public folder

  1. Change directory to the document root for Apache
    cd /var/www
  2. Create a softlink to the public folder of redmine
    ln -s /opt/redmine/public redmine

Create the SVN Repositories Directory and Set Permissions

  1. Create the repository directory
    mkdir -p /var/svn/repos
  2. Set permissions for Apache
    chown -R www-data:root /var/svn

Create a SSL Certificate for the Site

If your site already has a signed SSL certificate from a legitimate certificate authority, you can skip this part of the tutorial.

  1. Create a self signed ssl cert
    openssl req -new -x509 -days 365 -nodes -out /etc/ssl/certs/cert.pem -keyout /etc/ssl/certs/cert.pem
  2. Enter in your information companies’ for each prompt, or accept the defaults

Enable Needed Apache Modules and Create the Redmine Site

  1. Enable the following Apache modules using the a2enmod command
    • dav_svn
    • perl
    • ssl
    • rewrite
  2. Create the Redmine site file
  3. vim /etc/apache2/sites-available/redmine
  4. Set the contents of the redmine site file to
  5. <VirtualHost _default_:443>
         ServerAdmin webmaster@localhost
         DocumentRoot /var/www
         PerlLoadModule Apache::Redmine
         PerlLoadModule Authen::Simple::LDAP
         # PerlLoadModule IO::Socket::SSL
         RailsEnv production
         RailsBaseURI /redmine
        <Directory /opt/redmine/public>
             Options FollowSymLinks
             AllowOverride none
             Order deny,allow
             Allow from all
        </Directory>
        #This holds the configuration for the web accessible svn     
        <Location /svn>
            DAV svn
            SVNParentPath "/var/svn/repos"
            AuthType Basic
            AuthName redmine
            Require valid-user
            PerlAccessHandler Apache::Authn::Redmine::access_handler
            PerlAuthenHandler Apache::Authn::Redmine::authen_handler
            RedmineDSN "DBI:Pg:dbname=redmine;host=localhost"
            RedmineDbUser "redmine"
            RedmineDbPass "your_redmine_password"
            RedmineCacheCredsMax 50
        </Location>
        #Used by reposman.rb to create repos for new Redmine projects 
        <Location /sys>
            Order deny,allow
            Allow from 10.30.100.202, 127.0.0.1
            Deny from all
        </Location>
        SSLEngine on
        SSLCertificateFile /etc/ssl/certs/cert.pem
        SSLCertificateKeyFile /etc/ssl/certs/cert.pem
    </VirtualHost>
  6. Save the file
  7. Restart Apache (if all is good, Apache should start without error)
    /etc/init.d/apache2 restart

Setup Automatic Subversion Repository Creation

  1. Make the Redmine log file location
    mkdir /var/log/redmine
  2. Create the log file
    touch /var/log/redmine/reposman_errors.log
  3. Edit the Crontab (you may want to make a backup first)
    crontab -e
  4. Select an editor from the presented list (I selected nano, number 2)
  5. Add this line to the bottom of the file (this is one continuous line broken up for readability),  This line tells the cron to run this job every minute.
    * * * * * ruby /opt/redmine/extra/svn/reposman.rb -r https://your_server_ip/redmine -s
    /var/svn/repos -o www-data --url file:///var/svn/repos >>
    /var/log/redmine/reposman_errors.log #Add new repos for projects
  6. Press Ctrl + O to save the file
  7. Press Enter to confirm the file name
  8. Press Ctrl + X to exit nano

Optional Configurations

Disable Directory Browsing in Apache

We do not want people to be able to browse the files in our webroot, so let’s block that.

  1. Edit the default site configuration file
  2. vim /etc/apache2/sites-available/default
  3. Under the <Directory /var/www> section add a – infront of the word Indexes so the line looks like this
    Options -Indexes FollowSymLinks MultiViews
  4. Do the same for /etc/apache2/sites-available/default-ssl
  5. Restart Apache
    /etc/init.d/apache2 restart

Redirect all HTTP traffic to HTTPS

  1. Edit the default site configuration file
    vim /etc/apache2/sites-available/default
  2. Add the following lines after the DocumentRoot statement (do not change SERVER_NAME or SERVER_PORT, they are variables)
    RewriteEngine on
    RewriteCond   %{SERVER_PORT} ^80$
    RewriteRule   ^(.*)$ https://%{SERVER_NAME}$1 [L,R]
    RewriteLogLevel 2
  3. Restart Apache
    /etc/init.d/apache2 restart

Configuring The Rest of Redmine Via a Web Browser

  1. Open Firefox or you favorite browser and navigate to https://yourIPAddress/redmine.  For example, https://example.page.com/redmineYou should see this page:
    "The Redmine Uconfigured Main Page"

Change the admin account information (defaults are bad!)

  1. Click the “sign in” link in the upper right corner of the page.
  2. Sign in with the following credentials
    username: admin
    password: admin
  3. Click the “Administration” link in the upper left part of the page
  4. Click the “Users” link
  5. Click the username (which is a link) of the admin user
  6. Change the accounts information (especially the password)
  7. Click the save button

Configure the Redmine Server Settings

  1. After signing in as a user with administrator rights, click the “Administration” link in the upper left part of the screen
  2. Click the Settings link
  3. Under the General tab
    1. Change Host Name and Path from localhost:3000 to your.server.com/redmine (ex. example.demo.com/redmine)
    2. Change Protocol from HTTP to HTTPS
    3.  Click the Save button
  4. Under the Authentication tab
    1. Check “Authentication Required”
    2. Check “Enable REST Web Service”
    3. Change Minimum Password Length from 4 to 8
    4. Click the Save button
  5. Under the Projects tab
    1. Change the “Role given to non-admin users who creates a project” from “–Please Select–” to Manager
    2. Click the Save button
  6. Under the Email Notifications tab
    1. Change the “http://hostname/my/account&#8221; part in the “Emails footer” field to https://yourSeverAddress/redmine/my/account (for example: https://demo.example.com/redmine/my/account)
    2. Click the Save button
  7. Under the Repositories tab
    1. Check “Enable WS for repository management”
    2. Check “Filesystem”
    3. Click the Save button

Add LDAP Authentication (Optional)

  1. Click the Administration link in the upper left corner of the page
  2. Click the LDAP Authentication link
  3. Click the New Authentication Mode link
  4. Fill out the form as shown below, substituting in your own Active Directory domain information.  Do not alter the values for the Attributes section, these are domain type specific.
  5. If you want to manually create users who authenticate against AD, then uncheck “On-the-fly  user Creation”, else their account will be created on the first login attempt.
  6. Click the Create button.  If all went well, you should be able to authenticate against Active Directory.
  7. When creating new accounts, you will now have to select what authentication source you want to use.

Creating Your First Redmine Project

  1. Click the Projects link in the upper left corner of the page
  2. Click the New Project link
  3. Enter a Name for the project
  4. Enter a Identifier for the project
  5. The identifier is user to access your svn repository, so if you have an identifier of tstprj your
  6. repository will be available at https://yourServer/svn/tstprj
  7. If you want a private project, only accessible by the members of the project, uncheck Public
  8. Click the Save button
  9. Click the Projects link in the upper left corner of the page
  10. Click the link to the project you just made
  11. Click the Settings link
  12. Click the Members tab
  13. Select the members you would like to add and their role for the project form the list on the left
  14. Click the Add button
  15. Ignore repository tab as the cronjob we created earlier should create an svn reposity and link it to the project for you.

If you have made it this far and everything is working as expected, then Congratulations!!! You have setup your very own Redmine server with Subversion integration.  If things are not working, I recommend looking at the HowTo’s other documentation at redmine.org

Advertisements