Project

General

Profile

RedmineInstall » History » Version 140

Mischa The Evil, 2011-11-22 00:26
Roll-back to version 137 (undoing my changes from v138 and v139 since I'm not sure about the actual requirements after r7849 which raises rack to 1.1.2, rake to 0.9.2 and leaves i18n untouched at 0.4.2).

1 1 Jean-Philippe Lang
h1. Installing Redmine
2
3
{{>TOC}}
4 73 Liraz Siri
5 1 Jean-Philippe Lang
h2. Requirements
6
7 25 Jean-Philippe Lang
h3. Operating system
8 1 Jean-Philippe Lang
9 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]].
10 25 Jean-Philippe Lang
11 91 Kedar Mhaswade
h3. Ruby & Ruby on Rails & Rack
12 25 Jean-Philippe Lang
13 30 Jean-Philippe Lang
The required Ruby and Ruby on Rails versions for a given Redmine version is:
14 25 Jean-Philippe Lang
15 77 Anonymous
|_. Redmine version|_. Supported Ruby versions|_. Required Rails version|_. Required Rack version|
16 140 Mischa The Evil
|current trunk|ruby 1.8.6, 1.8.7|Rails 2.3.11|Rack 1.1.1|
17 118 Jean-Philippe Lang
|trunk from r2887 to r4903|ruby 1.8.6, 1.8.7|Rails 2.3.5|Rack 1.0.1|
18 77 Anonymous
|trunk from r2493 to r2886|ruby 1.8.6, 1.8.7|Rails 2.2.2||
19 1 Jean-Philippe Lang
|trunk before r2493|ruby 1.8.6, 1.8.7|Rails 2.1.2||
20 124 Etienne Massip
|1.2.x|ruby 1.8.6, 1.8.7|Rails 2.3.11|Rack 1.1.1|
21 113 Etienne Massip
|1.1.x|ruby 1.8.6, 1.8.7|Rails 2.3.5|Rack 1.0.1|
22 96 Felix Schäfer
|1.0.x|ruby 1.8.6, 1.8.7|Rails 2.3.5|Rack 1.0.1|
23 78 Jean-Philippe Lang
|0.9.x|ruby 1.8.6, 1.8.7|Rails 2.3.5|Rack 1.0.1|
24 77 Anonymous
|0.8.x|ruby 1.8.6, 1.8.7|Rails 2.1.2||
25 22 Jean-Philippe Lang
26 137 Etienne Massip
Official releases include the appropriate Rails version in their @vendor@ directory so you only need to make sure that you have the right Ruby/RubyGems/Rake/Rack stack installed.
27
28 1 Jean-Philippe Lang
If you checkout the source from the Redmine repository, you can install a specific Rails version on your machine by running:
29
30 123 Jean-Philippe Lang
  gem install rails -v=2.3.11
31 1 Jean-Philippe Lang
32
Install Rack:
33 125 Etienne Massip
34 137 Etienne Massip
  gem install rack -v=1.1.1
35 1 Jean-Philippe Lang
36 125 Etienne Massip
h3. Compatibility notes
37 1 Jean-Philippe Lang
38
* *Ruby 1.9 is not supported yet.* You _have_ to use Ruby 1.8.x as stated above.
39 140 Mischa The Evil
* *RubyGems* 1.3.7 or higher is required with following limitations :
40
** *Rails 2.3.5 will fail with RubyGems 1.5.0 or later*, stick to previous versions of RubyGems !
41
** *Rails 2.3.11 will fail with RubyGems 1.7.0 or later*, stick to previous versions of RubyGems !
42 128 Jean-Baptiste Barth
* *Rake 0.8.7 is required* (rake 0.9.x is not supported by Rails yet)
43 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.
44 125 Etienne Massip
* *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).
45 140 Mischa The Evil
* *I18n* 0.4.2 is required for Redmine >= 1.0.5
46
* *Rails* 2.3.11 to 2.3.14 suffer from a major issue with sending mails to multiple recipients, see #8751 for details and solution.
47
* *Rails* 2.3.14 is a minor security release known to work fine with Redmine 1.2.x series (except for previous point) and can be used as a replacement for 2.3.11 (read @config/environment.rb@ first).
48 1 Jean-Philippe Lang
49 25 Jean-Philippe Lang
h3. Database
50
51 93 Muntek Singh
* MySQL 5.0 or higher (recommended)
52 92 Knight Samar
53 68 Mischa The Evil
 * make sure to install the C bindings for Ruby that dramatically improve performance. You can get them by running @gem install mysql@. If you have problem installing the mysql gem refer "Rails Wiki pages":http://wiki.rubyonrails.org/database-support/mysql
54 35 Jean-Philippe Lang
55
* PostgreSQL 8
56 1 Jean-Philippe Lang
57 35 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";@
58 114 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
59 76 Randy Syring
 * make sure to install the PosgreSQL adapter for Ruby. You can get it by running (**one** of the following):
