Redmine

From Blue-IT.org Wiki

Contents

Redmine 2.x or 3.x and Ubuntu 14.04

Upgrade

First make a backup of both database and redmine dir. Then, if you downloaded Remine with SVN this boils down to 

cd /path/to/redmine; \
snv update; \
bundle update; \
bundle exec rake db:migrate RAILS_ENV=production; \
bundle exec rake redmine:plugins:migrate RAILS_ENV=production; \
bundle exec rake tmp:cache:clear tmp:sessions:clear RAILS_ENV=production; \
chown -R www-data:www-data .

Voilà ;-)

Install Ruby, Rails and Redmine manually with rvm, redmine sources for apache2

This is the recommended method for Ubuntu

After having a lot of problems installing ruby and switching between versions with the ubuntu packaging system (see Do it the Ubuntu way (debs and ppa), I decided to go with rvm, the standard installation script for ruby. Also I decided to use the stock redmine installation.

For installing ruby I followed the instructions here:

Other helpful sites for dealing with ruby are:


Mainly I followed the installation instructions at RedmineCRM but I used apache2 and the actual version of redmine:

Before you start, it might be wise to create a swap file first, because the compilation task for apache mod_passenger can take a lot of memory:

First make a backup of redmine (this was an Ubuntu-way-installation before, your directories might differ): 

cp -av /etc/redmine /etc/redmine.bak
cp -av /var/lib/redmine /var/lib/redmine.bak
cp -av /usr/share/redmine /usr/share/redmine.bak
# Backup your database:
# mysqldump / psql --dumpall ... > redmine.sql # you should know how to this

Then we will uninstall all packages concerning ruby, rails and redmine from the system ... 

apt-get remove --purge ruby*

... and cleanup directories: 

/usr/local/bin # check this for leftovers of manual installations of rake, ri, rdoc ...
rm -rf /var/lib/gems

Then we will download the latest redmine version and afterwards setup ruby and Co. You need subversion installed for this method, but you can also download redmine with wget and unzip it: 

cd /srv/www
svn co http://svn.redmine.org/redmine/branches/3.1-stable redmine

Set permissions for your redmine installation and create necessary files: 

cd /srv/wwww/redmine
mkdir public/plugin_assets
chown -R www-data:www-data files log tmp public/plugin_assets config.ru
chmod -R 755 files log tmp public/plugin_assets
[ -f Gemfile.local ] || touch Gemfile.local
chmod 644 Gemfile.local
chown www-data.www-data Gemfile.local

Now copy over necessary files from your old redmine installation 

rm files/delete.me
cp -av /var/lib/redmine.bak/default/files files
cp -av /usr/share/redmine.bak/public/themes/* public/themes/.
cp -av /usr/share/redmine.bak/plugins/* plugins/.
cp -av /etc/redmine.bak/default/database.yml config/.
chmod 644 config/database.yml


Setup ruby: 

sudo su 
# You should consider install ruby not as root, but a special user
# and add that user to the group rvm
cd ~
apt-get install libgdbm-dev libncurses5-dev automake libtool bison libffi-dev
gpg --keyserver hkp://keys.gnupg.net --recv-keys 409B6B1796C275462A1703113804BB82D39DC0E3
curl -L https://get.rvm.io | bash -s stable
source /etc/profile.d/rvm.sh
rvm install 2.2.3
rvm use 2.2.3 --default
ruby -v
#> ruby 2.2.3p173 (2015-08-18 revision 51636) [x86_64-linux]

Take care for Gem preferences and install the bundler: 

echo "gem: --no-ri --no-rdoc" > ~/.gemrc
gem install bundler

Install rails: 

gem install rails -v 4.2.4

Next we prepare setting up database connection (postgres or mysql, also see: https://gorails.com/setup/ubuntu/14.04)

Install the database gems for postgresql ... (see section #Postgres): 

gem install pg
gem install activerecord-postgresql-adapter
bundle install

... or mysql (see section #Mysql): 

gem install mysql2

Time to prepare the installation for apache2 mod_passenger: 

gem install passenger --no-ri --no-rdoc

Now you can start the compilation and configuration script for mod_passenger for apache2. The compilation script passenger-install-apache2-module tells you about everything you need to do (installing additional devs, the lines for the apache configuration file.

It is very likely that you have to install the development files first: 

apt-get install apache2-threaded-dev libaprutil1-dev libapr1-dev

No start the script ... which can take some time ... : 

passenger-install-apache2-module

... so go and get a green tee or make your dishes ;-) You are almost there.

The script output (which you should read carefully!) tells you for example add the corresponding lines from the compilation script output in your virtual hosts file: 

  LoadModule passenger_module /usr/local/rvm/gems/ruby-2.2.3/gems/passenger-5.0.21/buildout/apache2/mod_passenger.so
  <IfModule mod_passenger.c>
    PassengerRoot /usr/local/rvm/gems/ruby-2.2.3/gems/passenger-5.0.21
    PassengerDefaultRuby /usr/local/rvm/gems/ruby-2.2.3/wrappers/ruby
  </IfModule>

Then you have also to alter the section for ruby at the beginning of my virtual hosts file to point to the right gems directory: 

SetEnv GEM_HOME /usr/local/rvm/gems/ruby-2.2.3/


Install all necessary dev-packages for compiling your database connection and e.g. rmagick (see later sections):

Now install configure the database.yml and then change to your redmine directory. Pay attention: if you have some plugins, which need special treatment (e.g. special gems), you probably have to resolve this issues before: 

cd /srv/www/redmine
bundle install

Migrate your database and plugins: 

cd /srv/www/redmine
bundle exec rake db:migrate RAILS_ENV=production
bundle exec rake redmine:plugins RAILS_ENV=production

Generate a secret token: 

bundle exec rake generate_secret_token

Restart redmine (because we user passenger) 

touch tmp/restart.txt # IMPORTANT !!!
service apache2 start

Now everything should work ;-) As I said before, with this method I did not have any single problem. With the next method, using the debian packages I had a lot of trouble. This is sad, because I like the debian packaging.

Do it the Ubuntu way (debs and ppa)

NOT RECOMMENDED

[UPDATE]: this might be a pain when it comes to update ruby, rails or redmine periodically. So I decided to go with rvm (see section above) which led me to a fully functional redmine version within an hour.

I also had to look into some logfiles, but it was less problematic than dealing with the ubuntu packages. Plus: I could choose the ruby, rails and redmine version I liked without any hassle. --Apos (talk) 19:31, 25 October 2015 (CET)

(Credits goto an excerpt from https://gist.github.com/subchen/9a78c399ec150544ac4d / THANKS)

see http://brightbox.com/docs/ruby/ubuntu/

ruby 1.9.3 

sudo apt-get install ruby
sudo apt-get install ruby-dev # THIS IS IMPORTANT FOR SOME GEMS TO INSTALL !!!

ruby 2.1 

sudo apt-get install python-software-properties
sudo apt-add-repository ppa:brightbox/ruby-ng
sudo apt-get update
sudo apt-get install ruby2.1 
sudo apt-get install ruby2.1-dev # THIS IS IMPORTANT FOR SOME GEMS TO INSTALL !!!

switch to 2.1 

sudo update-alternatives --remove ruby /usr/bin/ruby2.1
sudo update-alternatives --remove irb /usr/bin/irb2.1
sudo update-alternatives --remove gem /usr/bin/gem2.1

OR (check your version of ruby, rdoc and gem!) 

sudo update-alternatives --remove ruby /usr/bin/ruby1.9.1
sudo update-alternatives --remove ruby /usr/bin/rdoc1.9.1
sudo update-alternatives --remove gem /usr/bin/gem1.9.1

Then update the alternatives to ruby 2.1 

sudo update-alternatives \
     --install /usr/bin/ruby ruby /usr/bin/ruby2.1 50 \
     --slave /usr/bin/irb irb /usr/bin/irb2.1 \
     --slave /usr/bin/rake rake /usr/bin/rake2.1 \
     --slave /usr/bin/gem gem /usr/bin/gem2.1 \
     --slave /usr/bin/rdoc rdoc /usr/bin/rdoc2.1 \
     --slave /usr/bin/testrb testrb /usr/bin/testrb2.1 \
     --slave /usr/bin/erb erb /usr/bin/erb2.1 \
     --slave /usr/bin/ri ri /usr/bin/ri2.1

update-alternatives --config ruby
update-alternatives --display ruby

[...]

If something goes wrong with your ruby version you can manually set the links for ruby: 

ln -s /usr/bin/ruby2.1 /usr/bin/ruby
ln -s /usr/bin/irb2.1 /usr/bin/irb
ln -s /usr/bin/rake2.1  /usr/bin/rake
ln -s /usr/bin/gem2.1  /usr/bin/gem
ln -s /usr/bin/rdoc2.1  /usr/bin/rdoc
ln -s /usr/bin/testrb2.1  /usr/bin/testrb
ln -s /usr/bin/erb2.1  /usr/bin/erb
ln -s /usr/bin/ri2.1  /usr/bin/ri

Update your apache config

The virtual host file must point to the right ruby version:

see: Apache_2.4

Update and install your bundle

Then update and install your libs necessary to run redmine - this will update and install all neccesary dependencies: 

sudo cd /usr/share/redmine

This is alway necessary if you switch to a new ruby version!: 

sudo gem install bundler

Install all your bundles: 

sudo bundle install


This might give you some faults, you have to resolve and google for!

e.g. an error for the rmagick gem, after googling I resolved that with: 

apt-get install libmagickwand-dev

Then again to check, if everything is in place: 

vim Gemfile.local

[...]
gem 'rmagick'

sudo bundle install

Probably you need to manually create a local Gemfile (see next section about Postgresql).

Mysql

This is the only thing you should do: 

gem install mysql2

Postgres

If you are using postgresql for database server:

Install development files (gcc is needed for compiling pg) : 

apt-get install build-essential bison openssl libreadline6 libreadline6-dev curl git-core zlib1g zlib1g-dev libssl-dev libyaml-dev libxml2-dev autoconf libc6-dev ncurses-dev automake libtool

On a 64bit environment there could be come the following error: 

/usr/include/ruby-2.0.0/ruby/ruby.h:24:25: fatal error: ruby/config.h: No such file or directory

Then you have to symlink the library path this way: 

mkdir /usr/include/i386-linux-gnu/
ln -s /usr/include/ruby-2.0.0 /usr/include/i386-linux-gnu/ruby-2.0.0


Install the Postgres PPA for the development files: 

http://www.postgresql.org/download/linux/ubuntu/

And the development files for your installed postgresql version: 

apt-get install postgresql-server-dev-PG_VERSION
# e.g.: postgresql-server-dev-9.3
apt-get install libdbd-pg-ruby
apt-get install ruby2.0-dev:i386

Create a local Gemfile: 

cd /usr/share/redmine
vim Gemfile.local

# Gemfile.local
gem 'activerecord-postgresql-adapter'
gem 'pg'

Then the add the following gems 

cd /usr/share/redmine
gem install pg
gem install activerecord-postgresql-adapter
bundle install

Apache 2.4

In your virtual hosts section include this: 


[...] 

ServerAlias projects.yourserver.com

#  If you updated to ruby 2.1.0 - also for others!
SetEnv GEM_HOME /usr/lib/ruby/gems/2.1.0

DocumentRoot /usr/share/redmine/public
 <Directory /usr/share/redmine/public>
   Options -MultiViews
   AllowOverride All
   Require all granted
</Directory>

 # Possible values include: debug, info, notice, warn, error, crit,
 # alert, emerg.
 LogLevel warn

 CustomLog /var/log/apache2/access.log combined
 ErrorLog /var/log/apache2/error.log

 ServerSignature Off

 [...]

Redmine 2.x and Ubuntu 12.04

Man problems mentioned are solved using a recent version of redmine.

Together with [Zentyal] you can use [LDAP] to authenticate users of a Samba4 domain.

[ UPDATE --Apos (talk) 15:54, 16 September 2015 (CEST) ] Do not use this ppa with Ubuntu 14.04 LTS because it updates Redmine from the stable 2.4.2 version to the 2.5.x which - my case - produced trouble, trouble, trouble.

Use the ppa for redmine on ubuntu 12.04 LTS:

Then use this guide:

Plugins

  1. Create the directory /usr/share/redmine/plugins
  2. Put plugins into this directory
  3. run the as explaned in http://www.redmine.org/projects/redmine/wiki/Plugins
rake redmine:plugins:migrate RAILS_ENV=production

LDAP with Zentyal

--Apos (talk) 10:27, 2 November 2013 (CET)

>>> See LDAP with Zentyal 3.2.

  • Redmine LDAP settings

Redmine 1.x on Debian Squeeze (6.x)

Redmine Bugs

width of attached images

vim ./public/stylesheets/application.css +740
#content .wiki img {
           max-width: 98%;
}

Possible other solutions:

Fixing a bug using svn

vim /usr/share/redmine/lib/redmine/scm/adapters/subversion_adapter.rb
# SVN executable name
-        SVN_BIN = "svn"
+        SVN_BIN = "/usr/bin/svn"

Installation mit Postgresql und Apache2 mod_passenger

Prerequisites:

  • postgresql server (8.4) installation
  • apache2 with virtual hosts

Debian will configure database and permissions automatically! Be prepared to have an database password for postgres handy.

Redmine 1.1.x

apt-get install redmine redmine-pgsql ruby-git libapache2-mod-passenger librmagick-ruby

Update to the most recent version 

aptitude -t squeeze-backports install redmine

Redmine 1.3.x

Or via testing: 

root@server:~#  vim /etc/apt/sources.list.d/testing.list

deb http://yourmirror/debian/mirror/ testing main non-free contrib
deb http://security.debian.org/ testing/updates main contrib non-free
deb-src http://security.debian.org/ testing/updates main contrib non-free

and 

root@server:~# vim /etc/apt/preferences.d/pinning 

Package: *
Pin: release n=squeeze
Pin-Priority: 900

Package: *
Pin: release a=testing
Pin-Priority: 80

then 

root@server:~# apt-get update &&  aptitude -t testing install redmine redmine-pgsql ruby-git libapache2-mod-passenger librmagick-ruby


Trouble after install

Error with bundler

cd /usr/share/redmine
gem install bundler

Error with Gemfile.lock

Create the file: 

cd /usr/share/redmine
touch Gemfile.lock
chmod 664 Gemfile.lock

And fill it with: 

GEM
 remote: https://rubygems.org/
 specs:

PLATFORMS
 ruby

DEPENDENCIES

Anyway

Alter permissions.

This is NOT necessary in ubuntu 12.04 and redmine 2.x. 

cd /usr/share/redmine/
mkdir files
chown -R www-data:www-data public
chown -R www-data:www-data files
chmod 777 files

Apache virtual host

SERVERIP="1.2.3.4"
MAIL="webmaster@mydomain.com"
DOMAIN="projects.example.com"
DOCPATH="/usr/share/redmine/public"
SSLPATH="/var/customers/ssl"
CUSTOMER="companyname"
CHAINFILE="/where/is/ssl/CAcert_chain.pem"

cat << EOF > ${DOMAIN}.conf
<VirtualHost ${SERVERIP}:443>
  ServerAdmin webmaster@${DOMAIN}
  ServerName  www.${DOMAIN}
  ServerAlias ${DOMAIN}

  DocumentRoot ${DOCPATH}
  <Directory ${DOCPATH}>
    Options -MultiViews
    allow from all
  </Directory>
  # Possible values include: debug, info, notice, warn, error, crit,
  # alert, emerg.
  LogLevel warn

  CustomLog /var/log/apache2/access.log combined
  ErrorLog /var/log/apache2/error.log

  ServerSignature Off

  SSLEngine on
  SSLCertificateFile ${SSLPATH}/${CUSTOMER}/${DOMAIN}.cert
  SSLCertificateKeyFile ${SSLPATH}/${CUSTOMER}/${DOMAIN}.key
  SSLCertificateChainFile ${CHAINFILE}

</VirtualHost>
EOF

Project Migration

Actually it is not possible to migrate projects from one to another Redmine instance. But there are efforts: Decussion here: http://www.redmine.org/issues/3647

Dealing with Plugins

Mylyn Connector for Eclipse and Redmine Plugin

  • General information can be found here - also for newer Redmine versions: [1]
  • I am using currently the Redmine Plugin from here: [2] with Redmine 3.2 and the updated Eclipse Mylin Plugin from here: [3] with Eclipse 4.4 (Luna). For the latter use the LATEST stable release [4]!

I could NOT get this working with Eclipse 4.5 (Mars) yet.

Old and not working any more for newer versions of Eclipse (> Luna / 4.4) and Redmine ( 2.x and older):

1. Install the Redmine Mylin Connector using the update site:

2. Install the Redmine Plugin 

cd /usr/share/redmine
ruby script/plugin install git://redmin-mylyncon.git.sourceforge.net/gitroot/redmin-mylyncon/redmine-mylyn-connector
# Update
# ruby script/plugin install --force git://redmin-mylyncon.git.sourceforge.net/gitroot/redmin-mylyncon/redmine-mylyn-connector

Timesheet Extension

Download the files (searching the „Downloads“ link) onto the server with 

links2 https://github.com/nicStuff/redmine_timesheet_extensions

AFTER installation of plugins

Update the database 

cd /usr/share/redmine
rake db:migrate_plugins RAILS_ENV=production

and for newer version of Redmine (> 2.2) 

rake redmine:plugins:migrate RAILS_ENV=production

If you have problems use 

rake db:migrate_plugins RAILS_ENV=production --trace

Some Basic Plugins

RedmineCRM - open source and commercial plugins

This are absolute MUST-HAVE plugins which are partly free, all open source (!!!) and very pricy, when you will decide to buy some of them.

Support them, they give a lot back to the community through their development of free plugins!

This includes e.g.:

  • Contacts (CRM)
  • Finance (Invoices, Expenses)
  • Nice Themes
  • ...

Not pitfalls, no high prices, no contracts:

Show project as list items

Redmines default view of the (sub)projects is a very ugly, simple comma separated list on the first page. Not very intuitive dealing. The following deals with this:

"Project Show is a Redmine plugin to show how simple it is to override default views. This partial one displays the sub-projects in a more readable list instead of the comma separated one. Doing it within a plugin is better than changing the core as when you go thru updates to Redmine you won't have to go back and make the changes again. I got tired of having to do this for multiple installs and versions so I think the plugin is a better idea."

Tweaking the project list

Projects list with blackjack and other features for Redmine and ChiliProject

This plugin gives a nice view to the projects page, uncluttering all the unnecessary stuff (like the project description).

Defining custom landing page

When then user opens a redmine project, he will be routed to the landing page which defaults to the Overview. This is not always intended, e. g. when a Wiki is established.

Solution: Use the "redmine_my_page" plugin or use the various methods altering the /config/route.rb file

Customizing "my page"

The Plugins aims at providing some user specific customization in redmine.

  • The user can select Custom Queries defined in his projects to be listed in My Page.
  • User can list all his Custom Queries created across all his projects in a single page.
  • The user can select his selected or filtered activities.
  • The plugin also provides the default page to be shown after login into the system. This can be the My Page or any Projects Issue List or Filtered Issue List.

Git:

Clipboard image paste

Works with pure JavaScript ;-)

Also see:

All commercial Plugins from easyredmine

Working for a company? Looking for a bigger scope? Probably for more than a couple of employees?

(If you are a stand alone man or woman, better stay with RedmineCRM - its much cheeper ...)

Ultraviolet Syntax Highlighting

* http://www.redmine.org/plugins/redmine_ultraviolet

DocPu, Document publishing plugin

* http://www.redmine.org/plugins/redmine_doc_pu

Requires: 

gem install RedCloth
apt-get install tetex-base texlive-latex-extra

Hudson

* http://www.redmine.org/plugins/t-ando_redmine_hudson

SVN integration and https

See SVN integration with apache and https


Security

Fail2ban

SSH Tunnel for non public installations

If you like to get access to a certain non public redmine installation you should use an ssh tunnel.

  1. Create an virtual host with listens e. g. on port 444
  2. Apache: don't forget to add a Listen directive in ports.conf for port 444 !

Once you establish the following tunnel you are able to reach your redmine installation in your browser through e.g. https://localhost:9001 

sudo  su -c "ssh -L 9001:domain.tld:444 user@domain.tld"

Troubeshooting

Test your redmine installation

Taken from: http://www.redmine.org/projects/redmine/wiki/HowTo_Install_Redmine_on_Debian_8_with_Apache2-Passenger#24-Test-Redmine

Replace $IP with your external IP: 

bundle exec ruby bin/rails server -b $IP webrick -e production

Open your browser and visit http://$IP:3000

Uninstall plugins

The trick is using VERSION=0 with the plugins migrate command: 

cd /srv/www/myredmine # or cd /usr/share/redmine
rake redmine:plugins:migrate NAME=redmine_plugin_name VERSION=0 RAILS_ENV=production
service apache2 reload

Website won't come up

Look at your apache logfile: 

tail -f /var/log/apache2/error.log

In my case I copied over the databae.yml, but did not pay attention to the rights: 

[!] There was an error parsing `Gemfile`: Permission denied @ rb_sysopen - /srv/www/projects.blue-it.org/config/database.yml. Bundler cannot continue.

chmod 644 /srv/www/redmine/config.yml

Thats it ...

Gemfile.lock - Site won't start

Accessing the Webpage you will get: 

There was an error while trying to write to Gemfile.lock. It is likely that 
you need to allow write permissions for the file at path:

Solution: 

sudo apt-get install bundler #Installs ruby-dev, which is ruby1.9-dev
sudo touch /usr/share/redmine/Gemfile.lock
sudo chown www-data:www-data /usr/share/redmine/Gemfile.lock

dpkg-reconfigure redmine witch cache cleaning

dpkg-reconfigure -plow redmine

Migration of plugins

New in 2.0.0 the plugins/engines is removed in 2.0.0. 

rake redmine:plugins:migrate RAILS_ENV=production --trace
rake db:migrate_plugins RAILS_ENV=production --trace

Mysql

If you get an error like 

No such file or directory - connect(2) for /tmp/mysql.sock (Errno::ENOENT)

Or 

database configuration specifies nonexistent mysql adapter (ActiveRecord::AdapterNotFound)

it is likely that your mysl connection cannot be established due to a gem error:

Install the development files for mysql 

apt-get install libmysqlclient-dev

Uninstall any old mysql gems: 

gem uninstall ruby-mysql
gem uninstall mysql
gem uninstall activerecord-mysql-adapter

Use the new mysql2 adapter: 

gem install mysql2

and remove the lines from your Gemfile.local

Wrong version of active...

If using Redmine 2.x and 

bundle show | grep active

shows 

activemodel 4.2.1

then you have to downgrade these: 

vim Gemfile.local 

gem 'activerecord-mysql-adapter'
gem 'activemodel', '3.2.15'
gem 'actionpack', '3.2.15'
gem 'activesupport', '3.2.15'
gem 'ruby-mysql'

and e.g. 

bundle update activemodel


Error: 

gem install activemodel -v 3.2.14
gem install actionpack -v 3.2.14
gem install activeresource -v 3.2.14
Retrieved from "https://wiki.blue-it.org/index.php?title=Redmine&oldid=6396"