This installation guide requires Ubuntu 14.04 or higher and Redmine 3.1+.

Package installation

Web frontend

The easiest way to run Redmine is through Apache and Passenger:

apt-get install --no-install-recommends apache2 libapache2-mod-passenger logrotate ssl-cert

DB backend

To configure a MySQL server, please refer to the MySQL installation guide


Install Redmine's dependencies and git:

apt-get install --no-install-recommends git ruby ruby-dev ruby-rmagick rake make gcc libmysqlclient-dev patch

Since Redmine is developped to a fast pace, it is better and more convenient to install it directly from the git repository:

# Clone the tree
cd /var/www
git clone
cd redmine

# Checkout the latest stable tag
git checkout 3.1-stable

Install the gems needed for Redmine 3.0+:

# Make sure gems are fetched using HTTPS
# An alternative is to use "--clear-sources -s"
cat << EOF >> /etc/gemrc

cd /var/www/redmine
gem install --no-ri --no-rdoc bundler nokogiri
hash -r

Use Bundler to install required gems but disable unused ones:

cd /var/www/redmine
bundle install --without development test postgresql sqlite rmagick



The following commands will create a DB and a user with a random password:

REDMINE_PASSWORD=$(openssl rand -base64 33)
mysql -e "CREATE DATABASE redmine;"
mysql -e "CREATE USER 'redmine'@'localhost' IDENTIFIED BY '$REDMINE_PASSWORD';"
mysql -e "GRANT ALL PRIVILEGES ON redmine.* TO 'redmine'@'localhost';"


Create a user to be used by Passenger:

adduser --quiet --system --group --gecos 'Passenger user for redmine' --shell /usr/sbin/nologin --home /nonexistent --no-create-home redmine

Prepare the file "/var/www/redmine/config/database.yml" with the right user/password and DB. You can look at "database.yml.example" for an example but the commands below generates the appropriate config file for MySQL. Adapt it if you are using ruby 1.8.

# Secure the file as it contains a password in plain text
touch /var/www/redmine/config/database.yml
chmod 640 /var/www/redmine/config/database.yml
chgrp redmine /var/www/redmine/config/database.yml

cat << EOF > /var/www/redmine/config/database.yml
  adapter: mysql2
  database: redmine
  # XXX: Unix sockets are faster than loopback connections
  socket: /var/run/mysqld/mysqld.sock
  username: redmine
  password: "$REDMINE_PASSWORD"
  encoding: utf8

# Clean up the environment

Prepare the file "/var/www/redmine/config/configuration.yml" to enable sending emails and to encrypt SCM and LDAP passwords in the DB:

# Secure the file as it contains a password and a cipher key in plain text
touch /var/www/redmine/config/configuration.yml
chmod 640 /var/www/redmine/config/configuration.yml
chgrp redmine /var/www/redmine/config/configuration.yml

cat << EOF > /var/www/redmine/config/configuration.yml
# default configuration options for all environments
    delivery_method: :async_sendmail

  # Key used to encrypt sensitive data in the database (SCM and LDAP passwords).
  # If you don't want to enable data encryption, just leave it blank.
  # WARNING: losing/changing this key will make encrypted data unreadable.
  # If you want to encrypt existing passwords in your database:
  # * set the cipher key here in your configuration file
  # * encrypt data using 'rake db:encrypt RAILS_ENV=production'
  # If you have encrypted data and want to change this key, you have to:
  # * decrypt data using 'rake db:decrypt RAILS_ENV=production' first
  # * change the cipher key here in your configuration file
  # * encrypt data using 'rake db:encrypt RAILS_ENV=production'
  database_cipher_key: "$(openssl rand -base64 45)"

  # Requires users to re-enter their password for sensitive actions (editing
  # of account data, project memberships, application settings, user, group,
  # role, auth source management and project deletion). Disabled by default.
  # Timeout is set in minutes.
  sudo_mode: true
  #sudo_mode_timeout: 15

Prepare the DB:

# Re-run Bundler to automatically install the right DB adapter now that database.yml is populated
cd /var/www/redmine
bundle install --without development test postgresql sqlite rmagick

# Generate a secret token and protect it
rake generate_secret_token
chmod 0640 config/initializers/secret_token.rb
chgrp redmine config/initializers/secret_token.rb

RAILS_ENV=production rake db:migrate
RAILS_ENV=production REDMINE_LANG=en rake redmine:load_default_data

# Encrypt SCM and LDAP passwords
RAILS_ENV=production rake db:encrypt

Setup some directories:

cd /var/www/redmine
mkdir -p tmp tmp/pdf public/plugin_assets
chown -R redmine: files log tmp public/plugin_assets
chmod -R 0755 public/plugin_assets
chmod -R 0750 files log tmp  # can contain sensitive data
find files log tmp public/plugin_assets -type f -exec chmod -x {} +

Ensure proper log rotation to avoid filling the HDD:

cat << EOF > /etc/logrotate.d/redmine
/var/www/redmine/log/*.log {
  rotate 7


If you want Redmine to be accessed via a sub-URI ("/pm" in this example) you need to tweak the configuration.yml and environment.rb files as well as create a symlink:

cd /var/www/redmine
echo 'Redmine::Utils::relative_url_root = "/pm"' >> config/environment.rb

cat << EOF >> config/configuration.yml
  # Configuration of the autologin cookie.
  # autologin_cookie_name: the name of the cookie (default: autologin)
  # autologin_cookie_path: the cookie path (default: /)
  # autologin_cookie_secure: true sets the cookie secure flag (default: false)
  autologin_cookie_path: "/pm"
  autologin_cookie_secure: true

ln -s public pm

Optionally, you can remove some unused modules but be careful if there are other vhosts on your server:

a2dismod access_compat alias authz_groupfile autoindex cgid deflate dir env filter negotiation status > /dev/null

Create the SSL enabled vhost for Redmine:

cat << EOF > /etc/apache2/sites-available/
<VirtualHost _default_:443>

  ErrorLog /var/log/apache2/redmine-error.log
  CustomLog /var/log/apache2/redmine.log combined

  SSLEngine On
  SSLCertificateFile    /etc/ssl/certs/ssl-cert-snakeoil.pem
  SSLCertificateKeyFile /etc/ssl/private/ssl-cert-snakeoil.key

  # Passenger user
  PassengerUser redmine

  # XXX: If NOT using a sub-URI
  #DocumentRoot /var/www/redmine/public

  # XXX: If using a sub-URI (/pm)
  DocumentRoot /var/www/redmine/pm
  RailsBaseURI /pm
  PassengerAppRoot /var/www/redmine

Tweak Passenger performance:

cat << EOF > /etc/apache2/conf-available/zz-passenger-performance.conf
# Passenger tuning
PassengerMaxPoolSize 2
PassengerMinInstances 1
# XXX: Pick one of those PassengerPreStart
PassengerMaxRequests 5000
PassengerUploadBufferDir /tmp/
# Breaks compatibility with mod_autoindex and mod_rewrite
PassengerHighPerformance on

# Do not reveal too much about the server
ServerTokens Prod
ServerSignature Off

It is desirable to only access the service via HTTPS to avoid transmitting credentials in the clear:

a2dissite default 000-default default-ssl
a2enmod ssl passenger
a2enconf zz-passenger-performance

apache2ctl -S && service apache2 restart

From here, you are ready to connect to your new Redmine by using the default credentials: "admin/admin".