Project

General

Profile

RedmineInstall » History » Version 153

Jean-Philippe Lang, 2012-06-09 12:21
Rails version is now 3.2.5

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 153 Jean-Philippe Lang
|current trunk|ruby 1.8.7, 1.9.2, 1.9.3, jruby-1.6.7|Rails 3.2.5|RubyGems <= 1.8|
19
|2.0.2|ruby 1.8.7, 1.9.2, 1.9.3, jruby-1.6.7|Rails 3.2.5|RubyGems <= 1.8|
20
|2.0.0, 2.0.1|ruby 1.8.7, 1.9.2, 1.9.3, jruby-1.6.7|Rails 3.2.3|RubyGems <= 1.8|
21 147 Jean-Philippe Lang
|1.4.x|ruby 1.8.7, 1.9.2, 1.9.3, jruby-1.6.7|Rails 2.3.14|RubyGems <= 1.8|
22 1 Jean-Philippe Lang
23 125 Etienne Massip
h3. Compatibility notes
24 140 Mischa The Evil
25
* *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).
26 25 Jean-Philippe Lang
27 93 Muntek Singh
h3. Database
28 92 Knight Samar
29 146 Etienne Massip
* MySQL 5.0 or higher (recommended)
30 35 Jean-Philippe Lang
31
 * 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
32 1 Jean-Philippe Lang
33 147 Jean-Philippe Lang
* PostgreSQL 8 or higher
34 117 Etienne Massip
35 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";@
36 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
37 1 Jean-Philippe Lang
38
* SQLite 3
39
40
h3. Optional components
41
42
      * SCM binaries (eg. @svn@), for repository browsing (must be available in your PATH). See [[RedmineRepositories]] for SCM compatibility and requirements.
43
      * "RMagick":http://rmagick.rubyforge.org/ (to enable Gantt export to png image)
44
      * "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.
45
46
h2. Redmine Version
47
48
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.
49
50 114 Etienne Massip
h2. Installation procedure
51 35 Jean-Philippe Lang
52
1. Get the Redmine source code by either downloading a packaged release or checking out the code repository. See [[Download]].
53 26 Jean-Philippe Lang
54 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:
55 23 Jean-Philippe Lang
56 147 Jean-Philippe Lang
  gem install bundler
57
58
Then you can install all the gems required by Redmine using the following command:
59
60
  bundle install --without development test
61
62
If ImageMagick is not installed on your system, you should skip the installation of the rmagick gem using: @`bundle install --without development test rmagick`@.
63
64 152 Etienne Massip
Sidenote concerning the installation of @rmagick@ on Windows:
65
66
>At the time of writing, there is little chance that the @rmagick@ gem installation (if not yet installed), go through fine when running the @bundle install@ command; you'll find some help [[HowTo_install_rmagick_gem_on_Windows|here]] .
67
68 147 Jean-Philippe Lang
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`@.
69
70 150 Mischa The Evil
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`. Example:
71 149 Jean-Philippe Lang
72
<pre>
73
# Gemfile.local
74
gem "mongrel"
75
</pre>
76 147 Jean-Philippe Lang
77
3. Create an empty database and accompanying user named @redmine@ for example.
78
79 1 Jean-Philippe Lang
For MySQL:
80
81 38 Yclept Nemo
<pre>
82 39 Yclept Nemo
create database redmine character set utf8;
83
create user 'redmine'@'localhost' identified by 'my_password';
84
grant all privileges on redmine.* to 'redmine'@'localhost';
85 38 Yclept Nemo
</pre>
86 1 Jean-Philippe Lang
87 88 Sean Farrell
For versions of MySQL prior to 5.0.2 - skip the 'create user' step and instead:
88
<pre>
89
grant all privileges on redmine.* to 'redmine'@'localhost' identified by 'my_password';
90 1 Jean-Philippe Lang
</pre>
91
92
For PostgreSQL:
93
94
<pre>
95
CREATE ROLE redmine LOGIN ENCRYPTED PASSWORD 'my_password' NOINHERIT VALID UNTIL 'infinity';
96
CREATE DATABASE redmine WITH ENCODING='UTF8' OWNER=redmine;
97
</pre>
98
99 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.
100 1 Jean-Philippe Lang
101 147 Jean-Philippe Lang
Example for a MySQL database using ruby1.8 or jruby:
102 88 Sean Farrell
103 63 Thanos Kyritsis
<pre>
104
production:
105
  adapter: mysql
