Project

General

Profile

HowTo Install Redmine in a sub-URI on Windows with Apache » History » Version 4

Jack Kurzecki, 2010-02-03 11:01
Provided some information on issues that might be encountered and added links to a forum thread with known issues

1 1 Jack Kurzecki
h1. HowTo Install Redmine in a sub-URI on Windows with Apache
2
3
{{>toc}}
4
5 3 Jack Kurzecki
bq. Following the steps below exactly as listed will produce a working *Redmine 0.9.1* installation hosted under *http://localhost/redmine* sub-URI on Windows XP/2003/2008 x86/x64 with Apache HTTP Server 2.2.x, MySQL 5.1.x, PHP 5.3.x and Ruby 1.8.7.
6
This walk-through also applies to installation of the latest Redmine revision. It was tested with *Redmine revision r3357*.
7 2 Jack Kurzecki
The intended audience for this walk-through are Windows users.
8 1 Jack Kurzecki
9 4 Jack Kurzecki
+In case you encounter problems, please look at "*this forum thread*":http://www.redmine.org/boards/1/topics/10162 for information about some known issues and their workarounds+
10
11 1 Jack Kurzecki
h2. Install Apache HTTP server 2.2.x
12
13 3 Jack Kurzecki
# Download *"Win32 Binary without crypto (no mod_ssl) (MSI Installer)"* or *"Win32 Binary including OpenSSL (MSI Installer)"*, depending if you intend to use SSL on your webserver, from "here":http://httpd.apache.org/download.cgi
14
# Install to *C:\webserver\apache*
15 1 Jack Kurzecki
16
h2. Install MySQL 5.1.x
17
18 3 Jack Kurzecki
# Download *"Windows (x86, 32-bit), MSI Installer"* from "here":http://dev.mysql.com/downloads/mysql/5.1.html#win32
19
#* _(the *64-bit* version could be installed on x64 Windows platforms, but the *32-bit* version is +recommended+ and it works well on both x86 and x64 versions of Windows.)_
20 4 Jack Kurzecki
#* _If you decide to go with the 64-bit version, you might get errors later in the setup that can be fixed by copying a specific version of *libmySQL.dll* into "Ruby/bin" folder. For details refer to "*this thread*_":http://www.redmine.org/boards/1/topics/10162
21 3 Jack Kurzecki
# Install to *C:\webserver\MySQL*
22
#* During setup:
23
#*# set +default character set+ to *UTF8*
24
#*# select "Include Bin Directory in Windows PATH"
25 1 Jack Kurzecki
#*# (_optional:_) set data files installation directory to *C:\webserver\MySQLData*
26
27 4 Jack Kurzecki
h2. Install -MySQL GUI Tools for MySQL 5.0- MySQL Workbench 5.x.x
28 1 Jack Kurzecki
29 4 Jack Kurzecki
* _(EOL was announced for the "MySQL GUI Tools for MySQL 5.0", but it can still be used)_
30 1 Jack Kurzecki
31 4 Jack Kurzecki
# Download -"Windows (x86)" from "here":http://dev.mysql.com/downloads/gui-tools/5.0.html- *"Windows (x86, 32-bit), MSI Installer"* from "here":http://dev.mysql.com/downloads/workbench/
32
# Install to -C:\webserver\MySQL_GUI_Tools- *C:\webserver\MySQL_Workbench*
33
34 1 Jack Kurzecki
h2. Install PHP 5.3.x
35
36
# Download *"VC6 x86 Thread Safe Installer"* from "here":http://windows.php.net/download/
37
# Install to *C:\webserver\PHP*
38 4 Jack Kurzecki
#* During setup:
39
#*# include *Curl* plugin
40
#*# (_optional:_) include *LDAP* plugin
41
#*# *DO NOT* include any MSSQL plugins, because they are not included in the installer package and you will encounter errors about missing DLLs when you try to restart Apache server later in this HowTo. _(bug present in PHP 5.3.1 installer)_
42 1 Jack Kurzecki
43
h2. Install Ruby 1.8.7
44 3 Jack Kurzecki
45
* _At the time of writing this document the latest version of Ruby was 1.9.1, however for best compatibility use +Ruby version 1.8.7+._
46 1 Jack Kurzecki
* Since there is no Ruby Installer Package for Windows version 1.8.7 at this time, +we will first install 1.8.6+ then +copy 1.8.7 binaries on top of it+.
47 3 Jack Kurzecki
48
# Download *"rubyinstaller-1.8.6-p383-rc1.exe"* from "here":http://rubyforge.org/frs/?group_id=167
49
# Install to *C:\webserver\ruby*
50 1 Jack Kurzecki
# During setup, select *"Add Ruby executables to your PATH"*
51
# Open command window, then execue: <pre>
52
mkdir C:\webserver\railsapps
53
cd C:\webserver\railsapps
54
gem list
55
gem uninstall rails
56
gem uninstall actionmailer
57
gem uninstall actionpack
58
gem uninstall activerecord
59
gem uninstall activeresource
60 3 Jack Kurzecki
gem uninstall activesupport
61
</pre>
62
# Download *Ruby 1.8.7-p72 Binary "ruby-1.8.7-p72-i386-mswin32.zip"* from "here":http://www.ruby-lang.org/en/downloads/
63
#* +Forget about the fact that version 1.9.1 is available (for now)+
64 1 Jack Kurzecki
# Extract the archive contents to *C:\webserver\ruby* overwriting the files from version 1.8.6 when prompted
65 3 Jack Kurzecki
# Download *"zlib compiled DLL"* package from "here":http://www.zlib.net/
66
## extract *zlib1.dll*
67
## rename it to *zlib.dll*
68
## move it to *C:\webserver\ruby\bin*
69
##* _(Alternatively you can just copy "C:\webserver\ruby\bin\zlib1.dll" and rename it to "C:\webserver\ruby\bin\zlib.dll")_
70 4 Jack Kurzecki
# Download *iconv 1.9.2-1 "libiconv-1.9.2-1-bin.zip"* from "here":http://sourceforge.net/projects/gnuwin32/files/libiconv/
71 3 Jack Kurzecki
## extract *bin\libiconv2.dll*
72
## rename it to *iconv.dll*
73
## move it to *C:\webserver\ruby\bin*
74 1 Jack Kurzecki
##* _(Alternatively you can just copy "C:\webserver\ruby\bin\libiconv2.dll" and rename it to "C:\webserver\ruby\bin\iconv.dll")_
75 2 Jack Kurzecki
# Verify Ruby version
76 1 Jack Kurzecki
## in command window, execute: <pre>
77
ruby -v
78
</pre>
79
##* expected output:<pre>
80 2 Jack Kurzecki
ruby 1.8.7 (2008-08-11 patchlevel 72) [i386-mswin32]
81 1 Jack Kurzecki
</pre>
82
83 2 Jack Kurzecki
h2. Install RubyGems
84 3 Jack Kurzecki
85 1 Jack Kurzecki
* _At the time of writing this document the latest version of RubyGems was 1.3.5. Newer versions should work too._
86 3 Jack Kurzecki
87
# Download *"rubygems-1.3.5.zip"* from "here":http://rubyforge.org/frs/?group_id=126
88 1 Jack Kurzecki
# Extract the package to *C:\webserver\railsapps*
89
# Install Ruby Gems
90
## in command window, execute: <pre>
91
cd C:\webserver\railsapps\rubygems-1.3.5
92
ruby setup.rb
93
</pre>
94
##* expected output:<pre>
95
RubyGems 1.3.5 installed
96
</pre>
97 2 Jack Kurzecki
## in command window, execute: <pre>
98 1 Jack Kurzecki
cd ..
99
gem update --system
100 3 Jack Kurzecki
</pre>
101 1 Jack Kurzecki
##* _If you get errors about missing "SSLEAY32.dll", install PHP as shown above and this dll will become available_
102 2 Jack Kurzecki
103
h2. Additional gems
104 1 Jack Kurzecki
105 2 Jack Kurzecki
* _mongrel-service and win32-service gems have to be downloaded manually. Download locations are added to sections below._
106 1 Jack Kurzecki
107
h3. Install Rake
108 3 Jack Kurzecki
109 1 Jack Kurzecki
* _At the time of writing this document the latest version of Rake was 0.8.7. Newer versions should work too._
110
111 2 Jack Kurzecki
# Install Rake gem
112 1 Jack Kurzecki
## in command window, execute: <pre>
113 2 Jack Kurzecki
gem install rake</pre>
114 1 Jack Kurzecki
##* expected output:<pre>
115
Successfully installed rake-0.8.7
116 2 Jack Kurzecki
</pre>
117 1 Jack Kurzecki
118
h3. Install Rails
119 3 Jack Kurzecki
120 1 Jack Kurzecki
* _At the time of writing this document, *Redmine 0.9.1* installation required *Rails 2.3.5*. Use Rails version 2.3.5 for Redmine revision >= r3235  deployment._*
121
122
# Install Rails gems
123 3 Jack Kurzecki
## in command window, execute: <pre>
124 1 Jack Kurzecki
gem install rails -v=2.3.5
125
</pre>
126 3 Jack Kurzecki
##* expected output:<pre>
127
Successfully installed activesupport-2.3.5
128
Successfully installed activerecord-2.3.5
129
Successfully installed actionpack-2.3.5
130
Successfully installed actionmailer-2.3.5
131
Successfully installed activeresource-2.3.5
132
Successfully installed rack-1.0.1
133 1 Jack Kurzecki
Successfully installed rails-2.3.5
134
</pre>
135
136
h3. Install Mongrel
137 3 Jack Kurzecki
138 2 Jack Kurzecki
* _At the time of writing this document the latest version of Mongrel was 1.1.5. Newer versions should work too._
139 1 Jack Kurzecki
* "_Project page_":http://rubyforge.org/projects/mongrel/
140
141
# Install Mongrel gems
142
## in command window, execute: <pre>
143
gem install mongrel
144
</pre>
145
##* expected output:<pre>
146
Successfully installed gem_plugin-0.2.3
147
Successfully installed cgi_multipart_eof_fix-2.5.0
148
Successfully installed mongrel-1.1.5-x86-mswin32-60
149
</pre>
150
151
h3. Install mysql gem
152 3 Jack Kurzecki
153 1 Jack Kurzecki
* _At the time of writing this document the latest version of mysql gem was 2.8.1. Newer versions should work too._
154
* It drastically improves page generation speed.
155 2 Jack Kurzecki
156 1 Jack Kurzecki
# Install mysql gem
157
## in command window, execute: <pre>
158
gem install mysql
159
</pre>
160 2 Jack Kurzecki
##* expected output:<pre>
161 3 Jack Kurzecki
Successfully installed mysql-2.8.1
162 1 Jack Kurzecki
No definition for ***
163 3 Jack Kurzecki
</pre>
164 1 Jack Kurzecki
##* _The gem was made for MySQL 5.0 so there are some additional features in 5.1 which will not be defined, so you will see a number of lines about missing definitions, but it does not cause any problems_
165 2 Jack Kurzecki
166 1 Jack Kurzecki
h3. Install mongrel-service + win32-service gems
167 3 Jack Kurzecki
168 1 Jack Kurzecki
* _At the time of writing this document the latest version of win32-service was 0.7 which does *NOT* work with Ruby 1.8.7_
169
* *Use only win32-service version 0.5.2 for Redmine deployment.*
170 3 Jack Kurzecki
171
# Download *"mongrel_service-0.3.4-i386-mswin32.gem"* from "here":http://rubyforge.org/frs/?group_id=1306
172
# Move *mongrel_service-0.3.4-i386-mswin32.gem* to *C:\webserver\railsapps*
173
# Download *"win32-service-0.5.2-mswin32.gem"* from "here":http://files.ruby.inoack.com/win32utils/
174
#* _This file is also attached at the bottom of this wiki page_
175 1 Jack Kurzecki
# Move *win32-service-0.5.2-mswin32.gem* to *C:\webserver\railsapps*
176 2 Jack Kurzecki
# Install the gem
177 1 Jack Kurzecki
## in command window, execute: <pre>
178
cd C:\webserver\railsapps
179
gem install mongrel_service
180
</pre>
181
##* expected output:<pre>
182
Successfully installed gem win32-service-0.5.2-mswin32
183
Successfully installed gem mongrel_service-0.3.4-i386-mswin32
184
</pre>
185 2 Jack Kurzecki
186 1 Jack Kurzecki
187
h2. Install Redmine
188 3 Jack Kurzecki
189 1 Jack Kurzecki
* _Procedure below assumes we will be installing Redmine 0.9.1, but it also works with any revisions >= r3235_
190 3 Jack Kurzecki
191
# Download *Redmine 0.9.1 (final) "redmine-0.9.1.zip"* from "here":http://rubyforge.org/frs/?group_id=1850
192
# Extract the contents of the +redmine-0.9.1+ directory in the archive to *C:\webserver\railsapps\redmine*
193 4 Jack Kurzecki
# Log into MySQL as *root* using "MySQL Workbench". You can also use command prompt or another tool, such as "MySQL GUI Tools" or "phpMyAdmin".
194 1 Jack Kurzecki
#* Open a new script tab and execute the following script: <pre>
195 3 Jack Kurzecki
create database redmine character set utf8;
196
create user 'redmineUser'@'localhost' identified by 'myPassword';
197 1 Jack Kurzecki
grant all privileges on redmine.* to 'redmineUser'@'localhost';
198 3 Jack Kurzecki
</pre>
199
#* _You should of course make the *redmineUser* and *myPassword* less obvious._
200
# Copy *C:\webserver\railsapps\redmine\config\database.yml.example* to *C:\webserver\railsapps\redmine\config\database.yml*
201
# Edit *C:\webserver\railsapps\redmine\config\database.yml* file to configure your database settings for "production" environment. It should look like this:<pre>
202
production:
203
  adapter: mysql