60 117 Etienne Massip
 **  @gem install postgres-pr@ (native Ruby implementation no more actively maintained by its author, presents "issues":https://github.com/mneumann/postgres-pr/issues#issue/4 with 9.x)
61 76 Randy Syring
 **  @gem install pg@ (works with SSL connections, may need development libraries/packages for your OS before it will compile)
62 114 Etienne Massip
 *** Ubuntu OS: development libraries can be installed with (or similar): @sudo aptitude install libdbd-pg-ruby1.8@
63 35 Jean-Philippe Lang
64
* SQLite 3
65 26 Jean-Philippe Lang
66 25 Jean-Philippe Lang
h3. Optional components
67 23 Jean-Philippe Lang
68 25 Jean-Philippe Lang
      * SCM binaries (eg. @svn@), for repository browsing (must be available in your PATH). See [[RedmineRepositories]] for SCM compatibility and requirements.
69
      * "RMagick":http://rmagick.rubyforge.org/ (to enable Gantt export to png image)
70 56 Eric Davis
      * "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.
71 1 Jean-Philippe Lang
72 129 Etienne Massip
h2. Redmine Version
73 107 Muntek Singh
74 130 Etienne Massip
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.
75 107 Muntek Singh
76 129 Etienne Massip
h2. Installation procedure
77 1 Jean-Philippe Lang
78 111 Jean-Philippe Lang
1. Get the Redmine source code by either downloading a packaged release or checking out the code repository. See [[Download]].
79 6 Jean-Philippe Lang
80 36 Yclept Nemo
2. Create an empty database and accompanying user named @redmine@ for example.
81 6 Jean-Philippe Lang
82
For MySQL:
83 1 Jean-Philippe Lang
84 38 Yclept Nemo
<pre>
85 39 Yclept Nemo
create database redmine character set utf8;
86
create user 'redmine'@'localhost' identified by 'my_password';
87
grant all privileges on redmine.* to 'redmine'@'localhost';
88 38 Yclept Nemo
</pre>
89 1 Jean-Philippe Lang
90 88 Sean Farrell
For versions of MySQL prior to 5.0.2 - skip the 'create user' step and instead:
91
<pre>
92
grant all privileges on redmine.* to 'redmine'@'localhost' identified by 'my_password';
93
</pre>
94
95 63 Thanos Kyritsis
For PostgreSQL:
96
97
<pre>
98
CREATE ROLE redmine LOGIN ENCRYPTED PASSWORD 'my_password' NOINHERIT VALID UNTIL 'infinity';
99 64 Thanos Kyritsis
CREATE DATABASE redmine WITH ENCODING='UTF8' OWNER=redmine;
100 63 Thanos Kyritsis
</pre>
101
102 3 Jean-Philippe Lang
3. Copy @config/database.yml.example@ to @config/database.yml@ and edit this file in order to configure your database settings for "production" environment.
103 1 Jean-Philippe Lang
104 14 Jean-Philippe Lang
Example for a MySQL database:
105
106
<pre>
107
production:
108
  adapter: mysql
109
  database: redmine
110
  host: localhost
111 40 Yclept Nemo
  username: redmine
112
  password: my_password
113 3 Jean-Philippe Lang
</pre>
114
115 54 Barbara Post
If your server is not running on the standard port (3306), use this configuration instead:
116
117
<pre>
118
production:
119
  adapter: mysql
120
  database: redmine
121
  host: localhost
122
  port: 3307
123
  username: redmine
124
  password: my_password
125
</pre>
126
127
128
Example for a PostgreSQL database (default port):
129 44 Alexey Lustin
130
<pre>
131
production:
132
  adapter: postgresql
133
  database: <your_database_name>
134
  host: <postgres_host>
135
  username: <postgres_user>
136 46 Istvan DEMETER
  password: <postgres_user_password>
137 1 Jean-Philippe Lang
  encoding: utf8
138 44 Alexey Lustin
  schema_search_path: <database_schema> (default - public)
139
</pre>
140
141 111 Jean-Philippe Lang
4. Generate a session store secret.
142 1 Jean-Philippe Lang
143 82 Simon Carpinter
   rake generate_session_store
144
145 41 Yclept Nemo
5. Create the database structure, by running the following command under the application root directory:
146
147 62 Vladimir L
  RAILS_ENV=production rake db:migrate
148 1 Jean-Philippe Lang
149 90 Jiongliang Zhang
150 1 Jean-Philippe Lang
It will create tables and an administrator account.
151 90 Jiongliang Zhang
152
If you get this error: 
153
<pre>
154
Rake aborted!
155
no such file to load -- net/https
156
</pre>
157
158 114 Etienne Massip
you need to install libopenssl-ruby1.8, in Ubuntu, just like this: apt-get install libopenssl-ruby1.8
159 1 Jean-Philippe Lang
160 41 Yclept Nemo
6. Insert default configuration data in database, by running the following command:
161 1 Jean-Philippe Lang
162 62 Vladimir L
  RAILS_ENV=production rake redmine:load_default_data
163 32 Jean-Philippe Lang
164
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.
165
166
7. Setting up permissions
167
168 14 Jean-Philippe Lang
NB: _Windows users have to skip this section._
169
170
The user who runs Redmine must have write permission on the following subdirectories: @files@, @log@, @tmp@ (create the last one if not present).
171
172
Assuming you run Redmine with a @redmine@ user:
173
174 31 Eric Davis
<pre>
175 1 Jean-Philippe Lang
mkdir tmp public/plugin_assets
176 31 Eric Davis
sudo chown -R redmine:redmine files log tmp public/plugin_assets
177 14 Jean-Philippe Lang
sudo chmod -R 755 files log tmp public/plugin_assets
178
</pre>
179 1 Jean-Philippe Lang
180 32 Jean-Philippe Lang
8. Test the installation by running WEBrick web server:
181 1 Jean-Philippe Lang
182 33 Jean-Philippe Lang
  ruby script/server webrick -e production
183 1 Jean-Philippe Lang
184 14 Jean-Philippe Lang
Once WEBrick has started, point your browser to http://localhost:3000/. You should now see the application welcome page.
185 1 Jean-Philippe Lang
186 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. 
187
188 32 Jean-Philippe Lang
9. Use default administrator account to log in:
189 1 Jean-Philippe Lang
190
    * login: admin
191 14 Jean-Philippe Lang
    * password: admin
192 1 Jean-Philippe Lang
193
You can go to @Admin & Settings@ to modify application settings.
194
195 130 Etienne Massip
h2. Configuration
196 1 Jean-Philippe Lang
197 131 Etienne Massip
Since of version:1.2.0, Redmine settings are defined in a file named @config/configuration.yml@.
198 130 Etienne Massip
199 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.
200 1 Jean-Philippe Lang
201 131 Etienne Massip
This settings may be defined per Rails environment (@production@/@development@/@test@).
202
203
+Important+ : don't forget to restart the application after any change.
204
205 130 Etienne Massip
h3. Email / SMTP server settings
206
207 132 Etienne Massip
Email configuration is described in a [[EmailConfiguration|dedicated page]].
208 1 Jean-Philippe Lang
209
h3. SCM settings
210
211 133 Etienne Massip
This configuration section allows you to:
212 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)
213
* specify the full path to the binary
214
215 133 Etienne Massip
Examples (with Subversion):
216 131 Etienne Massip
217 133 Etienne Massip
Command name override:
218 131 Etienne Massip
219
 scm_subversion_command: "svn_replacement.exe"
