Project

General

Profile

RedmineInstall » History » Version 122

Etienne Massip, 2011-05-25 12:19
RubyGems compatibility limitations update

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 121 Etienne Massip
|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
|trunk before r2493|ruby 1.8.6, 1.8.7|Rails 2.1.2||
20 113 Etienne Massip
|1.1.x|ruby 1.8.6, 1.8.7|Rails 2.3.5|Rack 1.0.1|
21 96 Felix Schäfer
|1.0.x|ruby 1.8.6, 1.8.7|Rails 2.3.5|Rack 1.0.1|
22 78 Jean-Philippe Lang
|0.9.x|ruby 1.8.6, 1.8.7|Rails 2.3.5|Rack 1.0.1|
23 77 Anonymous
|0.8.x|ruby 1.8.6, 1.8.7|Rails 2.1.2||
24 22 Jean-Philippe Lang
25
Official releases include the appropriate Rails version in their @vendor@ directory. So no particular action is needed.
26 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:
27
28 78 Jean-Philippe Lang
  gem install rails -v=2.3.5
29 1 Jean-Philippe Lang
30 91 Kedar Mhaswade
Install Rack:
31
 
32
  gem install rack -v=1.0.1
33
34 28 Jean-Philippe Lang
Notes:
35 94 Felix Schäfer
* *Ruby 1.9 is not supported yet.* You _have_ to use Ruby 1.8.x as stated above.
36 122 Etienne Massip
* RubyGems 1.3.1 or higher is required with following limitations :
37
** *Rails 2.3.5 will fail with RubyGems 1.5.0 or later*, stick to previous versions of RubyGems !
38
** *Rails 2.3.11 will fail with RubyGems 1.7.0 or later*, stick to previous versions of RubyGems !
39 97 Holger Just
* Rake 0.8.3 or higher is required
40 91 Kedar Mhaswade
* Rack 1.0.1 is required. If you don't have this exact version, database migration would fail.
41 111 Jean-Philippe Lang
* I18n 0.4.2 is required for Redmine >= 1.0.5
42 1 Jean-Philippe Lang
43 25 Jean-Philippe Lang
h3. Database
44
45 93 Muntek Singh
* MySQL 5.0 or higher (recommended)
46 92 Knight Samar
47 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
48 35 Jean-Philippe Lang
49
* PostgreSQL 8
50 1 Jean-Philippe Lang
51 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";@
52 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
53 76 Randy Syring
 * make sure to install the PosgreSQL adapter for Ruby. You can get it by running (**one** of the following):
54 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)
55 76 Randy Syring
 **  @gem install pg@ (works with SSL connections, may need development libraries/packages for your OS before it will compile)
56 114 Etienne Massip
 *** Ubuntu OS: development libraries can be installed with (or similar): @sudo aptitude install libdbd-pg-ruby1.8@
57 35 Jean-Philippe Lang
58
* SQLite 3
59 26 Jean-Philippe Lang
60 25 Jean-Philippe Lang
h3. Optional components
61 23 Jean-Philippe Lang
62 25 Jean-Philippe Lang
      * SCM binaries (eg. @svn@), for repository browsing (must be available in your PATH). See [[RedmineRepositories]] for SCM compatibility and requirements.
63
      * "RMagick":http://rmagick.rubyforge.org/ (to enable Gantt export to png image)
64 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.
65 1 Jean-Philippe Lang
66 107 Muntek Singh
h2. RedMine Version
67
68 114 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.
69 107 Muntek Singh
70 8 Thomas Lecavelier
h2. Installation
71 1 Jean-Philippe Lang
72 111 Jean-Philippe Lang
1. Get the Redmine source code by either downloading a packaged release or checking out the code repository. See [[Download]].
73 6 Jean-Philippe Lang
74 36 Yclept Nemo
2. Create an empty database and accompanying user named @redmine@ for example.
75 6 Jean-Philippe Lang
76
For MySQL:
77 1 Jean-Philippe Lang
78 38 Yclept Nemo
<pre>
79 39 Yclept Nemo
create database redmine character set utf8;
80
create user 'redmine'@'localhost' identified by 'my_password';
81
grant all privileges on redmine.* to 'redmine'@'localhost';
82 38 Yclept Nemo
</pre>
83 1 Jean-Philippe Lang
84 88 Sean Farrell
For versions of MySQL prior to 5.0.2 - skip the 'create user' step and instead:
85
<pre>
86
grant all privileges on redmine.* to 'redmine'@'localhost' identified by 'my_password';
87
</pre>
88
89 63 Thanos Kyritsis
For PostgreSQL:
90
91
<pre>
92
CREATE ROLE redmine LOGIN ENCRYPTED PASSWORD 'my_password' NOINHERIT VALID UNTIL 'infinity';
93 64 Thanos Kyritsis
CREATE DATABASE redmine WITH ENCODING='UTF8' OWNER=redmine;
94 63 Thanos Kyritsis
</pre>
95
96 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.
97 1 Jean-Philippe Lang
98 14 Jean-Philippe Lang
Example for a MySQL database:
99
100
<pre>
101
production:
102
  adapter: mysql
103
  database: redmine
104
  host: localhost
105 40 Yclept Nemo
  username: redmine
106
  password: my_password
107 3 Jean-Philippe Lang
</pre>
108
109 54 Barbara Post
If your server is not running on the standard port (3306), use this configuration instead:
110
111
<pre>
112
production:
113
  adapter: mysql
114
  database: redmine
115
  host: localhost
116
  port: 3307
117
  username: redmine
118
  password: my_password
119
</pre>
120
121
122
Example for a PostgreSQL database (default port):
123 44 Alexey Lustin
124
<pre>
125
production:
126
  adapter: postgresql
