Project

General

Profile

FedoraInstallation » History » Version 6

Jamie McPeek, 2014-08-16 23:37

1 1 Jamie McPeek
h1. HowTo Install Redmine 2.5.x on Fedora 20
2
3
{{toc}}
4
5
h2. System Requirements
6
7
No assumptions are made about the initial state of the system in this guide. The guide can be followed for either 32-bit or 64-bit systems - though all testing and the original installation was performed on a 64-bit system.
8
9
The hardware requirements are not significant, so a small VM with 10gb storage and 1GB ram and 1GB swap file should be sufficient.
10
11
This guide can be used on top of an already existing system or, from scratch, downloading from the Fedora website.
12
13
An ISO for installation can be downloaded from "here":http://fedoraproject.org/en/get-fedora.
14
15
The rest of the guide assumes that you have created a user account with wheel/administrator access and are logged in to the terminal directly or through SSH.
16 2 Jamie McPeek
17
h2. Updating the System
18
19
Before beginning, you should ensure all of your installed packages are up-to-date. This can be done by issuing the following command:
20
21
<pre>
22
$ sudo yum update
23
</pre>
24
25
If the kernel was updated as part of this command, you should perform a restart to begin using it:
26
27
<pre>
28
$ sudo shutdown -r now
29
</pre>
30
31
h2. Installing Dependencies
32 3 Jamie McPeek
33
Before beginning the installation of Redmine, there are a number of dependencies which need to be installed.
34
35 4 Jamie McPeek
Depending on your needs, some of these may not be necessary. Depending on your preferences, you may choose alternatives to some of these.
36 3 Jamie McPeek
37
<pre>
38
apr-devel         - For Passenger
39
apr-util-devel    - For Passenger
40
curl-devel        - For Passenger
41
gcc               - For JSON
42
gcc-c++           - For Passenger
43
git               - (Optional) For SCM Integration
44
httpd             - Web Server
45
httpd-devel       - For Passenger
46
ImageMagick-devel - For RMagick
47
mariadb-devel     - For Redmine
48
mariadb-server    - For Redmine
49
nano              - Configuration Editor
50 6 Jamie McPeek
postfix           - Email (MTA)
51 3 Jamie McPeek
ruby-devel        - For Redmine
52
tar               - For Decompression
53
wget              - For Download
54
</pre>
55
56
All of these can be installed prior to starting with a single command:
57
58 1 Jamie McPeek
<pre>
59 6 Jamie McPeek
$ sudo yum install apr-devel apr-util-devel curl-devel gcc gcc-c++ git httpd httpd-devel ImageMagick-devel mariadb-devel mariadb-server nano postfix ruby-devel tar wget
60 3 Jamie McPeek
</pre>
61
62
h2. Disable SELinux
63
64
Some users have noted issues installing Redmine with SELinux active. This can be disabled via the following command:
65
66
<pre>
67
# sudo setenforce 0
68
</pre>
69
70
Steps will be taken throughout the remainder of the guide to ensure that, if desired, SELinux can be re-enabled after and still maintain a fully functional Redmine installation.
71
72
h2. Enable Server Environment
73
74
With all of the dependencies installed, we need to ensure that the servers are setup, ready for use, and accessible external to the OS installation.
75
76
The first step is to open the standard port 80 in the firewall for the web server:
77
78
<pre>
79
$ sudo firewall-cmd --zone=public --add-service=http
80
$ sudo firewall-cmd --permanent --zone=public --add-service=http
81
</pre>
82
83
The first line opens the port in the current configuration. The second line ensures that, after a restart, that port will remain open and available.
84
85
The second step is to start the web server and database server:
86 1 Jamie McPeek
87 3 Jamie McPeek
<pre>
88 6 Jamie McPeek
$ sudo systemctl start httpd mariadb postfix
89
$ sudo systemctl enable httpd mariadb postfix
90 3 Jamie McPeek
</pre>
91
92 1 Jamie McPeek
Similar to the firewall commands, the first line starts the servers in the current configuration. The second line ensures that, after a restart, both servers come back online.
93 4 Jamie McPeek
94
h2. Configuring MariaDB
95
96
Now that you have a database server up and running, it needs to be configured for use. The initial setup can be performed with the following command:
97
98
<pre>
99
$ mysql_secure_installation
100
</pre>
101
102
This will prompt you to create a password for the root account as well as a number of other choices. For a standard setup, the default choice for each question is acceptable.
103
104
Advanced usages or installations may opt for different answers; however, that is beyond the scope of this guide.
105
106
h3. Creating a Redmine Database and Account
107
108
Now that you have MariaDB configured, it is time to create a database and user for use with your Redmine installation.
109
110
First, connect to the server:
111
112
<pre>
113
$ mysql -u root -p
114
</pre>
115
116
You will be prompted to enter the root password. Once provided, you will be able to issue the following commands:
117
118
<pre><code class="sql">
119
CREATE DATABASE redmine CHARACTER SET utf8;
120
CREATE USER 'redmine'@'localhost' IDENTIFIED BY '<user_password>';
121
GRANT ALL PRIVILEGES ON redmine.* TO 'redmine'@'localhost';
122
</code></pre>
123
124
The above commands will create the database, create a user with a defined password, and ensure the created user has full access on the newly created database.
125
126
Once those commands have been entered, issue the following command to return to the command line:
127
128
<pre>
129
quit
130
</pre>
131
132
h2. Obtaining Redmine
133
134
Now that all the dependencies are installed and the servers are up and running it's time to get the stable release of Redmine and begin its installation.
135
136
In this example, we'll use wget to download the file from the Redmine server and tar to extract its contents:
137
138
<pre>
139
$ wget http://www.redmine.org/releases/redmine-2.5.2.tar.gz
140
$ tar xfzv redmine-2.5.2.tar.gz
141
</pre>
142
143
h2. Redmine Database Configuration
144
145
To ensure proper functionality, the Redmine installation will need to communicate with the database that has just been created. This can be done by performing the following:
146
147
<pre>
148
$ cd redmine-2.5.2/config
149
$ cp database.yml.example database.yml
150
$ nano -w database.yml
151
</pre>
152
153
Once the file has been opened, the @production@ definition needs to be updated to match the database and account used above. It should look as follows:
154
155
<pre><code class="yaml">
156
production:
157
  adapter: mysql2