220
221 133 Etienne Massip
Absolute path:
222 1 Jean-Philippe Lang
223
 scm_subversion_command: "C:\Program Files\Subversion\bin\svn.exe"
224
225
h3. Attachment storage settings
226
227 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.
228
229
Examples:
230
231
 attachments_storage_path: /var/redmine/files
232
233
 attachments_storage_path: D:/redmine/files
234 130 Etienne Massip
235
h2. Logging configuration
236
237 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.
238 21 Jean-Philippe Lang
239
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@.
240 123 Jean-Philippe Lang
<pre><code class="ruby">
241 21 Jean-Philippe Lang
#Logger.new(PATH,NUM_FILES_TO_ROTATE,FILE_SIZE)
242 95 Mischa The Evil
config.logger = Logger.new(config.log_path, 2, 1000000)
243 11 Jean-Philippe Lang
config.logger.level = Logger::INFO
244
</code></pre>
245
246
h2. Backups
247
248
Redmine backups should include:
249
* data (stored in your redmine database)
250
* attachments (stored in the @files@ directory of your Redmine install)
251
252
Here is a simple shell script that can be used for daily backups (assuming you're using a mysql database):
253
254
<pre>
255
# Database
256 55 Lukasz Slonina
/usr/bin/mysqldump -u <username> -p<password> <redmine_database> | gzip > /path/to/backup/db/redmine_`date +%y_%m_%d`.gz
257 11 Jean-Philippe Lang
258
# Attachments
259 1 Jean-Philippe Lang
rsync -a /path/to/redmine/files /path/to/backup/files
260
</pre>
261 69 Giuliano Simoncelli
262
h2. Notes on Windows installation
263
264
Get and install rubyinstaller from http://rubyforge.org. Form start menu select _Start Command Prompt with Ruby_
265
266
In the prompt follow the instruction given before
267
268
The commands:
269
270
<pre>
271
RAILS_ENV=production rake db:migrate
272
RAILS_ENV=production rake redmine:load_default_data
273
</pre>
274
275
has to be changed in 
276
277
<pre>
278
set RAILS_ENV=production
279
rake db:migrate
280 71 Giuliano Simoncelli
rake redmine:load_default_data
281 69 Giuliano Simoncelli
</pre>  
282
283 70 Giuliano Simoncelli
You may need to install install the mysql gem, with the command
284 69 Giuliano Simoncelli
285
<pre>
286
gem install mysql
287 1 Jean-Philippe Lang
</pre>
288
289
And in some case is required to copy the libmysql.dll file in your ruby/bin directory.
290
Not all libmysql.dll are ok this seem to works http://instantrails.rubyforge.org/svn/trunk/InstantRails-win/InstantRails/mysql/bin/libmySQL.dll
291 80 Jean-Philippe Lang
292
h2. Alternative to manual installation
293
294
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.