127
  database: <your_database_name>
128
  host: <postgres_host>
129
  username: <postgres_user>
130 46 Istvan DEMETER
  password: <postgres_user_password>
131 1 Jean-Philippe Lang
  encoding: utf8
132 44 Alexey Lustin
  schema_search_path: <database_schema> (default - public)
133
</pre>
134
135 111 Jean-Philippe Lang
4. Generate a session store secret.
136 1 Jean-Philippe Lang
137 82 Simon Carpinter
   rake generate_session_store
138
139 41 Yclept Nemo
5. Create the database structure, by running the following command under the application root directory:
140
141 62 Vladimir L
  RAILS_ENV=production rake db:migrate
142 1 Jean-Philippe Lang
143 90 Jiongliang Zhang
144 1 Jean-Philippe Lang
It will create tables and an administrator account.
145 90 Jiongliang Zhang
146
If you get this error: 
147
<pre>
148
Rake aborted!
149
no such file to load -- net/https
150
</pre>
151
152 114 Etienne Massip
you need to install libopenssl-ruby1.8, in Ubuntu, just like this: apt-get install libopenssl-ruby1.8
153 1 Jean-Philippe Lang
154 41 Yclept Nemo
6. Insert default configuration data in database, by running the following command:
155 1 Jean-Philippe Lang
156 62 Vladimir L
  RAILS_ENV=production rake redmine:load_default_data
157 32 Jean-Philippe Lang
158
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.
159
160
7. Setting up permissions
161
162 14 Jean-Philippe Lang
NB: _Windows users have to skip this section._
163
164
The user who runs Redmine must have write permission on the following subdirectories: @files@, @log@, @tmp@ (create the last one if not present).
165
166
Assuming you run Redmine with a @redmine@ user:
167
168 31 Eric Davis
<pre>
169 1 Jean-Philippe Lang
mkdir tmp public/plugin_assets
170 31 Eric Davis
sudo chown -R redmine:redmine files log tmp public/plugin_assets
171 14 Jean-Philippe Lang
sudo chmod -R 755 files log tmp public/plugin_assets
172
</pre>
173 1 Jean-Philippe Lang
174 32 Jean-Philippe Lang
8. Test the installation by running WEBrick web server:
175 1 Jean-Philippe Lang
176 33 Jean-Philippe Lang
  ruby script/server webrick -e production
177 1 Jean-Philippe Lang
178 14 Jean-Philippe Lang
Once WEBrick has started, point your browser to http://localhost:3000/. You should now see the application welcome page.
179 1 Jean-Philippe Lang
180 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. 
181
182 32 Jean-Philippe Lang
9. Use default administrator account to log in:
183 1 Jean-Philippe Lang
184
    * login: admin
185 14 Jean-Philippe Lang
    * password: admin
186 1 Jean-Philippe Lang
187
You can go to @Admin & Settings@ to modify application settings.
188
189 101 T. Hauptman
h2. Logger Configuration
190
191
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.
192
193 106 Felix Schäfer
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@.
194
<pre><code class="ruby">
195 1 Jean-Philippe Lang
#Logger.new(PATH,NUM_FILES_TO_ROTATE,FILE_SIZE)
196 101 T. Hauptman
config.logger = Logger.new(config.log_path, 2, 1000000)
197 106 Felix Schäfer
config.logger.level = Logger::INFO
198
</code></pre>
199 101 T. Hauptman
200 21 Jean-Philippe Lang
h2. SMTP server Configuration
201
202 66 Henry Bernard
Copy @config/email.yml.example@ to @config/email.yml@ and edit this file to adjust your SMTP settings.
203 21 Jean-Philippe Lang
204 95 Mischa The Evil
See the [[EmailConfiguration|email configuration]] examples.
205 11 Jean-Philippe Lang
206
Don't forget to restart the application after any change.
207
208
h2. Backups
209
210
Redmine backups should include:
211
* data (stored in your redmine database)
212
* attachments (stored in the @files@ directory of your Redmine install)
213
214
Here is a simple shell script that can be used for daily backups (assuming you're using a mysql database):
215
216
<pre>
217
# Database
218 55 Lukasz Slonina
/usr/bin/mysqldump -u <username> -p<password> <redmine_database> | gzip > /path/to/backup/db/redmine_`date +%y_%m_%d`.gz
219 11 Jean-Philippe Lang
220
# Attachments
221 1 Jean-Philippe Lang
rsync -a /path/to/redmine/files /path/to/backup/files
222
</pre>
223 69 Giuliano Simoncelli
224
h2. Notes on Windows installation
225
226
Get and install rubyinstaller from http://rubyforge.org. Form start menu select _Start Command Prompt with Ruby_
227
228
In the prompt follow the instruction given before
229
230
The commands:
231
232
<pre>
233
RAILS_ENV=production rake db:migrate
234
RAILS_ENV=production rake redmine:load_default_data
235
</pre>
236
237
has to be changed in 
238
239
<pre>
240
set RAILS_ENV=production
241
rake db:migrate
242 71 Giuliano Simoncelli
rake redmine:load_default_data
243 69 Giuliano Simoncelli
</pre>  
244
245 70 Giuliano Simoncelli
You may need to install install the mysql gem, with the command
246 69 Giuliano Simoncelli
247
<pre>
248
gem install mysql
249 1 Jean-Philippe Lang
</pre>
250
251
And in some case is required to copy the libmysql.dll file in your ruby/bin directory.
252
Not all libmysql.dll are ok this seem to works http://instantrails.rubyforge.org/svn/trunk/InstantRails-win/InstantRails/mysql/bin/libmySQL.dll
253 80 Jean-Philippe Lang
254
h2. Alternative to manual installation
255
256
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.