Note: Redmine 1.4.0 has been released. This howto might be incompatible with the new version.
Redmine is an open-source web-based project management and bug-tracking tool.
This article explains how to install it on Arch Linux. At the time this article was written the official documentation page lacked of clear installation instructions.
Redmine is written in the ruby programming language and uses Rails as a web application framework which can be compared to the Zend framework for the php language. To get Redmine run on a webserver, Rack is required which provides a minimal interface between a webserver and the ruby web app.
Redmine is shipped with a script which launches a webserver called Webrick. More precisely Webrick is a Ruby standard library providing simple HTTP web server services.
With this background one understands what the Redmine’s requirements are for. According to Redmine’s website these are
Redmine 1.3.x Ruby 1.8.6 or 1.8.7 Rails 2.3.14 Rack 1.1.x Rake 0.8.7 i18n 0.4.2
Rake is required to generate a session store and to create/initialize the database. It’s a build tool similar to make but for ruby. i18n is for localization.
In the following it’s shown how to install Redmine automatically or how to do things manually.
Because Redmine doesn’t support Ruby 1.9 you have to uninstall any existing Ruby 1.9 if installed.
pacman -Rcs ruby
Before you proceed with the howto be sure you have the
base-devel package installed. If you don’t have it yet run
pacman -S base-devel
And also get the
yaourt tool which is used to load packages from the user repository AUR. Just follow these steps.
Installing the automatic way
Every chunk of Ruby required by Redmine will be installed automatically because pacman, the package manager in Arch Linux, will look at its dependency list and installs everything that redmine needs. Pacman goes up the whole dependency hierarchy so that at the end nothing is missing.
Just type in the following command and proceed with the “Configure Redmine and initialize the database” section.
yaourt -S ruby-redmine
Important: At the time this article was written, the
ruby-redmine package provided version 1.2 which is out-of-date. If you want to install version 1.3 follow the next section.
In order to run redmine some dependencies must be installed first. All the ruby stuff is installed by using RubyGems which is a package manager for the Ruby programming language. It provides a standard format for distributing Ruby programs and libraries (in a self-contained format called a “gem”), a tool designed to easily manage the installation of gems, and a server for distributing them. It is analogous to EasyInstall for the Python programming language.
You don’t need to install Ruby1.8 and RubyGems seperately as they are automatically installed as dependencies. Both are installed as
gem-1.8 in the bin directory.
Before proceeding with the installation be aware that a package might look for ruby or gem instead of ruby-1.8 and gem-1.8. If you encounter any problems during the installation, create the following symlinks. I recommend to create them only if you really run into trouble as the symlinks won’t be owned by any package.
ln -s /usr/bin/ruby-1.8 /usr/bin/ruby ln -s /usr/bin/gem-1.8 /usr/bin/gem
Now install all the ruby stuff. Be patient, this step takes some time.
yaourt -S ruby1.8-rake ruby1.8-i18n-v0.4.2 ruby1.8-rails
The SQLite support is yet missing, so by running the next command the SQLite3 database engine and the ruby interface will be installed.
yaourt -S ruby1.8-sqlite3
To see if everything got successfully installed you can run
gem-1.8 list which should give you the following list.
# gem-1.8 list *** LOCAL GEMS *** actionmailer (2.3.14) actionpack (2.3.14) activerecord (2.3.14) activeresource (2.3.14) activesupport (2.3.14) i18n (0.4.2) rack (1.1.0) rails (2.3.14) rake (0.8.7) sqlite3 (1.3.5)
Install some more ruby dependencies, this time directly in RubyGems as there are no Arch Linux packages available:
sudo gem-1.8 install shoulda -v=2.10.3 sudo gem-1.8 install edavis10-object_daddy mocha
Now it’s redmine time. Download, extract and move redmine to the directory where you wish it to be installed.
cd /tmp # download redmine wget http://rubyforge.org/frs/download.php/75597/redmine-1.3.0.tar.gz # install redmine in your home directory in .redmine mkdir ~/.redmine tar xvfz redmine-1.3.0.tar.gz -C ~/.redmine cd ~/.redmine/redmine-1.3.0
Configure Redmine and initialize the database
Change to the directory where you installed redmine. In this example it’s
Copy the database configuration file
First change to the config directory and copy the configuration.
cd config cp database.yml.example database.yml
Configure redmine to use SQLite3
Being in the config directory open
database.yml in the editor of your choice (e.g. vim).
Everything defined as test will be erased so don’t leave it as is and remove the prefix
test_. Scroll down and change the section
test_sqlite3: adapter: sqlite3 database: db/test.sqlite3
sqlite3: adapter: sqlite3 database: db/redmine.sqlite3
Fix a redmine bug
Still being in the config directory change to the environments directory and copy the SQLite3 ruby script.
cd environments cp test_sqlite3.rb sqlite3.rb
Create and initialize the database
Note (Jan 8th): The following steps probably require to be executed as the user under which redmine should run later. I will update this howto as soon as possible.
Now go back to the root of your redmine installation and initialize the database:
rake-1.8 generate_session_store RAILS_ENV=sqlite3 rake-1.8 db:migrate
The next step is optional but highly recommended.
RAILS_ENV=sqlite3 rake-1.8 redmine:load_default_data
The user who runs Redmine must have write permission on the following subdirectories: files, log, tmp (create the last one if not present).
Assuming you run Redmine with a redmine user:
mkdir tmp public/plugin_assets sudo chown -R redmine:redmine files log tmp public/plugin_assets sudo chmod -R 755 files log tmp public/plugin_assets
Being in the root of your redmine installation start the server with
ruby-1.8 script/server webrick -e sqlite3
Congratulations! You’re running redmine. Open your browser, point it to htt://127.0.0.1:3000 and login as admin with the following login.
- Login: admin
- Password: admin
Don’t forget to change the password immediately if your Redmine is accessible by other people including the evil ones out there.
Depending on what redmine modules you want to use you must also install the corresponding Arch Linux package.
- ruby1.8-rmagick: Enable Gantt export to png image
Source Code Management
If you need revision control in your projects, install one or multiple of these (depending on what you use):
- subversion>=1.3.0: Subversion repository browsing
- git: Git repository browsing
- darcs: Darcs repository browsing
- bzr: Bazaar repository browsing
- mercurial: Mercurial repository browsing
The official redmine documentation says that it will look on the
PATH for the binaries (svn, hg, git, cvs, bzr, darcs) if installed at all but my experience is that one has to configure them explicitly.
Note: Before you edit the configuration file also read the issues section at the end of this howto.
Go to the redmine root, change into the config directory and copy
configuration.yml. Open it in your editor and scroll down to the SCM configuration section. There you fill out the scm commands, in the following example only
scm_git_command got defined. Restart Redmine to take effect of the new configuration.
# Configuration of SCM executable command. # # Absolute path (e.g. /usr/local/bin/hg) or command name (e.g. hg.exe, bzr.exe) # On Windows + CRuby, *.cmd, *.bat (e.g. hg.cmd, bzr.bat) does not work. # # On Windows + JRuby 1.6.2, path which contains spaces does not work. # For example, "C:\Program Files\TortoiseHg\hg.exe". # If you want to this feature, you need to install to the path which does not contains spaces. # For example, "C:\TortoiseHg\hg.exe". # # Examples: # scm_subversion_command: svn # (default: svn) # scm_mercurial_command: C:\Program Files\TortoiseHg\hg.exe # (default: hg) # scm_git_command: /usr/local/bin/git # (default: git) # scm_cvs_command: cvs # (default: cvs) # scm_bazaar_command: bzr.exe # (default: bzr) # scm_darcs_command: darcs-1.0.9-i386-linux # (default: darcs) # scm_subversion_command: scm_mercurial_command: scm_git_command: /usr/bin/git scm_cvs_command: scm_bazaar_command: scm_darcs_command:
If you want to use MySQL instead of SQLite you want to install
Go to the official redmine documentation to get more information on this.
After configuring the scm commands and restarting Redmine I couldn’t create new issues. This error message appeared:
SocketError in IssuesController#create getaddrinfo: Name or service not known RAILS_ROOT: ~/.redmine/redmine-1.3.0
Here’s the application trace I got:
Application Trace | Framework Trace | Full Trace /opt/ruby1.8/lib/ruby/1.8/net/smtp.rb:551:in `initialize' /opt/ruby1.8/lib/ruby/1.8/net/smtp.rb:551:in `open' /opt/ruby1.8/lib/ruby/1.8/net/smtp.rb:551:in `do_start' /opt/ruby1.8/lib/ruby/1.8/timeout.rb:67:in `timeout' /opt/ruby1.8/lib/ruby/1.8/timeout.rb:101:in `timeout' /opt/ruby1.8/lib/ruby/1.8/net/smtp.rb:551:in `do_start' /opt/ruby1.8/lib/ruby/1.8/net/smtp.rb:525:in `start' ~/.redmine/redmine-1.3.0/vendor/rails/actionmailer/lib/action_mailer/base.rb:715:in `perform_delivery_smtp' ~/.redmine/redmine-1.3.0/vendor/rails/actionmailer/lib/action_mailer/base.rb:556:in `__send__' ~/.redmine/redmine-1.3.0/vendor/rails/actionmailer/lib/action_mailer/base.rb:556:in `deliver!' ~/.redmine/redmine-1.3.0/app/models/mailer.rb:322:in `deliver!' ~/.redmine/redmine-1.3.0/app/models/issue_observer.rb:20:in `after_create' ~/.redmine/redmine-1.3.0/app/controllers/issues_controller.rb:145:in `create'
This came because I didn’t configure the smtp server from which Redmine tries to send notification emails (when a user creates issues).
~/.redmine/redmine-1.3.0/config/configuration.yml you can modify the default configuration or use a new configuration with the environment you are using. In this howto the environment was always sqlite3. I chose to append a new section which allows me to provide Redmine with other default values and leave the sqlite3 section just for once I want to switch to another environment.
# default configuration options for all environments default: # Outgoing emails configuration (see examples above) email_delivery: delivery_method: :smtp smtp_settings: address: smtp.example.net port: 25 domain: example.net authentication: :login user_name: "firstname.lastname@example.org" password: "redmine" sqlite3: email_delivery: delivery_method: :smtp smtp_settings: address: smtp.slopjong.de port: 25 domain: slopjong.de authentication: :login user_name: "slopjong" password: "asdf1234"
Of course, use your own login
You might also be interested to install your own mailserver. Read Jeffrey’s guide for this. I didn’t test his guide so it could be out-of-date.