Project

General

Profile

RedmineInstall » History » Version 149

Jean-Philippe Lang, 2012-04-14 16:33
note about mongrel

1 1 Jean-Philippe Lang
h1. Installing Redmine
2
3
{{>TOC}}
4 73 Liraz Siri
5 147 Jean-Philippe Lang
This is the installation documentation for Redmine 1.4.0 and higher. You can still read the document for 1.3.x "here":/projects/redmine/wiki/RedmineInstall?version=146.
6
7 1 Jean-Philippe Lang
h2. Requirements
8
9 25 Jean-Philippe Lang
h3. Operating system
10 1 Jean-Philippe Lang
11 105 Josh Galvez
Redmine should run on most Unix, Linux, [[RedmineInstallOSX|Mac]], [[RedmineInstallOSXServer|Mac Server]] and Windows systems as long as Ruby is available on this platform.  See specific installation HowTos [[HowTos|here]].
12 25 Jean-Philippe Lang
13 91 Kedar Mhaswade
h3. Ruby & Ruby on Rails & Rack
14 25 Jean-Philippe Lang
15 1 Jean-Philippe Lang
The required Ruby and Ruby on Rails versions for a given Redmine version is:
16
17 147 Jean-Philippe Lang
|_. Redmine version|_. Supported Ruby versions|_. Required Rails version|_. Supported RubyGems versions|
18
|current trunk|ruby 1.8.7, 1.9.2, 1.9.3, jruby-1.6.7|Rails 2.3.14|RubyGems <= 1.8|
19
|1.4.x|ruby 1.8.7, 1.9.2, 1.9.3, jruby-1.6.7|Rails 2.3.14|RubyGems <= 1.8|
20
|1.3.x|ruby 1.8.6, 1.8.7|Rails 2.3.14|RubyGems <= 1.7|
21
|1.2.x|ruby 1.8.6, 1.8.7|Rails 2.3.11|RubyGems <= 1.6|
22
|1.1.x|ruby 1.8.6, 1.8.7|Rails 2.3.51|RubyGems <= 1.4|
23
|1.0.x|ruby 1.8.6, 1.8.7|Rails 2.3.5|RubyGems <= 1.4|
24
|0.9.x|ruby 1.8.6, 1.8.7|Rails 2.3.5|RubyGems <= 1.4|
25
|0.8.x|ruby 1.8.6, 1.8.7|Rails 2.1.2||
26 1 Jean-Philippe Lang
27 128 Jean-Baptiste Barth
h3. Compatibility notes
28 125 Etienne Massip
29 140 Mischa The Evil
* *Rack* 1.1.x is required, 1.1.0 has a bug with quotes (#8416). Database migration would fail with other version.
30
* *Mongrel* 1.1.5 needs a patch attached to #7688 to work fine with Rails 2.3.11. In case of upgrade, another issue may appear for some time after migration (#7857).
31 25 Jean-Philippe Lang
32 93 Muntek Singh
h3. Database
33 92 Knight Samar
34 146 Etienne Massip
* MySQL 5.0 or higher (recommended)
35 35 Jean-Philippe Lang
36
 * make sure to install the C bindings for Ruby that dramatically improve performance. You can get them by running @gem install mysql2@. If you have problem installing the mysql gem refer "Rails Wiki pages":http://wiki.rubyonrails.org/database-support/mysql
37 1 Jean-Philippe Lang
38 147 Jean-Philippe Lang
* PostgreSQL 8 or higher
39 117 Etienne Massip
40 1 Jean-Philippe Lang
 * 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";@
41 146 Etienne Massip
 * some bugs in PostgreSQL 8.4.0 and 8.4.1 affect Redmine behavior (#4259, #4314), they are fixed in PostgreSQL 8.4.2
42 1 Jean-Philippe Lang
43
* SQLite 3
44
45
h3. Optional components
46
47
      * SCM binaries (eg. @svn@), for repository browsing (must be available in your PATH). See [[RedmineRepositories]] for SCM compatibility and requirements.
48
      * "RMagick":http://rmagick.rubyforge.org/ (to enable Gantt export to png image)
49
      * "Ruby OpenID Library":http://openidenabled.com/ruby-openid/ (to enable OpenID support) [only on Redmine trunk / 0.9-dev]  Version 2 or greater is required.
50
51
h2. Redmine Version
52
53
It is recommended that the majority of users install the proper point releases of redmine. Redmine currently releases a new version every 6 months, and these releases are considered very usable and stable. It is *not* recommended to install redmine from trunk, unless you are deeply familiar with Ruby on Rails and keep up with the changes - Trunk _does_ break from time-to-time.
54
55 114 Etienne Massip
h2. Installation procedure
56 35 Jean-Philippe Lang
57
1. Get the Redmine source code by either downloading a packaged release or checking out the code repository. See [[Download]].
58 26 Jean-Philippe Lang
59 147 Jean-Philippe Lang
2. Since 1.4.0, Redmine uses "Bundler":http://gembundler.com/ to manage gems dependencies. You need to install Bundler first:
60 23 Jean-Philippe Lang
61 147 Jean-Philippe Lang
  gem install bundler
62
63
Then you can install all the gems required by Redmine using the following command:
64
65
  bundle install --without development test
66
67
If ImageMagick is not installed on your system, you should skip the installation of the rmagick gem using: @`bundle install --without development test rmagick`@.
68
69
You can also skip the installation of the database adapters you're not using. For example, if you're using MySQL, you can skip the installation of the postgresql and sqlite gems using @`bundle install --without development test postgresql sqlite`@.
70
71 149 Jean-Philippe Lang
If you need to load any gems that are not required by Redmine core (eg. mongrel, fcgi), create a file named @Gemfile.local@ at the root of your redmine directory. It will be loaded automatically when running `bundle install`. Exemple:
72
73
<pre>
74
# Gemfile.local
75
gem "mongrel"
76
</pre>
77 147 Jean-Philippe Lang
78
3. Create an empty database and accompanying user named @redmine@ for example.
79
80 1 Jean-Philippe Lang
For MySQL:
81
82 38 Yclept Nemo
<pre>
83 39 Yclept Nemo
create database redmine character set utf8;
84
create user 'redmine'@'localhost' identified by 'my_password';
85
grant all privileges on redmine.* to 'redmine'@'localhost';
86 38 Yclept Nemo
</pre>
87 1 Jean-Philippe Lang
88 88 Sean Farrell
For versions of MySQL prior to 5.0.2 - skip the 'create user' step and instead:
89
<pre>
90
grant all privileges on redmine.* to 'redmine'@'localhost' identified by 'my_password';
91 1 Jean-Philippe Lang
</pre>
92
93
For PostgreSQL:
94
95
<pre>
96
CREATE ROLE redmine LOGIN ENCRYPTED PASSWORD 'my_password' NOINHERIT VALID UNTIL 'infinity';
97
CREATE DATABASE redmine WITH ENCODING='UTF8' OWNER=redmine;
98
</pre>
99
100 147 Jean-Philippe Lang
4. Copy @config/database.yml.example@ to @config/database.yml@ and edit this file in order to configure your database settings for "production" environment.
101 1 Jean-Philippe Lang
102 147 Jean-Philippe Lang
Example for a MySQL database using ruby1.8 or jruby:
103 88 Sean Farrell
104 63 Thanos Kyritsis
<pre>
105
production:
106
  adapter: mysql
107
  database: redmine
108 64 Thanos Kyritsis
  host: localhost
109 63 Thanos Kyritsis
  username: redmine
110 3 Jean-Philippe Lang
  password: my_password
111 1 Jean-Philippe Lang
</pre>
112 14 Jean-Philippe Lang
113 147 Jean-Philippe Lang
Example for a MySQL database using ruby1.9 (adapter must be set to @mysql2@):
114
115
<pre>
116
production:
117
  adapter: mysql2
118
  database: redmine
119
  host: localhost
120
  username: redmine
121
  password: my_password
122
</pre>
123
124 54 Barbara Post
If your server is not running on the standard port (3306), use this configuration instead:
125
126
<pre>
127 1 Jean-Philippe Lang
production:
128 54 Barbara Post
  adapter: mysql
129
  database: redmine
130 1 Jean-Philippe Lang
  host: localhost
131 54 Barbara Post
  port: 3307
132
  username: redmine
133
  password: my_password
134
</pre>
135
136 44 Alexey Lustin
137
Example for a PostgreSQL database (default port):
138
139
<pre>
140
production:
141
  adapter: postgresql
142
  database: <your_database_name>
143 46 Istvan DEMETER
  host: <postgres_host>
144 1 Jean-Philippe Lang
  username: <postgres_user>
145 44 Alexey Lustin
  password: <postgres_user_password>
146
  encoding: utf8
147
  schema_search_path: <database_schema> (default - public)
148 111 Jean-Philippe Lang
</pre>
149 1 Jean-Philippe Lang
150 147 Jean-Philippe Lang
5. Generate a session store secret.
151 82 Simon Carpinter
152 41 Yclept Nemo
   rake generate_session_store
153
154 147 Jean-Philippe Lang
6. Create the database structure, by running the following command under the application root directory:
155 1 Jean-Philippe Lang
156 90 Jiongliang Zhang
  RAILS_ENV=production rake db:migrate
157 1 Jean-Philippe Lang
158 90 Jiongliang Zhang
159
It will create tables and an administrator account.
160
161
If you get this error: 
162 1 Jean-Philippe Lang
<pre>
163 90 Jiongliang Zhang
Rake aborted!
164
no such file to load -- net/https
165
</pre>
166 114 Etienne Massip
167 1 Jean-Philippe Lang
you need to install libopenssl-ruby1.8, in Ubuntu, just like this: apt-get install libopenssl-ruby1.8
168 41 Yclept Nemo
169 147 Jean-Philippe Lang
7. Insert default configuration data in database, by running the following command:
170 1 Jean-Philippe Lang
171 62 Vladimir L
  RAILS_ENV=production rake redmine:load_default_data
172 32 Jean-Philippe Lang
173
This step is optional but *highly recommended*, as you can define your own configuration from scratch. It will load default roles, trackers, statuses, workflows and enumerations.
174
175 147 Jean-Philippe Lang
8. Setting up permissions
176 32 Jean-Philippe Lang
177 14 Jean-Philippe Lang
NB: _Windows users have to skip this section._
178
179
The user who runs Redmine must have write permission on the following subdirectories: @files@, @log@, @tmp@ (create the last one if not present).
180
181
Assuming you run Redmine with a @redmine@ user:
182
183 31 Eric Davis
<pre>
184 1 Jean-Philippe Lang
mkdir tmp public/plugin_assets
185 31 Eric Davis
sudo chown -R redmine:redmine files log tmp public/plugin_assets
186 14 Jean-Philippe Lang
sudo chmod -R 755 files log tmp public/plugin_assets
187
</pre>
188 1 Jean-Philippe Lang
189 147 Jean-Philippe Lang
9. Test the installation by running WEBrick web server:
190 1 Jean-Philippe Lang
191 33 Jean-Philippe Lang
  ruby script/server webrick -e production
192 1 Jean-Philippe Lang
193 14 Jean-Philippe Lang
Once WEBrick has started, point your browser to http://localhost:3000/. You should now see the application welcome page.
194 1 Jean-Philippe Lang
195 103 Muntek Singh
> Note: Webrick is *not* suitable for normal use, please only use webrick for testing that the installation up to this point is functional. It is not recommended to use webrick for anything other than development. Use one of the many other guides in this wiki to setup redmine to use either passenger (aka mod_rails) or mongrel to serve up your redmine. 
196
197 147 Jean-Philippe Lang
10. Use default administrator account to log in:
198 1 Jean-Philippe Lang
199
    * login: admin
200 14 Jean-Philippe Lang
    * password: admin
201 1 Jean-Philippe Lang
202
You can go to @Admin & Settings@ to modify application settings.
203
204 130 Etienne Massip
h2. Configuration
205 1 Jean-Philippe Lang
206 131 Etienne Massip
Since of version:1.2.0, Redmine settings are defined in a file named @config/configuration.yml@.
207 130 Etienne Massip
208 133 Etienne Massip
If you need to override default application settings, simply copy @config/configuration.yml.example@ to @config/configuration.yml@ then edit the new file; the file is well commented by itself, so you should have a look at it.
209 1 Jean-Philippe Lang
210 131 Etienne Massip
This settings may be defined per Rails environment (@production@/@development@/@test@).
211
212
+Important+ : don't forget to restart the application after any change.
213
214 130 Etienne Massip
h3. Email / SMTP server settings
215
216 132 Etienne Massip
Email configuration is described in a [[EmailConfiguration|dedicated page]].
217 1 Jean-Philippe Lang
218
h3. SCM settings
219
220 133 Etienne Massip
This configuration section allows you to:
221 131 Etienne Massip
* override default commands names if the SCM binaries present in the @PATH@ variable doesn't use the standard name (Windows .bat/.cmd names won't work)
222
* specify the full path to the binary
223
224 133 Etienne Massip
Examples (with Subversion):
225 131 Etienne Massip
226 133 Etienne Massip
Command name override:
227 131 Etienne Massip
228
 scm_subversion_command: "svn_replacement.exe"
229
230 133 Etienne Massip
Absolute path:
231 1 Jean-Philippe Lang
232
 scm_subversion_command: "C:\Program Files\Subversion\bin\svn.exe"
233
234
h3. Attachment storage settings
235
236 133 Etienne Massip
You can set a path where Redmine attachments will be stored which is different from the default 'files' directory of your Redmine instance using the @attachments_storage_path@ setting.
237
238
Examples:
239
240
 attachments_storage_path: /var/redmine/files
241
242
 attachments_storage_path: D:/redmine/files
243 130 Etienne Massip
244
h2. Logging configuration
245
246 101 T. Hauptman
Redmine defaults to a log level of :info, writing to the @log@ subdirectory. Depending on site usage, this can be a lot of data so to avoid the contents of the logfile growing without bound, consider rotating them, either through a system utility like @logrotate@ or via the @config/additional_environment.rb@ file.
247 21 Jean-Philippe Lang
248
To use the latter, copy @config/additional_environment.rb.example@ to @config/additional_environment.rb@ and add the following lines. Note that the new logger defaults to a high log level and hence has to be explicitly set to @info@.
249 123 Jean-Philippe Lang
<pre><code class="ruby">
250 21 Jean-Philippe Lang
#Logger.new(PATH,NUM_FILES_TO_ROTATE,FILE_SIZE)
251 95 Mischa The Evil
config.logger = Logger.new(config.log_path, 2, 1000000)
252 11 Jean-Philippe Lang
config.logger.level = Logger::INFO
253
</code></pre>
254
255
h2. Backups
256
257
Redmine backups should include:
258
* data (stored in your redmine database)
259
* attachments (stored in the @files@ directory of your Redmine install)
260
261
Here is a simple shell script that can be used for daily backups (assuming you're using a mysql database):
262
263
<pre>
264
# Database
265 55 Lukasz Slonina
/usr/bin/mysqldump -u <username> -p<password> <redmine_database> | gzip > /path/to/backup/db/redmine_`date +%y_%m_%d`.gz
266 11 Jean-Philippe Lang
267
# Attachments
268 1 Jean-Philippe Lang
rsync -a /path/to/redmine/files /path/to/backup/files
269
</pre>
270 69 Giuliano Simoncelli
271
h2. Notes on Windows installation
272
273
Get and install rubyinstaller from http://rubyforge.org. Form start menu select _Start Command Prompt with Ruby_
274
275
In the prompt follow the instruction given before
276
277
The commands:
278
279
<pre>
280
RAILS_ENV=production rake db:migrate
281
RAILS_ENV=production rake redmine:load_default_data
282
</pre>
283
284
has to be changed in 
285
286
<pre>
287
set RAILS_ENV=production
288
rake db:migrate
289 71 Giuliano Simoncelli
rake redmine:load_default_data
290 69 Giuliano Simoncelli
</pre>  
291
292 70 Giuliano Simoncelli
You may need to install install the mysql gem, with the command
293 69 Giuliano Simoncelli
294
<pre>
295
gem install mysql
296 1 Jean-Philippe Lang
</pre>
297
298
And in some case is required to copy the libmysql.dll file in your ruby/bin directory.
299
Not all libmysql.dll are ok this seem to works http://instantrails.rubyforge.org/svn/trunk/InstantRails-win/InstantRails/mysql/bin/libmySQL.dll
300 80 Jean-Philippe Lang
301
h2. Alternative to manual installation
302
303
Some users may prefer to skip manual installation by using one of the [[Download#Third-party-Redmine-bundles|third-party Redmine bundles]] on the download page.