Redmine is a free and open source, web-based project management and issue tracking tool. It handles multiple projects and subprojects. It features per project wikis and forums, time tracking, and flexible role based access control. It includes a calendar and Gantt charts to aid visual representation of projects and their deadlines. Redmine integrates with various version control systems and includes a repository browser and diff viewer.
- 1 Prerequisites
- 2 Optional Prerequisites
- 3 Installation
- 3.1 Build and Installation
- 3.2 Database Configuration
- 3.3 Ruby gems
- 3.4 Session Store Secret Generation
- 3.5 Database Structure Creation
- 3.6 Database Population with Default Data
- 3.7 File System Permissions
- 3.8 Test the installation
- 3.9 Configure the production server
- 4 Updating
- 5 Troubleshooting
- 6 See also
This document will guide you through the installation process of Redmine and all of its prerequisites, including the optional ones. If desired, however, you may install Redmine and its prerequisites separately, simply referring to the relevant sections below.
Although this guide will go through the entire installation process, this is not a one way path. Redmine can use different versions of the requisite software. For example the database requirement can be provided by mariaDB, mySQL, postgreSQL, etc.
|Redmine version||Supported Ruby Versions||Rails version used|
|4.0||2.3, 2.4, 2.5, 2.6||5.2|
|4.1||2.3, 2.4, 2.5, 2.6||5.2|
Redmine supports many different databases.
MariaDB 5.0 or higher (recommended)
- MariaDB is a drop-in replacement for MySQL, in fact it was a fork of it and maintain binary compatibility. It is also Arch Linux's default implementation of MySQL.
- MariaDB has known issues (#19344, #19395, #17460).
To install MySQL.simply refer to
MySQL 5.5 - 5.7
- Oracle MySQL was dropped to the AUR. AUR in the AUR.
- MySQL 5.6 or higher has known issues (#19344, #19395, #17460).
PostgreSQL 9.2 or higher
- To install PostgreSQL. simply refer to
- Make sure your database datestyle is set to ISO (Postgresql default setting). You can set it using:
ALTER DATABASE "redmine_db" SET datestyle="ISO,MDY";
Not supported for multi-user production use. So, it will not be detailed how to install and configure it for use with Redmine. See upstream document for more info.
To install Apache HTTP Server.simply refer to
To install Unicorn server (ruby gem) simply refer to Ruby on Rails#Unicorn.
To install Nginx.simply refer to
To install Tomcat.or simply refer to
SCM (Source Code Management)
|Git||184.108.40.206 to 2.11.0|
|Subversion||1.3 to 1.9.7||1.3 or higher required.
Does not support Ruby Bindings for Subversion.
|Mercurial||1.2 to 4.3.1||Support bellow version 1.6 is droped as seen in #9465.|
|Bazaar||1.0.0.candidate.1 to 2.7.0|
|CVS||1.12.12, 1.12.13||1.12 required.
Will not work with CVSNT.
More information can be read at Redmine Repositories Wiki.
Ruby OpenID Library
To enable OpenID support, install the OpenID Connect Plugin.
Build and Installation
Install the package.
Now, we will need to create the database that the Redmine will use to store your data. For now on, the database and its user will be named
redmine. But this names can be changed to anything else.
To create the database, the user and set privileges:
# mysql -u root -p
CREATE DATABASE redmine CHARACTER SET UTF8; CREATE USER 'redmine'@'localhost' IDENTIFIED BY 'my_password'; GRANT ALL PRIVILEGES ON redmine.* TO 'redmine'@'localhost';
CREATE ROLE redmine LOGIN ENCRYPTED PASSWORD 'my_password' NOINHERIT VALID UNTIL 'infinity'; CREATE DATABASE redmine WITH ENCODING='UTF8' OWNER=redmine;
Although the database, login and user can be created within SQL Server Management Studio with a few clicks, you can always use the command line with
USE [master] GO -- Very basic DB creation CREATE DATABASE [REDMINE] GO -- Creation of a login with SQL Server login/password authentication and no password expiration policy CREATE LOGIN [REDMINE] WITH PASSWORD=N'redminepassword', DEFAULT_DATABASE=[REDMINE], CHECK_EXPIRATION=OFF, CHECK_POLICY=OFF GO -- User creation using previously created login authentication USE [REDMINE] GO CREATE USER [REDMINE] FOR LOGIN [REDMINE] GO -- User permissions set via roles EXEC sp_addrolemember N'db_datareader', N'REDMINE' GO EXEC sp_addrolemember N'db_datawriter', N'REDMINE' GO
Database Access Configuration
Now you need to configure Redmine to access the database we just created. To do that you have to copy
# cd /usr/share/webapps/redmine/config # cp database.yml.example database.yml
And then edit this file in order to configure your database settings for "production" environment (you can configure for the "development" and "test" environments too, just change the appropriate sections).
Example for MariaDB and MySQL database:
production: adapter: mysql2 database: redmine host: localhost port: 3307 #If your server is not running on the standard port (3306), set it here, otherwise this line is unnecessary. username: redmine password: my_password
Example for PostgreSQL database:
production: adapter: postgresql database: redmine host: localhost username: redmine password: my_password encoding: utf8 schema_search_path: <database_schema> (default - public)
Example for a SQL Server database:
production: adapter: sqlserver database: redmine host: localhost #Set not default host (localhost) here, otherwise this line is unnecessary. port: 1433 #Set not standard port (1433) here, otherwise this line is unnecessary. username: redmine password: my_password
Redmine requires some RubyGems to be installed and there are multiple ways of installing them (as listed on the referenced page).
- unicorn (an application-server)
- mysql2 (high-performance Ruby bindings for MySQL)
Obviously, if you choose a different database-server, or want to use a different application-server you should replace mysql2 and unicorn to your liking.
Adding Additional Gems (Optional)
If you need to load gems that are not required by Redmine core (eg. Puma, fcgi), create a file named
Gemfile.local at the root of your redmine directory. It will be loaded automatically when running
# nano Gemfile.local
Check previously installed gems
The Redmine devs included Bundler in Redmine, which can manage Gems just like pacman manages packages. Run the following command to assure that all Redmine dependencies are met:
# bundle install --without development test
This should output a list of gems Redmine needs.
Redmine uses Bundler to manage gems dependencies. So, you need to install Bundler first:
# gem install bundler
Then you can install all the gems required by Redmine using the following command:
# cd /usr/share/webapps/redmine # bundle install
To install without the ruby development and test environments use this instead of the last command:
# bundle install --without development test
Although recommended, if you do not use it, you should skip the installation of the
rmagick gem using:
# bundle install --without rmagick
config/database.ymluses the mysql2 adapter, then only the mysql2 gem will be installed). Do not forget to re-run
bundle installwhen you change or add adapters in this file.
Session Store Secret Generation
Now you must generate a random key that will be used by Rails to encode cookies that stores session data thus preventing their tampering:
# bundle exec rake generate_secret_token
Database Structure Creation
With the database created and the access configured for Redmine, now it is time to create the database structure. This is done by running the following command under the application root directory:
# cd /usr/share/webapps/redmine # RAILS_ENV=production bundle exec rake db:migrate
These command will create tables by running all migrations one by one then create the set of the permissions and the application administrator account, named admin.
Database Population with Default Data
Now you may want to insert the default configuration data in database, like basic types of task, task states, groups, etc. To do so execute the following:
# RAILS_ENV=production bundle exec rake redmine:load_default_data
Redmine will prompt for the data set language that should be loaded; you can also define the REDMINE_LANG environment variable before running the command to a value which will be automatically and silently picked up by the task:
# RAILS_ENV=production REDMINE_LANG=pt-BR bundle exec rake redmine:load_default_data
File System Permissions
The user account running the application must have write permission on the following subdirectories:
files: storage of attachments. log: application log file production.log. tmp and tmp/pdf: used to generate PDF documents among other things (create these ones if not present).
Assuming you run the application with a the default Apache user
# mkdir tmp tmp/pdf public/plugin_assets # chown -R http:http files log tmp public/plugin_assets # chmod -R 755 files log tmp tmp/pdf public/plugin_assets
Test the installation
To test your new installation using WEBrick web server run the following in the Redmine folder:
# ruby bin/rails server webrick -e production
Once WEBrick has started, point your browser to http://localhost:3000/. You should now see the application welcome page. Use default administrator account to log in: admin/admin. You can go to Administration menu and choose Settings to modify most of the application settings.
Configure the production server
Start by installing the 'passenger' gem:
# gem install passenger
Now you have to look at your passenger gem installation directory to continue. If you do not known where it is, type:
# gem env
And look at the
GEM PATHS to find where the gems are installed. If you followed this guide and installed RVM, you can have more than one path, look at the one you are using.
For this guide so far, the gem path is
# cd /usr/local/rvm/gems/ruby-2.0.0-p247@global/gems/passenger-4.0.23
If you are aiming to use Apache HTTP Server, run:
And finally, the installer will provide you with further information regarding the installation (such as installing additional libraries). So, to setup your server, simply follow the output from the passenger installer.
Backup the files used in Redmine:
# tar czvf ~/redmine_files.tar.gz -C /usr/share/webapps/redmine/ files
Backup the plugins installed in Redmine:
# tar czvf ~/redmine_plugins.tar.gz -C /usr/share/webapps/redmine/ plugins
Backup the database:
# mysqldump -u root -p <redmine_database> | gzip > ~/redmine_db.sql.gz
Update thepackage as normal.
Update the gems requirements:
# bundle update
For a clean gems environment, you may want to remove all the gems and reinstall them. To go through this, do:
# for x in `gem list --no-versions`; do gem uninstall $x -a -x -I; done
If you did the last step and removed all the gems, now you will need to reinstall them all:
# gem install bundler # bundle install --without development test
Copy the saved files:
# tar xzvf ~/redmine_files.tar.gz -C /usr/share/webapps/redmine/
Copy the installed plugins:
# tar xzvf ~/redmine_plugins.tar.gz -C /usr/share/webapps/redmine/
Regenerate the secret token:
# cd /usr/share/webapps/redmine # bundle exec rake generate_secret_token
Check for any themes that you may have installed in the
public/themes directory. You can copy them over but checking for updated version is ideal.
Update the database. This step is the one that could change the contents of your database. Go to your new redmine directory, then migrate your database:
# RAILS_ENV=production REDMINE_LANG=pt-BR bundle exec rake db:migrate
If you have installed any plugins, you should also run their database migrations:
# RAILS_ENV=production REDMINE_LANG=pt-BR bundle exec rake redmine:plugins:migrate
Now, it is time to clean the cache and the existing sessions:
# RAILS_ENV=production bundle exec rake tmp:cache:clear tmp:sessions:clear
Restart the application server (e.g. puma, thin, passenger, etc). And finally go to "Admin -> Roles & permissions" to check/set permissions for the new features, if any.
Runtime error complaining that RMagick was configured with older version
If you get the following runtime error after upgrading ImageMagick
This installation of RMagick was configured with ImageMagick 6.8.7 but ImageMagick 6.8.8-1 is in use. then you only need to reinstall (or rebuild as shown above if is the case).
Error when installing gems: Cannot load such file -- mysql2/mysql2
If you see an error like
cannot load such file -- mysql2/mysql2, you are having a problem with the installation of the database gem. Probably a misconfiguration in the Database Access Configuration step.
In this case you should verify the
If no success, you can manually install the database gem by:
# gem install mysql2
In last case, as suggested by Bobdog, you can try to comment the line of the database gem and add a new one as bellow:
# require 'mysql2/mysql2' require '<path-to-mysql2-gem-directory>/lib/mysql2/mysql2.so'
Apache 2.4 Updating
When updating to Apache 2.4 will be necessary to remove and install all your gems to make sure all of them that need to build native extensions will be rebuilt against the new Apache server.
So, for a clean gems environment, remove all the gems:
# for x in `gem list --no-versions`; do gem uninstall $x -a -x -I; done
To reinstall the gems:
# cd /usr/share/webapps/redmine # gem install bundler # bundle install --without development test
Remember to reinstall the RMagick gem as describe above in RMagick gem without support for High Dynamic Range in ImageMagick.
And if you are using Passenger to serve your apps through Apache you will need to reinstall it as described above in Configure the production server.
Checkout SVN Source
Get the Redmine source (Download instructions). Here is method of installing Redmine directly from subversion in /srv/http/redmine/
# useradd -d /srv/http/redmine -s /bin/false redmine # mkdir -p /srv/http/redmine # svn checkout http://svn.redmine.org/redmine/branches/2.1-stable /srv/http/redmine # chown -R redmine: /srv/http/redmine
Automating The Update Process
Example of an after-update script:
#!/usr/bin/bash export RAILS_ENV=production grep -E "^gem 'thin'" Gemfile || echo "gem 'thin'" >> Gemfile bundle update && bundle exec rake generate_secret_token db:migrate redmine:plugins:migrate tmp:cache:clear tmp:sessions:clear
Creating a Systemd Unit
If you want to automatic run you application server when system starts, you need to create a systemd unit file.
[Unit] Description=Redmine server After=syslog.target After=network.target [Service] Type=simple User=redmine2 Group=redmine2 Environment=GEM_HOME=/home/redmine2/.gem/ ExecStart=/usr/bin/ruby /usr/share/webapps/redmine/bin/rails server webrick -e production # Give a reasonable amount of time for the server to start up/shut down TimeoutSec=300 [Install] WantedBy=multi-user.target
Complaints about psych
/usr/lib/ruby/2.1.0/psych/parser.rb:33:in `<class:Parser>': superclass mismatch for class Mark (TypeError) from /usr/lib/ruby/2.1.0/psych/parser.rb:32:in `<module:Psych>' from /usr/lib/ruby/2.1.0/psych/parser.rb:1:in `<top (required)>' from /usr/lib/ruby/2.1.0/psych.rb:7:in `require'
according to that that is a bundler issue, and you have to add
to your Gemfile.local