158
  database: redmine
159
  host: localhost
160
  username: redmine
161
  password: "<user_password>"
162
  encoding: utf8
163
</code></pre>
164
165
This replaces the user @root@ and the blank password in the example configuration file.
166
167
h2. Redmine Installation Directory
168
169
With most of the precursor work completed, it's time to move the installation to a folder more accessible than a user's home directory.
170
171
For the purposes of this guide, Redmine will be moved to @/var/www/redmine@; however, this could be moved to a variety of over locations based on personal needs.
172
173
This can be don with the following commands:
174
175
<pre>
176
$ cd /var/www
177
$ sudo cp -R ~/redmine-2.5.2 redmine
178
$ cd redmine
179
</pre>
180
181
To ensure proper functionality and access rights, the @public/plugin_assets@ folder needs to be created:
182
183
<pre>
184
$ sudo mkdir public/plugin_assets
185
</pre>
186
187
To allow read/write access to the folders, the user @apache@ needs to have access:
188
189
<pre>
190
$ sudo chown apache:apache -R files log public/plugin_assets tmp
191
</pre>
192
193
h3. Optional SELinux Configuration
194
195
If you plan to re-enable SELinux after installation, the following steps should be taken to ensure smooth execution.
196
197
<pre>
198
$ sudo chcon -R --reference=/var/www/html /var/www/redmine
199
</pre>
200
201
This command applies SELinux directory permissions typically for a web server to all sub-directories under the redmine top-level folder.
202
203
<pre>
204
$ sudo chcon -t httpd_sys_content_rw_t -R files log public/plugin_assets tmp
205
</pre>
206
207
This command enables the specific folders listed to have read/write access while SELinux is active. Under a normal configuration with SELinux, all web directories are read-only.
208 5 Jamie McPeek
209
h2. Ruby Gem Installation
210
211
The ruby dependencies for Redmine are managed by bundler, so that must be installed first to determine what else must be downloaded and installed.
212
213
<pre>
214
$ sudo gem install bundler
215
</pre>
216
217
With bundler installed, the Redmine ruby dependencies can be sorted:
218
219
<pre>
220
$ sudo /usr/local/bin/bundle install --without development test
221
</pre>
222
223
*Note 1:* By default @/usr/local/bin@ is not on @$PATH@ for the @root@ user, so the absolute path must be provided.
224
225
*Note 2:* Bundle will complain about installing gems via sudo making them only usable by @root@. This is not true - by installing as @root@, these gems are available to all users.
226
227
h2. Native Extension Fixes
228
229
When running @bundler@ as root, the @mysql2@ and @rmagick@ native extensions get installed, but to a folder not on ruby's path. To correct this, the following steps should be taken:
230
231
<pre>
232
$ sudo mkdir -p /usr/local/lib64/ruby/site_ruby/mysql2
233
</pre>
234
235
This creates the path that ruby expects to find the @mysql2.so@ file at.
236
237
<pre>
238
$ cd /usr/local/share/gems/gems/mysql2-0.3.16/ext/mysql2
239
$ sudo ruby extconf.rb
240
$ sudo make
241
$ sudo make install
242
</pre>
243
244
The above steps complete the install to the expected directory using default compile options. Special options are beyond the scope of this guide.
245
246
The same should now be performed for the @rmagick@ native extension:
247
248
<pre>
249
$ cd /usr/local/share/gems/gems/rmagick-2.13.3/ext/RMagick
250
$ sudo ruby extconf.rb
251
$ sudo make
252
$ sudo make install
253
</pre>
254
255
Once again, the above steps complete the install to the expected directory using default compile options.
256
257
Finally, return to the installation directory to finish the remaining steps:
258
259
<pre>
260
$ cd /var/www/redmine
261
</pre>
262
263
h2. Redmine Database Initialization
264
265
We're on to the final steps of completing the Redmine installation now that everything else has been taken care of.
266
267
The first step is to generate the secret key for session management:
268
269
<pre>
270
$ sudo /usr/local/bin/rake generate_secret_token
271
</pre>
272
273
Next, the database needs to be setup:
274
275
<pre>
276
$ sudo RAILS_ENV=production /usr/local/bin/rake db:migrate
277
</pre>
278
279
Finally, the database needs to be populated with default data:
280
281
<pre>
282
$ sudo RAILS_ENV=production /usr/local/bin/rake redmine:load_default_data
283
</pre>
284
285
This will prompt you to pick your language, which defaults to [en].
286
287
h3. WEBRick Test Execution
288
289
Once this step has been completed, you have a fully functional Redmine installation and can run this for testing via WEBRick:
290
291 1 Jamie McPeek
<pre>
292
$ sudo ruby script/rails server webrick -e production
293
</pre>
294 6 Jamie McPeek
295
h2. Passenger Installation
296
297
For a more usable production setup, Redmine can be hosted through @apache2@ via Passenger. To get the Passenger bootstrap, issue the following command:
298
299
<pre>
300
$ sudo gem install passenger
301
</pre>
302
303
Once completed, the native extensions still need to be compiled. This can be done by issuing the following command:
304
305
<pre>
306
$ sudo /usr/local/bin/passenger-install-apache2-module
307
</pre>
308
309
This tool will help diagnose any issues as well as provide some default settings for your specific installation.
310
311
*Note 1:* The compilation of Passenger requires at least 1GB of RAM or RAM+Swap space combined. The compile will fail otherwise.
312
313
h2. Passenger Configuration
314
315
Now that the extensions have been installed, @apache2@ needs to know how to use it.
316
317
The first step is to create a configuration file for Passenger:
318
319
<pre>
320
$ sudo nano -w /etc/httpd/conf.modules.d/passenger.conf
321
</pre>
322
323
This file should contain the information presented from running @passenger-install-apache2-module@. An example:
324
325
<pre>
326
LoadModule passenger_module /usr/local/share/gems/gems/passenger-4.0.48/buildout/apache2/mod_passenger.so
327
<IfModule mod_passenger.c>
328
   PassengerDefaultUser apache
