BitNami Redmine legacy

How to start/stop the servers?

The Stacks include a graphical tool to manage the servers easily. You can find the "manager-windows.exe", "manager-osx" or "manager-linux" tool in your installation directory. Using this tool, you can Start, Stop or Restart the servers and check the log files. You can click on the icon to start it.

On Windows: You can also start the Manager tool from shortcuts: Start -> Program Files -> BitNami Stack -> Manager tool

If you prefer, you can use the "ctlscript.sh" utility from the command line. This script is in the installation directory.

On OS X: You can start the Manager tool from the installation directory or you can use the "ctlscript.sh" utility from a Terminal.

host:~ user$ cd /Applications/application-version
host:~ user$ ./ctlscript.sh start

On Linux:

$ cd ~/applicaton-version
$ ./ctlscript.sh start

How to change the default URL?

If you want to change Redmine to the root url you should follow the next next section. In this section you can see how to replace the URL "/redmine" with "/new_url".

It is necessary to modify the Apache configuration. Edit "installdir/apps/redmine/conf/redmine.conf"  the file to modify the "/redmine" setting:

ProxyPass /redmine balancer://redminecluster
ProxyPassReverse /redmine balancer://redminecluster

<Proxy balancer://redminecluster>
  BalancerMember http://127.0.0.1:3001/redmine
  BalancerMember http://127.0.0.1:3002/redmine
</Proxy>

  On Linux and OS X, you should modify the installdir/apps/redmine/config/mongrel_cluster.yml file and change the prefix option. Then restart the servers.

On Windows, you should modify the "installdir/apps/redmine/scripts/serviceinstall.bat" and change the prefix entry "--prefix /redmine". Then run the following command from a command prompt with Admin privileges:

> cd “C:\Program Files\BitNami Redmine Stack\apps\redmine\scripts”
> serviceinstall.bat UNINSTALL
> serviceinstall.bat INSTALL

How to change the default URL to the root?

You can change the "installdir/apps/redmine/conf/redmine.conf" file to modify the "/redmine" url to the root url. You can find below a configuration example. Please take into account that your current redmine.conf file may be a little bit different. Add a virtual host entry if it is missing. The number of the balancer members depends on the number of mongrels running. We use only one mongrel on port 3001 by default for the BitNami Cloud Hosting. Please remove the others like 3002 in such a case.

<VirtualHost *:80>
  ServerAdmin example.com
  ServerName example.com
  ServerAlias server
  ErrorLog "logs/error.log" 
  CustomLog "logs/access.log" combined
 # this not only blocks access to .svn directories, but makes it                
 # appear as though they aren't even there, not just that they are              
 # forbidden                                                                    
 <DirectoryMatch "^/.*/\.svn/">
    ErrorDocument 403 /404.html
    Order allow,deny
    Deny from all
    Satisfy All
  </DirectoryMatch>
  # This passes through remote_user to mongrel                                  
  RewriteEngine On
  # Redirect non-static requests to cluster                                     
  RewriteCond %{DOCUMENT_ROOT}/%{REQUEST_FILENAME} !-f
  RewriteRule ^/(.*)$ balancer://redminecluster%{REQUEST_URI} [P,QSA,L]
</VirtualHost>

#ProxyPass / balancer://redminecluster
#ProxyPassReverse / balancer://redminecluster

<Proxy balancer://redminecluster>
  BalancerMember http://127.0.0.1:3001
  BalancerMember http://127.0.0.1:3002
  # The number of balancer members depends on the number of mongrels running
  # We use only one mongrel on port 3001 by default for the BitNami Cloud Hosting
  # Please remove the others like 3002 above in such a case.
</Proxy>

It is also necessary to edit the prefix in the Redmine application.

  On Linux and OS X, you should modify the installdir/apps/redmine/config/mongrel_cluster.yml file and remove prefix option.

On Windows, you should modify the "installdir/apps/redmine/scripts/serviceinstall.bat" and remove the prefix entry "--prefix /redmine". Then run the following command from a command prompt with Admin privileges:

