Installing Redmine on a Debian Squeeze machine turned out to be bit challenging, especially for a person like me not closely associated with Ruby based development. The below blog post just explains what I did to get the nice setup of Redmine project management system along with Redmine-Backlogs plugin for managing agile, scrum tasks and sprint cycles. You may find it helpful to bring up a similar setup for your own consumption.
Redmine, nginx and passenger packages are custom built and are not installed from the official Debian repository. Please remember that you need to be a root/superuser in order to go further. Please assume that all the tasks have been performed as '
Final, installed system will have the following:
Basic system setup:
Optional, proxy configuration if you are behind any proxy:
Git configuration: Make sure we have added username and email as part of git setup.
Postgresql database configuration:
Redmine installation:
Now, it is the time to setup configuration.xml and database.xml files for Redmine.
Open and edit the configuration.yml to setup your default email server and other Redmine specific configuration as per your need. Consult a system administrator for proper values for email server setup (SMTP) if needed. Rest of the parameters are self-explanatory.
Open and edit the database.yml to reflect just the following entries as below. Again, don't forget to replace "myredminepassword" with the one you have set earlier.
The executable 'budle' which is part of the bundler gem gets installed into /var/lib/gems/1.8/bin. Include this path into PATH environment variable, before proceeding further. Since, we are not interested in development, test, mysql and sqlite gem installations for Redmine, we are skipping those here.
Make sure the above command succeeds. Otherwise, install any additional *-dev packages using apt-get and retry the bundle command above.
Installing and configuring Redmine Backlogs plugin for agile project management:
Make sure the 'bundle' command above succeeds again. This time it installs some additional gems required by backlogs plugin. For the last command which installs backlogs, please answer the questions which it prompts at the command prompt while it sets up the backlog for use with Redmine. You can change the settings later using the Redmine's user interface inside the browser.
Setting up nginx to serve Redmine ruby-on-rails application:
Follow the command prompt instructions and choose to download, compile and install nginx with passenger support (which is the recommended setup). If you choose the default options, nginx will be installed in /opt/nginx folder.
In Debian,
Well, we are almost done. We need to start the nginx server now.
If all are fine, the last command will fireup the nginx web server, running our Redmine application. Open the browser and access redmine at http://localhost/redmine. Login to the redmine as user 'admin' with default password 'admin'. Now, you are free to configure Redmine as per your project needs. Wait! we still need to do one thing, especially if we are interested in accessing gitolite controlled git repositories from within Redmine (read access only).
Configuring Gitolite and allowing read access to Redmine:
Gitolite is not configured if you simply install it via apt-get. For it to work, we need to give it a user's rsa public key, who will act as gitolite-admin, thus controlling the repository creation, providing user access and so on. Let's say, we have a user by name 'sysadmin' in our system on which we just setup the Redmine. Let's choose this user as the gitolite-admin.
Now, choose all the default values as shown in the ncurses based prompts which appear, except for admin key prompt where in you type, /tmp/sysadmin.pub. Then, gitolite will run additional setups automatically to configure sysadmin as the gitolite-admin.
Open and edit the file .gitolite.rc (under gitolite's home directory which is /var/lib/gitolite by default). Change the umask entries to reflect the following. By setting the umask to 0027 we are giving read access to the group 'gitolite' and hence, anybody who belongs to this group. We will soon include www-data as a member of this group.
Now, under those redmine projects which use git as the repository, we can view the repository contents, diffs and so on. Just stop and start the nginx server again.
Clone the gitolite-admin repository to manage rest of the git repositories through gitolite. I have assumed that sysadmin user will have a directory named 'Projects' under his HOME directory (assumed as /home/sysadmin) wherein he will clone the gitolite-admin repo.
We need to manually remove the testing.git repository from gitolite user's repositories directory.
We remove the testing.git directory as this is a test repository with previous umask set. We can create another testing repo again, using gitolite-admin configuration. Remember, not to touch the gitolite-admin.git directory!
Well, we are done!! For further assistance on git and gitolite, please refer to http://git-scm.com/docs and https://github.com/sitaramc/gitolite/wiki/ respectively.
Redmine, nginx and passenger packages are custom built and are not installed from the official Debian repository. Please remember that you need to be a root/superuser in order to go further. Please assume that all the tasks have been performed as '
root
' user unless explicitly mentioned. The dependency packages as mentioned below, are installed form the Debian repositories using the usual apt-get
command. I choose /opt
as the directory to install customized software. '$>
' just indicates the command prompt in the terminal. Make sure your proxy settings are fine, if your machine is running behind a proxy.
Final, installed system will have the following:
- Web server: Nginx
- Project management system: Redmine (v2.0)
- Scrum or Agile plugin for Redmine: Redmine Backlogs (v0.9.26)
- Ruby on Rails interface to Nginx: Phusion Passenger
- Database used for Redmine: Postgresql (v8.4, installed from Debian repository)
- Source control system: Git with Gitolite installation for repository management (git and gitolite are installed from Debian repository itself)
Basic system setup:
- My /etc/apt/sources.list file contents, showing the Debian repositories which I use. Please verify whether you have
deb http://ftp.de.debian.org/debian/ squeeze main contrib non-free
deb-src http://ftp.de.debian.org/debian/ squeeze main contrib non-free
deb http://security.debian.org/ squeeze/updates main contrib non-free
deb-src http://security.debian.org/ squeeze/updates main contrib non-free
deb http://ftp.de.debian.org/debian/ squeeze-updates main contrib non-free
deb-src http://ftp.de.debian.org/debian/ squeeze-updates main contrib non-free
- Install some of the important, dependency packages such as, g++, libtool, intltool, autoconf, automake, make, subversion, git, gitolite and rubygems, which are used by gem and passenger tools to download, compile and install the packages.
- Install additional development dependency packages such as postgresql, postgresql-contrib, libpq-dev, libxslt1-dev, libxml2-dev, libssl-dev as required by nokogiri gem and redmine. Install libcurl4-openssl-dev as required by passenger-install-nginx-module while compiling nginx.
Optional, proxy configuration if you are behind any proxy:
- Install the
socat
package using apt-get. - Copy the following shell script into a file named /usr/local/bin/gitproxy.
#!/bin/sh
#
# Use socat to proxy git through an HTTP CONNECT firewall.
# Useful if you are trying to clone git:// from inside a company.
# Requires that the proxy allows CONNECT to port 9418.
#
# Save this file as gitproxy somewhere in your path (e.g., ~/bin) and then run
# chmod +x gitproxy
# git config --global core.gitproxy gitproxy
#
# More details at http://tinyurl.com/8xvpny
# Configuration. Common proxy ports are 3128, 8123, 8000.
#
_proxy=yourproxyhost
_proxyport=yourproxyport
exec socat STDIO PROXY:$_proxy:$1:$2,proxyport=$_proxyport
- Set the executable bit of the gitproxy file by using chmod +x /usr/local/bin/gitproxy command.
- Make sure /usr/local/bin is available in PATH environment variable for everybody (not just root).
- Configure git to use proxy setting by running the following command,
$> git config --global core.gitproxy gitproxy
Git configuration: Make sure we have added username and email as part of git setup.
$> git config --global user.name "Some super user name"
$> git config --global user.email "Super user or admin email address"
Postgresql database configuration:
- Database template setup
$> su - postgres # This will change the user to postgres
$> psql template1 < /usr/share/postgresql/8.4/contrib/adminpack.sql # This will setup the postgresql database template
$> exit # Logout the postgres user. We are back to root user
- Change the password for postgres user. Choose a strong password for the postgres user ('postgres' is the admin user for Postgresql installation)
$> password postgres
- Issue the following commands to set a password for the
postgres
administrative user. Be sure to replacemypassword
with a strong password. This password will be used to connect to the database via the network; ident authentication will be used for local connections made withpsql
while logged into a shell as thepostgres
user. You may use the system password for 'postgres' again, here. If you have already done all these first-timepostgresql
setup, you can use thepsql
client directly.
$> su - postgres
$> psql -c "ALTER USER postgres WITH PASSWORD 'mypassword'" -d template1
$> psql # Start the postgresql client
Now, you will get the psql prompt. Let's setup the database and user-role for Redmine here.postgres=#
just indicates the postgresql client prompt. Replace themyredminepassword
with a strong enough password for redmine db user.
postgres=# CREATE ROLE redmine_user LOGIN ENCRYPTED PASSWORD 'myredminepassword' NOINHERIT VALID UNTIL 'infinity';
postgres=# CREATE DATABASE redmine_db WITH ENCODING='UTF8' OWNER=redmine_user;
postgres=# ALTER DATABASE "redmine_db" SET datestyle="ISO,MDY";
Now we have the database for Redmine named, 'redmine_db' and the corresponding user-role for it named, 'redmine_user' having the password 'myredminepassword' (whatever you have replaced it with).
Redmine installation:
$> cd /opt
$> svn co http://redmine.rubyforge.org/svn/branches/2.0-stable redmine-2.0
$> mv redmine-2.0 redmine
Now, it is the time to setup configuration.xml and database.xml files for Redmine.
$> cd /opt/redmine/config
$> cp configuration.yml.sample configuration.yml
Open and edit the configuration.yml to setup your default email server and other Redmine specific configuration as per your need. Consult a system administrator for proper values for email server setup (SMTP) if needed. Rest of the parameters are self-explanatory.
$> cp database.yml.sample database.yml
Open and edit the database.yml to reflect just the following entries as below. Again, don't forget to replace "myredminepassword" with the one you have set earlier.
production:
adapter: postgresql
database: redmine_db
host: localhost
username: redmine_user
password: "myredminepassword"
encoding: utf8
schema_search_path: public
$> cd /opt/redmine
$> gem install bundler
The executable 'budle' which is part of the bundler gem gets installed into /var/lib/gems/1.8/bin. Include this path into PATH environment variable, before proceeding further. Since, we are not interested in development, test, mysql and sqlite gem installations for Redmine, we are skipping those here.
$> bundle install --without development test mysql sqlite
Make sure the above command succeeds. Otherwise, install any additional *-dev packages using apt-get and retry the bundle command above.
$> export RAILS_ENV=production
$> rake generate_secret_token
$> rake db:migrate
$> rake redmine:load_default_data
$> rake tmp:cache:clear
$> rake tmp:sessions.clear
Installing and configuring Redmine Backlogs plugin for agile project management:
$> export RAILS_ENV=production
$> cd /opt/redmine/plugins
$> git clone git://github.com/backlogs/redmine_backlogs.git
$> cd /opt/redmine
$> bundle install --without development test mysql sqlite
$> rake redmine:backlogs:install
Make sure the 'bundle' command above succeeds again. This time it installs some additional gems required by backlogs plugin. For the last command which installs backlogs, please answer the questions which it prompts at the command prompt while it sets up the backlog for use with Redmine. You can change the settings later using the Redmine's user interface inside the browser.
Setting up nginx to serve Redmine ruby-on-rails application:
$> gem install passenger
$> passenger-install-nginx-module
Follow the command prompt instructions and choose to download, compile and install nginx with passenger support (which is the recommended setup). If you choose the default options, nginx will be installed in /opt/nginx folder.
$> cd /opt/nginx/html
$> ln -s /opt/redmine/public redmine
In Debian,
www-data
is the default web-server user, with a group of the same name. If it is not so in your case, adjust the web user and group values accordingly. Open the file /opt/nginx/conf/nginx.conf and edit the entries to reflect those shown below.
user www-data;
worker_processes 1;
events {
worker_connections 1024;
}
http {
passenger_root /var/lib/gems/1.8/gems/passenger-3.0.17;
passenger_ruby /usr/bin/ruby1.8;
passenger_default_user www-data;
passenger_default_group www-data;
include mime.types;
default_type application/octet-stream;
sendfile on;
keepalive_timeout 65;
gzip on;
server {
listen 80;
server_name localhost;
location / {
root html;
index index.html index.htm;
passenger_enabled on;
passenger_base_uri /redmine;
}
# redirect server error pages to the static page /50x.html
#
error_page 500 502 503 504 /50x.html;
location = /50x.html {
root html;
}
}
}
Now, we need to change the web-user access to some of the Redmine directories.
$> cd /opt/redmine
$> chown -R www-data:www-data files tmp log public/plugin_assets
$> chmod -R 755 files tmp log public/plugin_assets
Well, we are almost done. We need to start the nginx server now.
$> /opt/nginx/sbin/nginx -c /opt/nginx/conf/nginx.conf
If all are fine, the last command will fireup the nginx web server, running our Redmine application. Open the browser and access redmine at http://localhost/redmine. Login to the redmine as user 'admin' with default password 'admin'. Now, you are free to configure Redmine as per your project needs. Wait! we still need to do one thing, especially if we are interested in accessing gitolite controlled git repositories from within Redmine (read access only).
Configuring Gitolite and allowing read access to Redmine:
Gitolite is not configured if you simply install it via apt-get. For it to work, we need to give it a user's rsa public key, who will act as gitolite-admin, thus controlling the repository creation, providing user access and so on. Let's say, we have a user by name 'sysadmin' in our system on which we just setup the Redmine. Let's choose this user as the gitolite-admin.
$> su - sysadmin
$> ssh-keygen -t rsa #Just, type enter and do not set any passphrase
$> cp ~/.ssh/id_rsa.pub /tmp/sysadmin.pub # Name of the .pub file should match the user name
$> exit # We are back to root / superuser
$> dpkg-reconfigure gitolite
Now, choose all the default values as shown in the ncurses based prompts which appear, except for admin key prompt where in you type, /tmp/sysadmin.pub. Then, gitolite will run additional setups automatically to configure sysadmin as the gitolite-admin.
$> su - gitolite # switch to gitolite user
Open and edit the file .gitolite.rc (under gitolite's home directory which is /var/lib/gitolite by default). Change the umask entries to reflect the following. By setting the umask to 0027 we are giving read access to the group 'gitolite' and hence, anybody who belongs to this group. We will soon include www-data as a member of this group.
# $REPO_UMASK = 0077; # gets you 'rwx------'
$REPO_UMASK = 0027; # gets you 'rwxr-x---'
# $REPO_UMASK = 0022; # gets you 'rwxr-xr-x'
$> exit # We are back as root / superuser
$> adduser www-data gitolite # We have added www-data to gitolite group
Now, under those redmine projects which use git as the repository, we can view the repository contents, diffs and so on. Just stop and start the nginx server again.
$> /opt/nginx/sbin/nginx -s stop && sync
$> /opt/nginx/sbin/nginx -c /opt/nginx/conf/nginx.conf
Clone the gitolite-admin repository to manage rest of the git repositories through gitolite. I have assumed that sysadmin user will have a directory named 'Projects' under his HOME directory (assumed as /home/sysadmin) wherein he will clone the gitolite-admin repo.
$> su - sysadmin
$> mkdir -p ~/Projects
$> cd ~/Projects
$> git clone gitolite@localhost:gitolite-admin.git
Now, sysadmin user will have gitolite-admin repo under /home/sysadmin/Projects. Open edit the file conf/gitolite.conf uner gitolite-admin directory and remove the 'testing' repo configuration. Do not touch gitolite-admin stuff!! Then do a git commit and push as follows (We are in directory /home/sysadmin/Projects/gitolite-admin).
$> git add .
$> git commit -a -m "Removed testing repo"
$> git push origin master
$> exit # We are back as root / superuser
We need to manually remove the testing.git repository from gitolite user's repositories directory.
$> su - gitolite
$> cd ~/repositories
$> rm -rf testing.git
We remove the testing.git directory as this is a test repository with previous umask set. We can create another testing repo again, using gitolite-admin configuration. Remember, not to touch the gitolite-admin.git directory!
Well, we are done!! For further assistance on git and gitolite, please refer to http://git-scm.com/docs and https://github.com/sitaramc/gitolite/wiki/ respectively.
Comments
Post a Comment