329
   PassengerRoot /usr/local/share/gems/gems/passenger-4.0.48
330
   PassengerDefaultRuby /usr/bin/ruby
331
</IfModule>
332
</pre>
333
334
*Note 1: In addition to the default information from the installer, also add @PassengerDefaultUser apache@. This will ensure Passenger runs as the user apache and maintains write access only to the folders defined previously.
335
336
h2. Web Server Configuration
337
338
Now that the module is enabled, we have the choice of running the installation of Redmine at our root directory or as a subdirectory on the website.
339
340
h3. Top-Level Execution
341
342
To run straight at a base website, modify the @apache2@ configuration file:
343
344
<pre>
345
$ sudo nano -w /etc/httpd/conf/httpd.conf
346
</pre>
347
348
And add the following block to the bottom of the file:
349
350
<pre>
351
<VirtualHost *:80>
352
   ServerName www.website.com
353
354
   DocumentRoot /var/www/redmine/public
355
356
   <Directory /var/www/redmine/public>
357
      # This relaxes Apache security settings.
358
      AllowOverride all
359
      # MultiViews must be turned off.
360
      Options -MultiViews
361
      # Uncomment this if you're on Apache >= 2.4:
362
      Require all granted
363
   </Directory>
364
</VirtualHost>
365
</pre>
366
367
h3. Sub-Directory Execution
368
369
To run from a sub-directory of the base of a website, modify the @apache2@ configuration file:
370
371
<pre>
372
$ sudo nano -w /etc/httpd/conf/httpd.conf
373
</pre>
374
375
And add the following block to the bottom of the file:
376
377
<pre>
378
<VirtualHost *:80>
379
   ServerName www.website.com