204
  database: redmine
205
  host: localhost
206
  username: redmineUser
207
  password: myPassword
208 1 Jack Kurzecki
  encoding: utf8
209 3 Jack Kurzecki
</pre>
210 2 Jack Kurzecki
#* set username and password to the values entered in the SQL script above.
211 1 Jack Kurzecki
#* save and close the file.
212
# Create default tables and populate with data (for fresh install only)
213
## in command window, execute: <pre>
214
cd C:\webserver\railsapps\redmine
215
set RAILS_ENV=production
216
rake config\initializers\session_store.rb
217
rake db:migrate
218 3 Jack Kurzecki
rake redmine:load_default_data
219 1 Jack Kurzecki
</pre>
220 4 Jack Kurzecki
##* _If you encounter this error: *Don't know how to build task 'config\initializers\session_store.rb'*, substitute slashes for backslashes in the commands above, that is:_<pre>
221
rake config/initializers/session_store.rb
222
</pre>
223
##* _If you encounter this error: *Mysql::Error: query: not connected: CREATE TABLE `schema_migrations` (`version` varchar(255) NOT NULL) ENGINE=InnoDB*, you might need to download a specific version of *libmySQL.dll* into "Ruby/bin" folder.
224
_For details refer to "*this thread*_":http://www.redmine.org/boards/1/topics/10162
225
# _Assuming that we will be hosting Redmine under http://localhost/redmine:_
226
Edit *C:\webserver\railsapps\redmine\config\environment.rb* file to configure Redmine to work as a sub-URI (Apache configuration is also required and is listed later on in this document).
227 1 Jack Kurzecki
#* add the following line at the bottom of the file:<pre>
228 2 Jack Kurzecki
Redmine::Utils::relative_url_root = "/redmine" 
229 1 Jack Kurzecki
</pre>
230 3 Jack Kurzecki
#* save and close the file.
231 1 Jack Kurzecki
#* _This is a preferred way of setting up the application prefix. *Mongrel_rails service "--prefix" directive does +NOT+ work with Rails 2.3.x*_
232
233
h2. Setup windows services
234 3 Jack Kurzecki
235
* Memory usage is greatly affected by the number of mongrels running. Keep that in mind when deciding on how many processes you want to run. For example, memory usage on Windows Server 2003 x64 SP2:
236
** Apache = 5MB + 20MB + 40MB = 65MB
237
** MySQL = 35MB
238
** Mongrel cluster = number-of-mongrel_rails-services x (3MB + 90MB) = 279MB (@3 processes)
239 1 Jack Kurzecki
240
# Create windows services
241
## in command window, execute: <pre>
242
mongrel_rails service::install -N mongrel_redmine_3001 -D "Mongrel serving Redmine on 3001" -p 3001 -e production -c C:\webserver\railsapps\redmine
243
mongrel_rails service::install -N mongrel_redmine_3002 -D "Mongrel serving Redmine on 3002" -p 3002 -e production -c C:\webserver\railsapps\redmine
244
mongrel_rails service::install -N mongrel_redmine_3003 -D "Mongrel serving Redmine on 3003" -p 3003 -e production -c C:\webserver\railsapps\redmine
245
</pre>
246
# Start windows services, which in turn will start mongrel servers
247 2 Jack Kurzecki
## in command window, execute: <pre>
248
net start mongrel_redmine_3001
249 1 Jack Kurzecki
net start mongrel_redmine_3002
250
net start mongrel_redmine_3003
251 2 Jack Kurzecki
</pre>
252 1 Jack Kurzecki
# Go to the Windows Services list and set all "Mongrel serving Redmine on 300#" services to start automatically
253
## in command window, execute: <pre>
254
services.msc /s
255 3 Jack Kurzecki
</pre>
256
## find each one of "Mongrel serving Redmine on 300#" services
257
## right click, select *Properties*
258
## set *Startup type* to *"Automatic"*
259 1 Jack Kurzecki
## press OK and repeat for the remaining Mongrel services.
260
261
h2. Configure Apache 2.2.x as proxy to Mongrel cluster
262 3 Jack Kurzecki
263 1 Jack Kurzecki
* _Procedure below assumes we will be hosting Redmine under http://localhost/redmine and must match the *relative_url_root* set above_
264 3 Jack Kurzecki
265 1 Jack Kurzecki
# Open *C:\webserver\apache\conf\httpd.conf*
266
# At the bottom of this file add the following line: <pre>
267
Include conf/httpd-proxy-mongrel.conf
268 3 Jack Kurzecki
</pre>
269 1 Jack Kurzecki
# Create a file *C:\webserver\apache\conf\httpd-proxy-mongrel.conf*
270
# Enter the following: <pre>
271
LoadModule proxy_module modules/mod_proxy.so
272 2 Jack Kurzecki
LoadModule proxy_http_module modules/mod_proxy_http.so
273 1 Jack Kurzecki
LoadModule proxy_balancer_module modules/mod_proxy_balancer.so
274
275
ProxyPass /redmine balancer://redmine_cluster
276
ProxyPassReverse /redmine balancer://redmine_cluster
277
278
279
<Proxy balancer://redmine_cluster>
280
	BalancerMember http://127.0.0.1:3001
