FedoraInstallation » History » Version 5

Jamie McPeek, 2014-08-16 23:10

1 1 Jamie McPeek
h1. HowTo Install Redmine 2.5.x on Fedora 20
2 1 Jamie McPeek
3 1 Jamie McPeek
{{toc}}
4 1 Jamie McPeek
5 1 Jamie McPeek
h2. System Requirements
6 1 Jamie McPeek
7 1 Jamie McPeek
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 1 Jamie McPeek
9 1 Jamie McPeek
The hardware requirements are not significant, so a small VM with 10gb storage and 1GB ram and 1GB swap file should be sufficient.
10 1 Jamie McPeek
11 1 Jamie McPeek
This guide can be used on top of an already existing system or, from scratch, downloading from the Fedora website.
12 1 Jamie McPeek
13 1 Jamie McPeek
An ISO for installation can be downloaded from "here":http://fedoraproject.org/en/get-fedora.
14 1 Jamie McPeek
15 1 Jamie McPeek
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 2 Jamie McPeek
h2. Updating the System
18 2 Jamie McPeek
19 2 Jamie McPeek
Before beginning, you should ensure all of your installed packages are up-to-date. This can be done by issuing the following command:
20 2 Jamie McPeek
21 2 Jamie McPeek
<pre>
22 2 Jamie McPeek
$ sudo yum update
23 2 Jamie McPeek
</pre>
24 2 Jamie McPeek
25 2 Jamie McPeek
If the kernel was updated as part of this command, you should perform a restart to begin using it:
26 2 Jamie McPeek
27 2 Jamie McPeek
<pre>
28 2 Jamie McPeek
$ sudo shutdown -r now
29 2 Jamie McPeek
</pre>
30 2 Jamie McPeek
31 2 Jamie McPeek
h2. Installing Dependencies
32 3 Jamie McPeek
33 3 Jamie McPeek
Before beginning the installation of Redmine, there are a number of dependencies which need to be installed.
34 3 Jamie McPeek
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 3 Jamie McPeek
<pre>
38 3 Jamie McPeek
apr-devel         - For Passenger
39 3 Jamie McPeek
apr-util-devel    - For Passenger
40 3 Jamie McPeek
curl-devel        - For Passenger
41 3 Jamie McPeek
gcc               - For JSON
42 3 Jamie McPeek
gcc-c++           - For Passenger
43 3 Jamie McPeek
git               - (Optional) For SCM Integration
44 3 Jamie McPeek
httpd             - Web Server
45 3 Jamie McPeek
httpd-devel       - For Passenger
46 3 Jamie McPeek
ImageMagick-devel - For RMagick
47 3 Jamie McPeek
mariadb-devel     - For Redmine
48 3 Jamie McPeek
mariadb-server    - For Redmine
49 3 Jamie McPeek
nano              - Configuration Editor
50 3 Jamie McPeek
ruby-devel        - For Redmine
51 3 Jamie McPeek
tar               - For Decompression
52 3 Jamie McPeek
wget              - For Download
53 3 Jamie McPeek
</pre>
54 3 Jamie McPeek
55 3 Jamie McPeek
All of these can be installed prior to starting with a single command:
56 3 Jamie McPeek
57 3 Jamie McPeek
<pre>
58 3 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 ruby-devel tar wget
59 3 Jamie McPeek
</pre>
60 3 Jamie McPeek
61 3 Jamie McPeek
h2. Disable SELinux
62 3 Jamie McPeek
63 3 Jamie McPeek
Some users have noted issues installing Redmine with SELinux active. This can be disabled via the following command:
64 3 Jamie McPeek
65 3 Jamie McPeek
<pre>
66 3 Jamie McPeek
# sudo setenforce 0
67 3 Jamie McPeek
</pre>
68 3 Jamie McPeek
69 3 Jamie McPeek
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.
70 3 Jamie McPeek
71 3 Jamie McPeek
h2. Enable Server Environment
72 3 Jamie McPeek
73 3 Jamie McPeek
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.
74 3 Jamie McPeek
75 3 Jamie McPeek
The first step is to open the standard port 80 in the firewall for the web server:
76 3 Jamie McPeek
77 3 Jamie McPeek
<pre>
78 3 Jamie McPeek
$ sudo firewall-cmd --zone=public --add-service=http
79 3 Jamie McPeek
$ sudo firewall-cmd --permanent --zone=public --add-service=http
80 3 Jamie McPeek
</pre>
81 3 Jamie McPeek
82 3 Jamie McPeek
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.
83 3 Jamie McPeek
84 3 Jamie McPeek
The second step is to start the web server and database server:
85 3 Jamie McPeek
86 3 Jamie McPeek
<pre>
87 3 Jamie McPeek
$ sudo systemctl start httpd mariadb
88 3 Jamie McPeek
$ sudo systemctl enable httpd mariadb
89 3 Jamie McPeek
</pre>
90 3 Jamie McPeek
91 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.
92 4 Jamie McPeek
93 4 Jamie McPeek
h2. Configuring MariaDB
94 4 Jamie McPeek
95 4 Jamie McPeek
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:
96 4 Jamie McPeek
97 4 Jamie McPeek
<pre>
98 4 Jamie McPeek
$ mysql_secure_installation
99 4 Jamie McPeek
</pre>
100 4 Jamie McPeek
101 4 Jamie McPeek
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.
102 4 Jamie McPeek
103 4 Jamie McPeek
Advanced usages or installations may opt for different answers; however, that is beyond the scope of this guide.
104 4 Jamie McPeek
105 4 Jamie McPeek
h3. Creating a Redmine Database and Account
106 4 Jamie McPeek
107 4 Jamie McPeek
Now that you have MariaDB configured, it is time to create a database and user for use with your Redmine installation.
108 4 Jamie McPeek
109 4 Jamie McPeek
First, connect to the server:
110 4 Jamie McPeek
111 4 Jamie McPeek
<pre>
112 4 Jamie McPeek
$ mysql -u root -p
113 4 Jamie McPeek
</pre>
114 4 Jamie McPeek
115 4 Jamie McPeek
You will be prompted to enter the root password. Once provided, you will be able to issue the following commands:
116 4 Jamie McPeek
117 4 Jamie McPeek
<pre><code class="sql">
118 4 Jamie McPeek
CREATE DATABASE redmine CHARACTER SET utf8;
119 4 Jamie McPeek
CREATE USER 'redmine'@'localhost' IDENTIFIED BY '<user_password>';
120 4 Jamie McPeek
GRANT ALL PRIVILEGES ON redmine.* TO 'redmine'@'localhost';
121 4 Jamie McPeek
</code></pre>
122 4 Jamie McPeek
123 4 Jamie McPeek
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.
124 4 Jamie McPeek
125 4 Jamie McPeek
Once those commands have been entered, issue the following command to return to the command line:
126 4 Jamie McPeek
127 4 Jamie McPeek
<pre>
128 4 Jamie McPeek
quit
129 4 Jamie McPeek
</pre>
130 4 Jamie McPeek
131 4 Jamie McPeek
h2. Obtaining Redmine
132 4 Jamie McPeek
133 4 Jamie McPeek
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.
134 4 Jamie McPeek
135 4 Jamie McPeek
In this example, we'll use wget to download the file from the Redmine server and tar to extract its contents:
136 4 Jamie McPeek
137 4 Jamie McPeek
<pre>
138 4 Jamie McPeek
$ wget http://www.redmine.org/releases/redmine-2.5.2.tar.gz
139 4 Jamie McPeek
$ tar xfzv redmine-2.5.2.tar.gz
140 4 Jamie McPeek
</pre>
141 4 Jamie McPeek
142 4 Jamie McPeek
h2. Redmine Database Configuration
143 4 Jamie McPeek
144 4 Jamie McPeek
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:
145 4 Jamie McPeek
146 4 Jamie McPeek
<pre>
147 4 Jamie McPeek
$ cd redmine-2.5.2/config
148 4 Jamie McPeek
$ cp database.yml.example database.yml
149 4 Jamie McPeek
$ nano -w database.yml
150 4 Jamie McPeek
</pre>
151 4 Jamie McPeek
152 4 Jamie McPeek
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:
153 4 Jamie McPeek
154 4 Jamie McPeek
<pre><code class="yaml">
155 4 Jamie McPeek
production:
156 4 Jamie McPeek
  adapter: mysql2