106
  database: redmine
107 64 Thanos Kyritsis
  host: localhost
108 63 Thanos Kyritsis
  username: redmine
109 3 Jean-Philippe Lang
  password: my_password
110 1 Jean-Philippe Lang
</pre>
111 14 Jean-Philippe Lang
112 147 Jean-Philippe Lang
Example for a MySQL database using ruby1.9 (adapter must be set to @mysql2@):
113
114
<pre>
115
production:
116
  adapter: mysql2
117
  database: redmine
118
  host: localhost
119
  username: redmine
120
  password: my_password
121
</pre>
122
123 54 Barbara Post
If your server is not running on the standard port (3306), use this configuration instead:
124
125
<pre>
126 1 Jean-Philippe Lang
production:
127 54 Barbara Post
  adapter: mysql
128
  database: redmine
129 1 Jean-Philippe Lang
  host: localhost
130 54 Barbara Post
  port: 3307
131
  username: redmine
132
  password: my_password
133
</pre>
134
135 44 Alexey Lustin
136
Example for a PostgreSQL database (default port):
137
138
<pre>
139
production:
140
  adapter: postgresql
141
  database: <your_database_name>
142 46 Istvan DEMETER
  host: <postgres_host>
143 1 Jean-Philippe Lang
  username: <postgres_user>
144
  password: <postgres_user_password>
145
  encoding: utf8
146
  schema_search_path: <database_schema> (default - public)
147
</pre>
148
149
5. Generate a session store secret.
150
151 151 Jean-Philippe Lang
* with Redmine 1.4.x:
152 1 Jean-Philippe Lang
153 151 Jean-Philippe Lang
<pre>
154
rake generate_session_store
155
</pre>
156
157
* with Redmine 2.x:
158
159
<pre>
160
rake generate_secret_token
161
</pre>
162
163 147 Jean-Philippe Lang
6. Create the database structure, by running the following command under the application root directory:
164 1 Jean-Philippe Lang
165 90 Jiongliang Zhang
  RAILS_ENV=production rake db:migrate
166 1 Jean-Philippe Lang
167 90 Jiongliang Zhang
168
It will create tables and an administrator account.
169
170
If you get this error: 
171 1 Jean-Philippe Lang
<pre>
172 90 Jiongliang Zhang
Rake aborted!
173
no such file to load -- net/https
174
</pre>
175 114 Etienne Massip
176 1 Jean-Philippe Lang
you need to install libopenssl-ruby1.8, in Ubuntu, just like this: apt-get install libopenssl-ruby1.8
177 41 Yclept Nemo
178 147 Jean-Philippe Lang
7. Insert default configuration data in database, by running the following command:
179 1 Jean-Philippe Lang
180 62 Vladimir L
  RAILS_ENV=production rake redmine:load_default_data
181 32 Jean-Philippe Lang
182
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.
183
184 147 Jean-Philippe Lang
8. Setting up permissions
185 32 Jean-Philippe Lang
186 14 Jean-Philippe Lang
NB: _Windows users have to skip this section._
187
188
The user who runs Redmine must have write permission on the following subdirectories: @files@, @log@, @tmp@ (create the last one if not present).
189
190 1 Jean-Philippe Lang
Assuming you run Redmine with a @redmine@ user:
191
192
<pre>
193
mkdir tmp public/plugin_assets
194
sudo chown -R redmine:redmine files log tmp public/plugin_assets
195
sudo chmod -R 755 files log tmp public/plugin_assets
196
</pre>
197
198
9. Test the installation by running WEBrick web server:
199
200 151 Jean-Philippe Lang
* with Redmine 1.4.x:
201
202
<pre>
203
ruby script/server webrick -e production
204
</pre>
205
206
* with Redmine 2.x:
207
208
<pre>
209
ruby script/rails server webrick -e production
210
</pre>
211 1 Jean-Philippe Lang
212 14 Jean-Philippe Lang
Once WEBrick has started, point your browser to http://localhost:3000/. You should now see the application welcome page.
213 1 Jean-Philippe Lang
214 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. 
215
216 147 Jean-Philippe Lang
10. Use default administrator account to log in:
217 1 Jean-Philippe Lang
218
    * login: admin