281
	BalancerMember http://127.0.0.1:3002
282
	BalancerMember http://127.0.0.1:3003
283
</Proxy>
284 3 Jack Kurzecki
</pre>
285
# Restart the Apache service.
286
#* in command window, execute: <pre>
287
C:\webserver\apache\bin\httpd.exe -w -n "Apache2.2" -k stop
288
C:\webserver\apache\bin\httpd.exe -w -n "Apache2.2" -k start
289 1 Jack Kurzecki
</pre>
290
291
292 2 Jack Kurzecki
293
*+DONE!+*
294
295
296
297
h3. Apendix
298 3 Jack Kurzecki
299 1 Jack Kurzecki
* Check if you have all the necessary gems installed for Redmine 0.9.1+
300
** in command window, execute: <pre>
301
gem list
302
</pre>
303
*** expected output:<pre>
304 2 Jack Kurzecki
actionmailer (2.3.5)
305 1 Jack Kurzecki
actionpack (2.3.5)
306
activerecord (2.3.5)
307
activeresource (2.3.5)
308
activesupport (2.3.5)
309
cgi_multipart_eof_fix (2.5.0)
310
gem_plugin (0.2.3)
311
mongrel (1.1.5)
312
mongrel_service (0.3.4)
313
mysql (2.8.1)
314
rack (1.0.1)
315
rails (2.3.5)
316
rake (0.8.7)
317
win32-service (0.5.2)
318
</pre>
319 4 Jack Kurzecki
320
* As already mentioned above, in case you encounter problems, please look at "*this forum thread*":http://www.redmine.org/boards/1/topics/10162 for information about some known issues and their workarounds