157 4 Jamie McPeek
  database: redmine
158 4 Jamie McPeek
  host: localhost
159 4 Jamie McPeek
  username: redmine
160 4 Jamie McPeek
  password: "<user_password>"
161 4 Jamie McPeek
  encoding: utf8
162 4 Jamie McPeek
</code></pre>
163 4 Jamie McPeek
164 4 Jamie McPeek
This replaces the user @root@ and the blank password in the example configuration file.
165 4 Jamie McPeek
166 4 Jamie McPeek
h2. Redmine Installation Directory
167 4 Jamie McPeek
168 4 Jamie McPeek
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.
169 4 Jamie McPeek
170 4 Jamie McPeek
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.
171 4 Jamie McPeek
172 4 Jamie McPeek
This can be don with the following commands:
173 4 Jamie McPeek
174 4 Jamie McPeek
<pre>
175 4 Jamie McPeek
$ cd /var/www
176 4 Jamie McPeek
$ sudo cp -R ~/redmine-2.5.2 redmine
177 4 Jamie McPeek
$ cd redmine
178 4 Jamie McPeek
</pre>
179 4 Jamie McPeek
180 4 Jamie McPeek
To ensure proper functionality and access rights, the @public/plugin_assets@ folder needs to be created:
181 4 Jamie McPeek
182 4 Jamie McPeek
<pre>
183 4 Jamie McPeek
$ sudo mkdir public/plugin_assets
184 4 Jamie McPeek
</pre>
185 4 Jamie McPeek
186 4 Jamie McPeek
To allow read/write access to the folders, the user @apache@ needs to have access:
187 4 Jamie McPeek
188 4 Jamie McPeek
<pre>
189 4 Jamie McPeek
$ sudo chown apache:apache -R files log public/plugin_assets tmp
190 4 Jamie McPeek
</pre>
191 4 Jamie McPeek
192 4 Jamie McPeek
h3. Optional SELinux Configuration
193 4 Jamie McPeek
194 4 Jamie McPeek
If you plan to re-enable SELinux after installation, the following steps should be taken to ensure smooth execution.
195 4 Jamie McPeek
196 4 Jamie McPeek
<pre>
197 4 Jamie McPeek
$ sudo chcon -R --reference=/var/www/html /var/www/redmine
198 4 Jamie McPeek
</pre>
199 4 Jamie McPeek
200 4 Jamie McPeek
This command applies SELinux directory permissions typically for a web server to all sub-directories under the redmine top-level folder.
201 4 Jamie McPeek
202 4 Jamie McPeek
<pre>
203 4 Jamie McPeek
$ sudo chcon -t httpd_sys_content_rw_t -R files log public/plugin_assets tmp
204 4 Jamie McPeek
</pre>
205 4 Jamie McPeek
206 4 Jamie McPeek
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.
207 5 Jamie McPeek
208 5 Jamie McPeek
h2. Ruby Gem Installation
209 5 Jamie McPeek
210 5 Jamie McPeek
The ruby dependencies for Redmine are managed by bundler, so that must be installed first to determine what else must be downloaded and installed.
211 5 Jamie McPeek
212 5 Jamie McPeek
<pre>
213 5 Jamie McPeek
$ sudo gem install bundler
214 5 Jamie McPeek
</pre>
215 5 Jamie McPeek
216 5 Jamie McPeek
With bundler installed, the Redmine ruby dependencies can be sorted:
217 5 Jamie McPeek
218 5 Jamie McPeek
<pre>
219 5 Jamie McPeek
$ sudo /usr/local/bin/bundle install --without development test
220 5 Jamie McPeek
</pre>
221 5 Jamie McPeek
222 5 Jamie McPeek
*Note 1:* By default @/usr/local/bin@ is not on @$PATH@ for the @root@ user, so the absolute path must be provided.
223 5 Jamie McPeek
224 5 Jamie McPeek
*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.
225 5 Jamie McPeek
226 5 Jamie McPeek
h2. Native Extension Fixes
227 5 Jamie McPeek
228 5 Jamie McPeek
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:
229 5 Jamie McPeek
230 5 Jamie McPeek
<pre>
231 5 Jamie McPeek
$ sudo mkdir -p /usr/local/lib64/ruby/site_ruby/mysql2
232 5 Jamie McPeek
</pre>
233 5 Jamie McPeek
234 5 Jamie McPeek
This creates the path that ruby expects to find the @mysql2.so@ file at.
235 5 Jamie McPeek
236 5 Jamie McPeek
<pre>
237 5 Jamie McPeek
$ cd /usr/local/share/gems/gems/mysql2-0.3.16/ext/mysql2
238 5 Jamie McPeek
$ sudo ruby extconf.rb
239 5 Jamie McPeek
$ sudo make
240 5 Jamie McPeek
$ sudo make install
241 5 Jamie McPeek
</pre>
242 5 Jamie McPeek
243 5 Jamie McPeek
The above steps complete the install to the expected directory using default compile options. Special options are beyond the scope of this guide.
244 5 Jamie McPeek
245 5 Jamie McPeek
The same should now be performed for the @rmagick@ native extension:
246 5 Jamie McPeek
247 5 Jamie McPeek
<pre>
248 5 Jamie McPeek
$ cd /usr/local/share/gems/gems/rmagick-2.13.3/ext/RMagick
249 5 Jamie McPeek
$ sudo ruby extconf.rb
250 5 Jamie McPeek
$ sudo make
251 5 Jamie McPeek
$ sudo make install
252 5 Jamie McPeek
</pre>
253 5 Jamie McPeek
254 5 Jamie McPeek
Once again, the above steps complete the install to the expected directory using default compile options.
255 5 Jamie McPeek
256 5 Jamie McPeek
Finally, return to the installation directory to finish the remaining steps:
257 5 Jamie McPeek
258 5 Jamie McPeek
<pre>
259 5 Jamie McPeek
$ cd /var/www/redmine
260 5 Jamie McPeek
</pre>
261 5 Jamie McPeek
262 5 Jamie McPeek
h2. Redmine Database Initialization
263 5 Jamie McPeek
264 5 Jamie McPeek
We're on to the final steps of completing the Redmine installation now that everything else has been taken care of.
265 5 Jamie McPeek
266 5 Jamie McPeek
The first step is to generate the secret key for session management:
267 5 Jamie McPeek
268 5 Jamie McPeek
<pre>
269 5 Jamie McPeek
$ sudo /usr/local/bin/rake generate_secret_token
270 5 Jamie McPeek
</pre>
271 5 Jamie McPeek
272 5 Jamie McPeek
Next, the database needs to be setup:
273 5 Jamie McPeek
274 5 Jamie McPeek
<pre>
275 5 Jamie McPeek
$ sudo RAILS_ENV=production /usr/local/bin/rake db:migrate
276 5 Jamie McPeek
</pre>
277 5 Jamie McPeek
278 5 Jamie McPeek
Finally, the database needs to be populated with default data:
279 5 Jamie McPeek
280 5 Jamie McPeek
<pre>
281 5 Jamie McPeek
$ sudo RAILS_ENV=production /usr/local/bin/rake redmine:load_default_data
282 5 Jamie McPeek
</pre>
283 5 Jamie McPeek
284 5 Jamie McPeek
This will prompt you to pick your language, which defaults to [en].
285 5 Jamie McPeek
286 5 Jamie McPeek
h3. WEBRick Test Execution
287 5 Jamie McPeek
288 5 Jamie McPeek
Once this step has been completed, you have a fully functional Redmine installation and can run this for testing via WEBRick:
289 5 Jamie McPeek
290 5 Jamie McPeek
<pre>
291 5 Jamie McPeek
$ sudo ruby script/rails server webrick -e production
292 5 Jamie McPeek
</pre>