219 14 Jean-Philippe Lang
    * password: admin
220 1 Jean-Philippe Lang
221
You can go to @Admin & Settings@ to modify application settings.
222
223 130 Etienne Massip
h2. Configuration
224 1 Jean-Philippe Lang
225 131 Etienne Massip
Since of version:1.2.0, Redmine settings are defined in a file named @config/configuration.yml@.
226 130 Etienne Massip
227 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.
228 1 Jean-Philippe Lang
229 131 Etienne Massip
This settings may be defined per Rails environment (@production@/@development@/@test@).
230
231
+Important+ : don't forget to restart the application after any change.
232
233 130 Etienne Massip
h3. Email / SMTP server settings
234
235 132 Etienne Massip
Email configuration is described in a [[EmailConfiguration|dedicated page]].
236 1 Jean-Philippe Lang
237
h3. SCM settings
238
239 133 Etienne Massip
This configuration section allows you to:
240 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)
241
* specify the full path to the binary
242
243 133 Etienne Massip
Examples (with Subversion):
244 131 Etienne Massip
245 133 Etienne Massip
Command name override:
246 131 Etienne Massip
247
 scm_subversion_command: "svn_replacement.exe"
248
249 133 Etienne Massip
Absolute path:
250 1 Jean-Philippe Lang
251
 scm_subversion_command: "C:\Program Files\Subversion\bin\svn.exe"
252
253
h3. Attachment storage settings
254
255 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.
256
257
Examples:
258
259
 attachments_storage_path: /var/redmine/files
260
261
 attachments_storage_path: D:/redmine/files
262 130 Etienne Massip
263
h2. Logging configuration
264
265 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.
266 21 Jean-Philippe Lang
267
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@.
268 123 Jean-Philippe Lang
<pre><code class="ruby">
269 21 Jean-Philippe Lang
#Logger.new(PATH,NUM_FILES_TO_ROTATE,FILE_SIZE)
270 95 Mischa The Evil
config.logger = Logger.new(config.log_path, 2, 1000000)
271 11 Jean-Philippe Lang
config.logger.level = Logger::INFO
272
</code></pre>
273
274
h2. Backups
275
276
Redmine backups should include:
277
* data (stored in your redmine database)
278
* attachments (stored in the @files@ directory of your Redmine install)
279
280
Here is a simple shell script that can be used for daily backups (assuming you're using a mysql database):
281
282
<pre>
283
# Database
284 55 Lukasz Slonina
/usr/bin/mysqldump -u <username> -p<password> <redmine_database> | gzip > /path/to/backup/db/redmine_`date +%y_%m_%d`.gz
285 11 Jean-Philippe Lang
286
# Attachments
287 1 Jean-Philippe Lang
rsync -a /path/to/redmine/files /path/to/backup/files
288
</pre>
289 69 Giuliano Simoncelli
290
h2. Notes on Windows installation
291
292
Get and install rubyinstaller from http://rubyforge.org. Form start menu select _Start Command Prompt with Ruby_
293
294
In the prompt follow the instruction given before
295
296
The commands:
297
298
<pre>
299
RAILS_ENV=production rake db:migrate
300
RAILS_ENV=production rake redmine:load_default_data
301
</pre>
302
303
has to be changed in 
304
305
<pre>
306
set RAILS_ENV=production
307
rake db:migrate
308 71 Giuliano Simoncelli
rake redmine:load_default_data
309 69 Giuliano Simoncelli
</pre>  
310
311 70 Giuliano Simoncelli
You may need to install install the mysql gem, with the command
312 69 Giuliano Simoncelli
313
<pre>
314
gem install mysql
315 1 Jean-Philippe Lang
</pre>
316
317
And in some case is required to copy the libmysql.dll file in your ruby/bin directory.
318
Not all libmysql.dll are ok this seem to works http://instantrails.rubyforge.org/svn/trunk/InstantRails-win/InstantRails/mysql/bin/libmySQL.dll
319 80 Jean-Philippe Lang
320
h2. Alternative to manual installation
321
322
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.