> cd “C:\Program Files\BitNami Redmine Stack\apps\redmine\scripts”
> serviceinstall.bat UNINSTALL
> serviceinstall.bat INSTALL

How to create a full backup of Redmine?

Because BitNami stacks are self-contained, the simplest option for performing your backups is to copy or compress the BitNami Stack installation directory. To do so in a safe manner, you will need to stop all servers, so this method may not be appropriate if you have people accessing the application continously.

On Linux and OS X:

$ cd installdir
$ ./ctlscript.sh stop
$ cp -r installdir application-backup

Or you can create a tarball:

$ tar -czvf application-backup.tar.gz installdir

Or a zip file:

$ zip -r application-backup.zip installdir/*

To restore this backup you only need to uncompress the backup in the same location. It is important to use the same path that was used when the stack was originally installed.

For example if you have a backup in a Red Hat machine, you can copy it to an Ubuntu Linux machine (a different distro!) in the same location. Then start the servers and that’s all.

$ cd installdir
$ ./ctlscript.sh start

You just need to be carefull to keep the same permissions for the files and folders. If you installed as root make sure that in the new machine you copy the files also as root. And this case, if you are also moving MySQL or PostgreSQL, you will need to create those users in the new machine (if they don't exist yet).

On Windows:

On Windows, you should follow the same process. Stop the servers using the shortcuts and copy the whole installation directory. To restore the system, copy the directory to a different Windows machine in the same location and follow these steps from a command prompt:

$ cd installdir
$ serviceinstall.bat INSTALL

You can access your BitNami Application at the usual URL.

If you want to create only a database backup, check the following link for MySQL /Components/MySQL#How_to_create_a_database_backup or for PostgreSQL

How to upgrade Redmine?

It is strongly recommended that you create a backup before starting the update process. If you have important data, it is advisable that you create and try to restore a backup to ensure that everything works properly.

There are two different ways to upgrade your application.

1. If you want to upgrade the application and all Stack components PHP, Ruby, MySQL, Apache… You can follow the steps described at How to upgrade the full Stack migrating the data?
2. In case you only want to upgrade the application code without modifying any other Stack components. You can find below the steps to upgrade onlye the Redmine application.

First, you have to download the new Redmine version. You can choose to download the latest stable version of Redmine from RubyForge or you can download the latest repository version. In that case, you can use the Subversion tool included in the Stack:

$ svn co svn://rubyforge.org/var/svn/redmine/trunk redmine

Once you have downloaded the newer Redmine version, you need to stop the servers and rename the old redmine folder:

$ cd installdir
$ ./ctlscript.sh stop
$ mv apps/redmine apps/redmine-old

On Windows:

$ cd installdir
$ servicerun.bat STOP
$ cd apps
$ rename redmine redmine-old

Move the new redmine version to the apps folder and name it “redmine” and then copy the following folders and files from the old copy to the new one: “scripts”, “conf” and “files” folders and all the yml files inside “config”. It is also necessary to create the “installdir/apps/redmine/tmp/pids” folder.

$ cd installdir/apps
$ cp -r redmine-old/scripts redmine-old/conf redmine-old/files redmine-old/files redmine/
$ cp redmine-old/config/email.yml redmine/config/
$ cp redmine-old/config/database.yml redmine/config/
$ mkdir redmine/tmp/pids

Copy your base configuration settings-file config/configuration.yml into the new config directory. If you are upgrading from a version older than 1.2.0, copy your email settings from your "config/email.yml" into the new "config/configuration.yml" file. This can be created by copying the "configuration.yml.example" file.

If you have installed plugins in the previous version, copy the folders from "vendor/plugins" directory into new installation directory.

If you want to keep using the currently installed Rails version, you should comment out the following line in “installdir/apps/redmine/config/environment.rb” file

RAILS_GEM_VERSION = 'x.x.x' unless defined? RAILS_GEM_VERSION

You also need to copy session store keys to the new redmine location:

$ cd installdir/apps
$ cp redmine-old/config/initializers/session_store.rb redmine/config/initializers

In case this file doesn’t exist in your old installation or you get an error message about session key, you may need to run this instead:

$ cd installdir/apps/redmine
$ rake config/initializers/session_store.rb

It is also necessary to update the database to merge the changes in the new version. Remember to start the “use_redmine” script or the shortcut on Windows before typing the following commands:

$ cd installdir/apps/redmine
$ rake db:migrate RAILS_ENV="production"

If you have installed plugins you should also run these commands:

$ rake db:migrate:upgrade_plugin_migrations RAILS_ENV="production"
$ rake db:migrate_plugins RAILS_ENV="production"

Finally you should clean the cache and the sessions:

$ rake tmp:cache:clear
$ rake tmp:sessions:clear

Restart the servers and you can access to your new Redmine.

How to install a plugin on Redmine?

Before installing a plugin make sure that the plugin is compatible with your redmine version. If you get the plugin from the Redmine Plugin Directory  you can check the "Compatible with:" field for each plugin.

1. Download the plugin and copy your plugin directory into installdir/apps/redmine/vendor/plugins.
2. If the plugin requires a migration, run the following command to upgrade your database (make a db backup before). You should run this command from a use_redmine console:
   
   $ cd installdir
   $ ./use_redmine
   $ cd apps/redmine
   $ rake db:migrate:plugins RAILS_ENV=production
    
3. Restart Redmine application.

How to install the Redmine Dropbox plugin?

The Redmine Dropbox plugin allows to storage proyect files on your Dropbox account http://www.redmine.org/plugins/redmine_drop_box

The following steps are generic for any BitNami Redmine installation. If you are using a Virtual Machine or AMI, you should replace the "installdir" with "/opt/bitnami" folder.

Install the required gems:

$ cd installdir
$ ./use_redmine
$ sudo gem install oauth multipart-post mechanize shoulda

Add the gems into the Redmine Gemfile, "/installdir/apps/redmine/htdocs/Gemfile":

gem 'oauth'
gem 'multipart-post'
gem 'mechanize'
gem 'shoulda'

Download the plugin and uncompress it in the /installdir/apps/redmine/vendor/plugins folder.

$ unzip zuinqstudio_redmine_drop_box*.zip -d /installdir/apps/redmine/vendor/plugins

Run the migrate command to install the plugin:

$ cd /installdir/apps/redmine
$ bundle install
$ rake db:migrate:plugins RAILS_ENV=production

That's all, you can configure your DropBox account in the Redmine Administration panel -> Plugins.

How to install the Redmine Ultraviolet plugin?

Some of plugins require to be compiled, for instance, the Redmine Ultraviolet Syntax Highlighting plugin (http://www.redmine.org/plugins/redmine_ultraviolet). It is necessary that you machine have the compilation tools (gcc, make and their dependencies). If you are running a Virtual Appliance or an AMI, you should do the following:

$ sudo apt-get install gcc make
$ sudo apt-get install libonig-dev
$ sudo gem install ultraviolet

Now you can download the plugin and install it in Redmine application

$ sudo git clone git://github.com/epitron/redmine_ultraviolet.git
$ sudo mv redmine_ultraviolet /installdir/apps/redmine/vendor/plugins
$ sudo /installdir/ctlscript.sh restart redmine

That's all, you can enable any Ultraviolet theme in the administrator account.

How to configure the email settings of Redmine?

You can configure the email settings in the "installdir/apps/redmine/config/configuration.yml" file. In older versions you should use the "installdir/apps/redmine/config/email.yml" file. The sample configuration for GMail account is shown below:

production:
  delivery_method: :smtp
  smtp_settings:
    tls: true
    address: "smtp.gmail.com"
    port: 587
    domain: "smtp.gmail.com"
    authentication: :plain
    user_name: "your_email@gmail.com"
    password: "your_password"
    enable_starttls_auto: true

Please make sure you have the enable_starttls_auto property setotherwise the error message "(530 5.7.0 Must issue a STARTTLS command first ..." is shown.

Once the email.yml file is changed, you need to restart the mongrel process:

$ sudo installdir/ctlscript.sh restart redmine

You can also change the link that appears in the email. Go to Administration -> Settings -> General -> Host name and path and you can write your domain name and port.

You can also find more info at the Redmine wiki page and Redmine blog.

How to enable SSL?

You can see how to configure Apache to enable SSL connections at How to enable SSL to access through https? In addition to this, for Redmine it is necessary to add the "RequestHeader" option in the /installdir/apps/redmine/conf/redmine.conf file:

<Proxy balancer://redminecluster
  RequestHeader set X_FORWARDED_PROTO ‘https’
  BalancerMember http://127.0.0.1:3001/redmine
  BalancerMember http://127.0.0.1:3002/redmine
</Proxy>

How to configure Redmine with Phusion Passenger

This is the default configuration for Redmine 2.0 or greater.

Make sure you have the Phussion Passenger enabled. Check if the following line is uncommented in Apache config file /installdir/apache2/con/httpd.conf:

Include conf/bitnami/passenger.conf

Assuming you have your application running in /application location, substitute the content of the file /installdir/apps/application/conf/application.conf with the following:

<VirtualHost *:80>
  RailsBaseURI /application
  <Directory /installdir/apache2/htdocs/application>
    Options -MultiViews
  </Directory>
</VirtualHost>

Then ssh to your machine and create a symbolic link:

sudo ln -s /installdir/apps/application/public /installdir/apache2/htdocs/application

(You should make sure that the 'public' and 'config' application folders and their parent directories are readable and executable by Apache).

Restart Apache server:

sudo /installdir/ctlscript.sh restart apache

How to change the default URL with Phussion Passenger

Please make sure you have the Phussion Passenger enabled (check the previous section for the details). Then substitute the content of the file /opt/bitnami/apps/application/conf/application.conf with the following:

<VirtualHost *:80>
  DocumentRoot /installdir/apps/application/public
  <Directory /installdir/apps/application/public/>
     Allow from all
     Options -MultiViews
  </Directory>
</VirtualHost>

Restart Apache server:

sudo /installdir/ctlscript.sh restart apache

How to see the Subversion repository from Redmine application or from web browser directly?

Redmine application itself lets to check the Repository changes and link to the number case. You only have to configure the Repository URL from the project settings.

SCM: Subversion
URL: http://your_repository
Login: repository_login
Password: repository_password

If you do not have any repository yet, you can create it manually. This guide describes how you can create a Subversion repository in your machine.

If you also want to see the repository directly from the web browser, you can configure Apache server to serve the repository. You can find the exact steps here.

How to configure Redmine for advanced integration with Git

Before starting this guide, take into account that this is not necessary to see the repository changes in the Redmine application. If you only want to see the repository changes and link to the issues, it is only necessary to configure the project repository: Project -> Settings -> Repository -> URL and Control Version System.

This Redmine advanced configuration is to use the users created in the Redmine application for the Git repository. For example, you can create new users from the Redmine application which will be the same that be able to "push" changes in the Git project repository. Since 1.1.3-1 version, Redmine Stack ships all required modules for this configuration. Notice that if you are using Virtual Appliances or AMIs the installdir variable is "/opt/bitnami" and your_user is "bitnami". It could be necessary to use the "sudo" command if the Stack was installed by the root user. This guide is based on the Felix Schäfer guide posted at the Redmine Wiki.

1. Create a Git repository. I will use "projects" to a folder where the repositories are going to be created. This directory should have write privileges for the "daemon" user. 

$ cd installdir
$ sudo mkdir projects
$ sudo mkdir projects/test
$ cd projects/test
$ sudo git init --bare
$ sudo chown -R your_user:daemon projects

2. Download the Grack project from GitHub: 

$ cd /opt/bitnami/apache2/htdocs/
$ git clone http://github.com/schacon/grack.git
$ chown your_user:daemon grack

Edit the "grack/config.ru" file to specify where is your Git project:

$LOAD_PATH.unshift File.expand_path(File.dirname(__FILE__) + '/lib')

use Rack::ShowExceptions
require 'git_http'

config = {
  :project_root => "/installdir/projects/",
  :git_path => '/installdir/git/bin/git',
  :upload_pack => true,
  :receive_pack => true,
}

run GitHttp::App.new(config)

$ cd /opt/bitnami/apache2/htdocs/grack
$ rackup --host 127.0.0.1 -p 8080 config.ru

3.a. Then you can try to clone the repository and push changes from a different machine.

$ cd /tmp/
$ git clone http://IP_MACHINE:8080/test
$ cd test
$ echo "test" > test_file
$ git add test_file
$ git commit -m "test" test_file
$ git push origin master

And you can see something similar to the following:

Counting objects: 3, done.
Writing objects: 100% (3/3), 200 bytes, done.
Total 3 (delta 0), reused 0 (delta 0)
To http://IP_MACHINE:8080/test
* [new branch]      master -> master

4. You can now stop the Grack server and configue Apache with Passenger. It is necessary to create two directories in the grack folder:

$ mkdir /installdir/apache2/htdocs/grack/public
$ mkdir /installdir/apache2/htdocs/grack/tmp

Edit the /installdir/apache2/conf/httpd.conf and add the following (notice that versions could be different)

...
LoadModule passenger_module /installdir/ruby/lib/ruby/gems/1.8/gems/passenger-2.2.11/ext/apache2/mod_passenger.so
PassengerRoot /installdir/ruby/lib/ruby/gems/1.8/gems/passenger-2.2.11
PassengerRuby /installdir/ruby/bin/ruby
...
 

<VirtualHost *:80>
     DocumentRoot "/installdir/apache2/htdocs/grack/public"
    <Directory "/installdir/apache2/htdocs/grack/public">
         Options None
         AllowOverride None
         Order allow,deny
         Allow from all
     </Directory> 
 </VirtualHost>

$ cd /tmp
$ wget http://www.redmine.org/attachments/5989/0001-merged-LeeF-s-patch-with-Michael-Fox-s-security-fix-redminetrunk.patch
$ cd /installdir/apps/redmine/extra/svn/
$ sudo mv /tmp/*.patch .
$ sudo patch -p0 < *.patch

I have a problem with line 487 in the "Redmine.pm" file. You can comment this line if you do not use the "example.git" name for your repository.

Once you have fixed the Redmine.pm to support Git's smart HTTP protocol, you should copy in the appropiate perl folder.

$ sudo cp Redmine.pm /installdir/perl/lib/site_perl/5.8.8/i686_linux/Apache/

6. Enable the perl module in httpd.conf adding the following line.

LoadModule perl_module modules/mod_perl.so

7. Finally add the following configuration in your already created VirtualHost in the step 4. The redmine_db_user and the redmine_db_password credentials you can get from the "installdir/apps/redmine/config/database.yml" file

<VirtualHost *:80>	
     DocumentRoot "/installdir/apache2/htdocs/grack/public"
     <Directory "/installdir/apache2/htdocs/grack/public">
        Options None
        AllowOverride None
        Order allow,deny
        Allow from all
     </Directory>
     
    PerlLoadModule Apache::Redmine
    <Directory "/installdir/apache2/htdocs/grack/public">
        Options None
        AllowOverride None
        Order allow,deny
        Allow from all
     </Directory>
     
     <Location "/">
       AuthType Basic
       AuthName "Redmine git repositories"
       Require valid-user
       
       PerlAccessHandler Apache::Authn::Redmine::access_handler
       PerlAuthenHandler Apache::Authn::Redmine::authen_handler
       RedmineDSN "DBI:mysql:database=bitnami_redmine;host=localhost;mysql_socket=/installdir/mysql/tmp/mysql.sock"
       RedmineDbUser "redmine_db_user"
       RedmineDbPass "redmine_db_password"
       RedmineGitSmartHttp yes
     </Location>
</VirtualHost>

You can now restart Apache and create the Project "test" in the Redmine application. Specify the path to the repository (i.e. /opt/bitnami/projects/test) and add a user as a Developer to this project. Now everything is ready to the created user be able to develop in the "test" repository using the same password that he has to access to the Redmine application. You can try the basic approach to clone and "push" a change in the repository that you did in the 3.a step.

How to configure Redmine for advanced integration with Subversion

Before starting this guide, take into account that this is not necessary to see the repository changes in the Redmine application. If you only want to see the repository changes and link to the issues, it is only necessary to configure the project repository: Project -> Settings -> Repository -> URL and Control Version System.

This Redmine configuration is for automatic repository creation and rights management. Since 1.1.3-1 version, Redmine Stack ships all required modules for this configuration. Notice that if you are using Virtual Appliances or AMIs the installdir variable is "/opt/bitnami". It could be necessary to use the "sudo" command if the Stack was installed by the root user.

• Uncomment the following lines in Apache configuration file (httpd.conf):

LoadModule dav_svn_module modules/mod_dav_svn.so
...
LoadModule perl_module modules/mod_perl.so

• Copy the Redmine.pm file into the Perl modules folder:

$ cp installdir/apps/redmine/extra/svn/Redmine.pm installdir/perl/lib/site_perl/5.8.8/i686-linux/Apache/

• Create a folder for the repository, for instance:

$ mkdir installdir/repository
$ mkdir installdir/repository/svn
$ chown root:daemon                  [or "your_user:your_user" if you installed the Stack without root privileges]
$ chmod 0755 installdir/repository
$ chmod 0750 installdir/repository/svn

• Edit the installdir/apps/redmine/conf/redmine.conf file.

ProxyPass /redmine balancer://redminecluster
ProxyPassReverse /redmine balancer://redminecluster
ProxyPass /svn !

<Proxy balancer://redminecluster>
  BalancerMember http://127.0.0.1:3001/redmine
  RewriteCond %{REQUEST_URI} !/svn(/|$)
  
</Proxy>

  
PerlLoadModule Apache::Redmine
<Location /svn>
  DAV svn
  SVNParentPath "/installdir/repository/svn" 
  Order deny,allow
  Deny from all
  Satisfy any

  PerlAccessHandler Apache::Authn::Redmine::access_handler
  PerlAuthenHandler Apache::Authn::Redmine::authen_handler
  AuthType Basic
  AuthName "Redmine SVN Repository" 

  #read-only access   
  <Limit GET PROPFIND OPTIONS REPORT>
     Require valid-user
     Allow from all
     # Allow from another-ip
     Satisfy any
  </Limit>
  # write access
  <LimitExcept GET PROPFIND OPTIONS REPORT>
    Require valid-user
  </LimitExcept>

  ## for mysql
  RedmineDSN "DBI:mysql:database=bitnami_redmine;host=localhost;mysql_socket=/installdir/mysql/tmp/mysql.sock" 

  RedmineDbUser "bitnami" 
  RedmineDbPass "bitnami_database_password"    
  #You can find this value at /installdir/apps/redmine/config/database.yml
</Location>

• Restart the servers:

$ installdir/ctlscript.sh restart

• Log in the Redmine application as Administrator and go to "Settings" -> "Repositories" -> "Enable WS for repository management".
• Click on "Generate a key" and save it.
• Add the following line in the crontab. You can edit the crontab using the command "crontab -e"

*/2 * * * * installdir/ruby/bin/ruby installdir/apps/redmine/extra/svn/reposman.rb --redmine localhost/redmine --svn-dir installdir/repository/svn --owner root --group daemon --command="installdir/subversion/bin/svnadmin create --pre-1.6-compatible --fs-type fsfs" --url http://YOUR_PUBLIC_IP_ADDRESS/svn --key=YOUR_API_KEY --verbose >> /var/log/reposman.log 

• If you have configured Redmine to accress through SSL, you can specify "--redmine http://127.0.0.1:3001/redmine" in the previous crontab line.
• You can check that everything works properly creating a project from the Redmine application and checking the /var/log/reposman.log file.

Thanks to "Jedbifa" who posted a complete guide in the BitNami forums.

How to debug errors?

The Redmine log files are created in /installdir/apps/redmine/logs directory. You can check these files to see the exact error in the application.