Setting up Redmine on FreeBSD : phaq : http://phaq.phunsites.net

This page was exported from phaq [ http://phaq.phunsites.net ]
Export date: Thu Apr 25 2:18:09 2024 / +0000 GMT

"Redmine is a flexible project management web application. Written using Ruby on Rails framework, it is cross-platform and cross-database." (redmine.org)

Here's my short primer on setting up Redmine on FreeBSD.

In my case, I just wanted a rather simplistic and stripped-down environment, which was the reason to choose Redmine.
While it can perfectly integrate with Apache, Nginx and other web-servers, I preferred to use the minimalistic "thin" web-server.
I do as well use self-compiled port in favor to binary packages. Feel free to use binary packages if you like ;-)

Installing the software

Redmine requires a database server. Either MySQL or PostgreSQL or sqlite.
If chose to use MySQL and installed it from the ports using defaults:



[root@localhost ~] cd /usr/ports/databases/mysql51-server; make build install

Then install Redmine from /usr/ports/www/redmine.



[root@localhost ~] cd /usr/ports/www/redmine; WITHOUT_X11=true make config build install

It's important to fire up the "config dialog" to include the "thin" web-server:

Enable service configuration

Enable the services in your /etc/rc.conf.



mysql_enable="YES"                      # enable MySQL server

redmine_enable="YES"                    # enable redmine server

redmine_flags="-a 0.0.0.0 -p 3000 -e production --ssl --ssl-key-file=/usr/local/www/redmine/config/server.key --ssl-cert-file=/usr/local/www/redmine/config/server.crt"

I choose to enable SSL in the configuration above. If you don't need SSL, then change the "redmine_flags" line to read as follows:



redmine_flags="-a 0.0.0.0 -p 3000 -e production"

Prepare MySQL

Now start mysql server:



[root@localhost ~] /usr/local/etc/rc.d/mysql-server start

Fire up the mysql console.
If this happens to be the first time you use MySQL, then you won't have a password yet. It may be a good idea then, to first assign new passwords and remove the default database stuff. Do this



delete from user where user='';

delete from db where user='';

drop database test;

flush privileges;

Now create the database and user for use with Redmine:



create database redmine character set utf8;

create database redmine_devel;

create database redmine_test;

create user 'redmine'@'localhost' identified by 'A_secRET_passw0RD';

grant all privileges on redmine.* to 'redmine'@'localhost';

grant all privileges on redmine_devel.* to 'redmine'@'localhost';

grant all privileges on redmine_test.* to 'redmine'@'localhost';

Prepare Redmine

For Redmine you'll need to edit some configuration files at /usr/local/www/redmine/config first.
First copy the "database.yml.example" file to "database.yml".



[root@localhost ~]# cd /usr/local/www/redmine/config

[root@locahost /data/local/www/redmine/config]# cp database.yml.example database.yml

Now edit the "database.yml" file to your correct database settings:



production:

  adapter: mysql

  database: redmine

  host: localhost

  username: redmine

  password: A_secRET_passw0RD

  encoding: utf8



development:

  adapter: mysql

  database: redmine_development

  host: localhost

  username: redmine

  password: A_secRET_passw0RD

  encoding: utf8



# Warning: The database defined as "test" will be erased and

# re-generated from your development database when you run "rake".

# Do not set this db to the same as development or production.

test:

  adapter: mysql

  database: redmine_test

  host: localhost

  username: redmine

  password: A_secRET_passw0RD

  encoding: utf8

Now create the session store and import the initial database as follows:



[root@localhost /data/local/www/redmine/config]# rake generate_session_store

[root@localhost /data/local/www/redmine/config]# RAILS_ENV=production rake db:migrate

To enable mail processing, you need to copy "email.yml.example" to "email.yml":



[root@locahost /data/local/www/redmine/config]# cp email.yml.example email.yml

Then edit "email.yml" to your proper email settings. The following example is for SMTP delivery through an external host:



production:

  delivery_method: :smtp

  smtp_settings:

    address: SMTP.DOMAIN.TLD

    port: 25

    domain: SMTP.DOMAIN.TLD

    authentication: :login

    user_name: "smtp_user_name"

    password: "some_password"



development:

  delivery_method: :smtp

  smtp_settings:

    address: SMTP.DOMAIN.TLD

    port: 25

    domain: SMTP.DOMAIN.TLD

    authentication: :login

    user_name: "smtp_user_name"

    password: "some_password"

Optional: Enable SSL mode

I enabled SSL for the "thin" web-server in /etc/rc.conf. If you choose to not use SSL, skip this step.

To enable SSL, you need to create the SSL private key and a certificate.
I'm giving just the command list here, as this procedure is otherwise very well documented over there at the mod_ssl FAQ.



openssl genrsa -des3 -out server.key.cryped 1024

openssl rsa -in server.key.crypted -out server.key

openssl req -new -key server.key -out server.csr

openssl req -new -x509 -days 365 -key server.key -out server.crt

The above procedure would essentially create a password-protected key (step 1), which would then get the password removed (step 2). I'd then create a signing request in the 3rd step and have a self-signed certificate created (last command).
The removal of the password is essential to start the web-server without prompting for a password.

Now, there was just one little cave-at I came along. On my setup, Redmine would not properly run in SSL mode in some cases create redirect url containing http:// instead of https://.
I suspect this is a problem caused by the "thin" web-server, which would not properly state that it runs in SSL mode to the application. Obviously, wenn running "thin" in SSL mode, it would no longer word in "http plain" mode, so this causes some errors.

For example, when logging on to your host using https://HOSTNAME:3000, you'd get redirected to http://HOSTNAME:3000/login?back_url=http://HOSTNAME:3000".
Now, as this obviously won't work, there's a little change required in the "/usr/local/www/redmine/vendor/rails/actionpack/lib/action_controller/request.rb" file.

Look out for this text block:



    # Is this an SSL request?

    def ssl?

      @env['HTTPS'] == 'on' || @env['HTTP_X_FORWARDED_PROTO'] == 'https'

    end

Then change it to look like this:



    # Is this an SSL request?

    def ssl?

        true

    end

This will force Redmine into thinking it's permanently SSL enabled, thus it will always generate proper https:// URLs.
This particular issue would propably not come up when using Apache or Nginx in SSL forwarding mode.

Start using Redmine

Now you're basically done. Start accessing Redmine through https://YOURHOSTNAME:3000 (or http://YOURHOSTNAME:3000, in case you left SSL disabled).

And don't forget to change your default username/password settings upon first login.

I recommed the Redmine User's Guide for further reading ;-)