380
381
   DocumentRoot /var/www/html
382
383
   Alias /redmine /var/www/redmine/public
384
385
   <Location /redmine>
386
      PassengerBaseURI /redmine
387
      PassengerAppRoot /var/www/redmine
388
   </Location>
389
390
   <Directory /var/www/redmine/public>
391
      # This relaxes Apache security settings.
392
      AllowOverride all
393
      # MultiViews must be turned off.
394
      Options -MultiViews
395
      # Uncomment this if you're on Apache >= 2.4:
396
      Require all granted
397
   </Directory>
398
</VirtualHost>
399
</pre>
400
401
h2. Email Configuration
402
403
This section goes through the steps necessary to setup email notifications to be sent out from Redmine. Handling email input for issue creation and other purposes is beyond the scope of this guide.
404
405
The default configuration file for @postfix@ is very thorough; however, you may want to change the @myhostname@ option as follows:
406
407
<pre>
408
myhostname = mail.website.com
409
</pre>
410
411
The default will attempt to grab the FQDN from the server, which may not be what you want.
412
413
h3. Optional SELinux Configuration
414
415
By default with SELinux enabled, the web server cannot open external connections. This is necessary for sending email notifications, even when port 25 is being opened on the localhost. This can be done with the following command:
416
417
<pre>
418
$ sudo setsebool httpd_can_network_connect 1
419
</pre>
420
421
h3. Redmine Email Configuration
422
423
To use postfix, Redmine needs to know to communicate with it appropriately.
424
425
This can be done by making some more configuration changes:
426
427
<pre>
428
$ cd /var/www/redmine/config
429
$ sudo cp configuration.yml.example configuration.yml
430
$ sudo nano -w configuration.yml
431
</pre>
432
433
Assuming you are only running a production environment, just editing the @default@ section will be sufficient. An example of an authenticationless connection using postfix:
434
435
<pre><code class="yaml">
436
default:
437
  # Outgoing emails configuration (see examples above)
438
  email_delivery:
439
    delivery_method: :async_smtp
440
</code></pre>
441
442
h2. Restart Web Server
443
444
With all of the configuration changes and module installations, the @apache2@ server needs to be restarted:
445
446
<pre>
447
$ sudo systemctl restart httpd
448
</pre>
449
450
Once that comes back up, you should be able to browse to a fully working stock installation of Redmine at either http://www.website.com/ or http://www.website.com/redmine.
451
452
h2. Enable SELinux
453
454
If you wish to re-enable SELinux at this point, you may do so by issuing the following command:
455
456
<pre>
457
$ sudo setenforce 1
458
</pre>
459
460
Assuming you have followed the optional SELinux sections, the Redmine installation should function identically with SELinux enabled or disabled.