Project

General

Profile

HowTo Install Redmine on Ubuntu step by step » History » Version 29

Toshi MARUYAMA, 2015-04-19 06:07
remove bold in "pre" tag added in previous version

1 1 Lee Butler
h1. HowTo Install Redmine on Ubuntu step by step
2
3 17 Dietmar H
{{>toc}}
4
5 24 Anonymous
h2. Prerequisite: check your ubuntu version against intended Redmine version
6
7 21 Anonymous
p. Before using or studying this guide you should check which Redmine version you are going for. Be aware that only latest stable releases will be fully compatible with current releases of plugins.
8 23 Anonymous
To check redmine versions versus your ubuntu version have a look at http://www.ubuntuupdates.org/pm/redmine
9 1 Lee Butler
10 24 Anonymous
p. Generally you could also consider only installing ruby from ubuntu-repos and then heading for a release of redmine from redmine's download page: http://www.redmine.org/projects/redmine/wiki/Download (this is the more common way of installing redmine on ubuntu). In this case *this guide is not suited* for you and you should check for an alternate guide. Google provides lots of resources for this alternate installation procedure.
11
12 1 Lee Butler
If you are sure that you want to install from ubuntu-repositories, keep on reading:
13 24 Anonymous
14
h2. Introduction
15 21 Anonymous
16 1 Lee Butler
p. This tutorial walks you step-by-step through installing Redmine on a clean/fresh Ubuntu 12.04 installation.  This is intended to be a complete cookbook method for getting Redmine installed and running.  It makes no assumptions about other things being installed or configured.  Since I have had some issues when using the graphical package managers, we will be doing this from the command line prompt to keep things as clear and clean as possible.
17
18 6 Lee Butler
p. I recommend that you install any Ubuntu updates prior to beginning this process.  There are almost always some waiting to be applied after Ubuntu is first set up.
19 1 Lee Butler
20 3 Lee Butler
h2. Prerequisites:  Apache, mod-passenger, and MySQL
21 1 Lee Butler
22 3 Lee Butler
p. There are several support packages that we will install first.  The apache installation is pretty simple if you just follow the prompts and accept the defaults.
23
<pre>$ sudo apt-get install apache2 libapache2-mod-passenger</pre>
24 1 Lee Butler
25 3 Lee Butler
Installing mysql takes just a little more, so the details are spelled out.
26
27
<pre>$ sudo apt-get install mysql-server mysql-client </pre>
28
29 1 Lee Butler
p. The installation process for mysql is going to prompt you for a password for the "root" access for the database server, then ask you to confirm the password in a follow-up screen.  This sets the database adminstration password.
30
31
<pre>Package configuration                                                           
32
33
  ┌────────────────────┤ Configuring mysql-server-5.5 ├─────────────────────┐   
34
  │ While not mandatory, it is highly recommended that you set a password   │   
35
  │ for the MySQL administrative "root" user.                               │   
36
  │                                                                         │   
37
  │ If this field is left blank, the password will not be changed.          │   
38
  │                                                                         │   
39
  │ New password for the MySQL "root" user:                                 │   
40
  │                                                                         │   
41
  │ _______________________________________________________________________ │   
42
  │                                                                         │   
43
  │                                 <Ok>                                    │   
44
  │                                                                         │   
45
  └─────────────────────────────────────────────────────────────────────────┘   
46
</pre>
47
<pre>
48
  ┌────┤ Configuring mysql-server-5.5 ├──────────┐
49
  │                                              │
50
  │ Repeat password for the MySQL "root" user.   │
51
  │                                              │
52
  │                                              │
53
  │ ____________________________________________ │
54
  │                                              │
55
  │                   <Ok>                       │
56
  │                                              │
57
  └──────────────────────────────────────────────┘
58
</pre>
59
60 3 Lee Butler
h2. Installing and configuring the Ubuntu Redmine package
61
62 2 Lee Butler
p. Now it is time to install redmine itself.  
63
<pre>
64 1 Lee Butler
$ sudo apt-get install redmine redmine-mysql
65
</pre>
66
67
68
p. You want to allow dbconfig-common to configure the database when prompted so select *Yes* from the prompt in the panel below.
69
<pre>
70
Package configuration                                                           
71
                                                                                
72
 ┌──────────────────────────┤ Configuring redmine ├──────────────────────────┐  
73
 │                                                                           │  
74
 │ The redmine/instances/default package must have a database installed and  │  
75
 │ configured before it can be used.  This can be optionally handled with    │  
76
 │ dbconfig-common.                                                          │  
77
 │                                                                           │  
78
 │ If you are an advanced database administrator and know that you want to   │  
79
 │ perform this configuration manually, or if your database has already      │  
80
 │ been installed and configured, you should refuse this option.  Details    │  
81
 │ on what needs to be done should most likely be provided in                │  
82
 │ /usr/share/doc/redmine/instances/default.                                 │  
83
 │                                                                           │  
84
 │ Otherwise, you should probably choose this option.                        │  
85
 │                                                                           │  
86
 │ Configure database for redmine/instances/default with dbconfig-common?    │  
87
 │                                                                           │  
88
 │                    <Yes>                       <No>                       │  
89
 │                                                                           │  
90
 └───────────────────────────────────────────────────────────────────────────┘  
91
</pre>
92
93
p. Then you want to provide the "root" password for the database, so that the installer can create the redmine database.  This is the password set when you installed mysql.
94
95
<pre>
96
Package configuration                                                           
97
                                                                                
98
 ┌──────────────────────────┤ Configuring redmine ├──────────────────────────┐  
99
 │ Please provide the password for hte administrative account with which     │  
100
 │ this package should create its MySQL database and user.                   │  
101
 │                                                                           │  
102
 │ Password of the database's administrative user:                           │  
103
 │                                                                           │  
104
 │ ******__________________________________________________________________  │  
105
 │                                                                           │  
106
 │                   <Ok>                       <Cancel>                     │  
107
 │                                                                           │  
108
 └───────────────────────────────────────────────────────────────────────────┘  
109
</pre>
110
111
p. Tell the redmine installer we are using mysql for this installation by highlighting "mysql" from the list of database choices:
112
113
<pre>
114
Package configuration                                                           
115
                                                                                
116
 ┌──────────────────────────┤ Configuring redmine ├──────────────────────────┐  
117
 │ The redmine/instances/default package can be configured to use one of     │  
118
 │ several database types. Below, you will be presented with the available   │  
119
 │ choices.                                                                  │  
120
 │                                                                           │  
121
 │ Database type to be used by redmine/instances/default:                    │  
122
 │                                                                           │  
123
 │                                  sqlite3                                  │  
124
 │                                  pgsql                                    │  
125
 │                                  mysql                                    │  
126
 │                                                                           │  
127
 │                                                                           │  
128
 │                    <Ok>                        <Cancel>                   │  
129
 │                                                                           │  
130
 └───────────────────────────────────────────────────────────────────────────┘  
131
</pre>
132
133
p. Now you are asked to provide a password that will be used to protect the redmine database.  Redmine itself will use this when it wants to access mysql.
134
135
<pre>
136
Package configuration                                                           
137
138
 ┌──────────────────────────┤ Configuring redmine ├──────────────────────────┐  
139
 │ Please provide a password for redmine/instances/default to register with  │  
140
 │ the database server.  If left blank, a random password will be            │  
141
 │ generated.                                                                │  
142
 │                                                                           │  
143
 │ MySQL application password for redmine/instances/default:                 │  
144
 │                                                                           │  
145
 │ *******__________________________________________________________________ │  
146
 │                                                                           │  
147
 │                    <Ok>                        <Cancel>                   │  
148
 │                                                                           │  
149
 └───────────────────────────────────────────────────────────────────────────┘ 
150
</pre>
151
152
Now confirm the redmine password.
153
154
<pre>
155
Package configuration                                                           
156
                                                                                
157
   ┌────┤ Configuring redmine ├─────┐                       
158
   │                                │                       
159
   │                                │                       
160
   │ Password confirmation:         │                       
161
   │                                │                       
162
   │ *******_______________________ │                       
163
   │                                │                       
164
   │     <Ok>         <Cancel>      │                       
165
   │                                │                       
166
   └────────────────────────────────┘   
167
</pre>
168
169 26 Evgeny Bogushevich
You might be needed to install bundle
170
171
<pre>
172
$ sudo gem update
173
$ sudo gem install bundler
174
</pre>
175
176 3 Lee Butler
h2. Configuring Apache
177
178 28 Andrey Ivanov
p. You need to modify two files for apache.  The first is /etc/apache2/mods-available/passenger.conf which needs the text *PassengerDefaultUser www-data* added as seen below. Do not try to replace whole file content!
179 1 Lee Butler
<pre>
180
<IfModule mod_passenger.c>
181 29 Toshi MARUYAMA
  PassengerDefaultUser www-data
182 1 Lee Butler
  PassengerRoot /usr
183
  PassengerRuby /usr/bin/ruby
184
</IfModule>
185
</pre>
186
187
Now create a symlink to connect Redmine into the web document space:
188
<pre>
189 28 Andrey Ivanov
$ sudo ln -s /usr/share/redmine/public /var/www/html/redmine
190 1 Lee Butler
</pre>
191
192 25 Ruben Barkow
p. And modify /etc/apache2/sites-available/000-default.conf (before apache 2.4 /etc/apache2/sites-available/default) to insert the following with the other <Directory> sections so that apache knows to follow the symlink into Rails:
193 1 Lee Butler
<pre>
194 28 Andrey Ivanov
<Directory /var/www/html/redmine>
195 1 Lee Butler
	RailsBaseURI /redmine
196
	PassengerResolveSymlinksInDocumentRoot on
197
</Directory>
198
</pre>
199
200
Now restart apache:
201
<pre>
202
$ sudo service apache2 restart
203
</pre>
204
205
p. You should now be able to access redmine from the local host
206
<pre>$ firefox http://127.0.0.1/redmine
207
</pre>
208
209 27 Evgeny Bogushevich
If you see error "There was an error while trying to write to Gemfile.lock" then change ownership of Gemfile.lock or change permissions:
210
<pre>
211
$ sudo touch /usr/share/redmine/Gemfile.lock
212
$ sudo chown www-data:www-data /usr/share/redmine/Gemfile.lock
213
</pre>
214 1 Lee Butler
215
p. In the upper right corner of the browser window you should see the "Sign in" link.  Click that and enter "admin" at both the *Login:* and *Password:* prompts.  Note: _this is not the password you set during the installation process_.  Click the *Login* button.
216
217 3 Lee Butler
p. I recommend that the next thing you do is to click on *My account* in the upper right corner and change that password.  In the page that is displayed there should be a *Change password* link in the upper right of the white area of the page.  Click to change the password.
218 4 Lee Butler
219 5 Lee Butler
h2. Backing up Redmine
220 4 Lee Butler
221 14 Lee Butler
p. You should arrange a regular backup of the Redmine database and the files that users upload/attach.  The database can be dumped to a text file with:
222
<pre>/usr/bin/mysqldump -u root -p<password> redmine_default | gzip > /path/to/backups/redmine_db_`date +%y_%m_%d`.gz</pre>where <password> is the one you set when installing mysql.
223 1 Lee Butler
224 14 Lee Butler
p. The attachments are stashed in /var/lib/redmine/default/files and can be backed up with something like:
225
<pre>rsync -a /var/lib/redmine/default/files /path/to/backups/files</pre>
226 13 Lee Butler
227 14 Lee Butler
p. You can have these commands run automatically by creating a script called /etc/cron.daily/redmine that contains:
228
<pre>#!/bin/sh
229 4 Lee Butler
/usr/bin/mysqldump -u root -p<password> redmine_default | gzip > /path/to/backups/redmine_db_`date +%y_%m_%d`.gz
230 14 Lee Butler
rsync -a /var/lib/redmine/default/files /path/to/backups/files</pre>
231 13 Lee Butler
232 15 Lee Butler
p. Again, be sure to substitute the mysql root password for <password> in the mysqldump command line.  The file should be protected so that only root has read permission because you are storing the root password for your mysql installation in this file.  That the first line creates a new file every time the script is run.  This can eventually create a large number of backups of your database files.  You should have a script that purges old ones periodically.
233 14 Lee Butler
234 16 Lee Butler
h1. Additional semi-optional packages
235 3 Lee Butler
236
There are some services that Redmine can use that are not absolutely necessary, but are useful.  These are email and software repository/revision control systems.
237
238 16 Lee Butler
h2. Email setup
239 3 Lee Butler
240 19 Lee Butler
p. At some point you will probably want Redmine to be able to send email.  For this you will need to install and configure email.  This can be achieved by installing the *postfix* package.  I do not recommend the exim4 package, as there have been some incompatibilities in the way the "sendmail" command line is handled between Redmine and exim4.  Unless everyone has an email account on the redmine server you will want to set up external email as a full internet host.  Once email service is installed, you will have to restart apache for Redmine to know that it has access to email services.
241 3 Lee Butler
242 20 Lee Butler
<pre>$ sudo apt-get install postfix</pre>
243 1 Lee Butler
244 16 Lee Butler
p. Now that you can send email, you have to tell Redmine about it.  You need to create/edit the file */etc/redmine/default/configuration.yml* and add the following lines:
245
<pre>
246
production:
247
  email_delivery:
248
    delivery_method: :sendmail
249
</pre>
250
251
Then restart apache so that Redmine reloads the configuration file:
252
253 18 Lee Butler
<pre>$ sudo service apache2 restart</pre>
254
255 16 Lee Butler
h2. Revision control repository setup
256 3 Lee Butler
257
p. In order to have your software repository on the system Redmine will need the corresponding software installed.  
258
259
<pre>$ sudo apt-get install git subversion cvs mercurial
260
$ sudo service apache2 restart
261
</pre>
262
263
That covers it as far as I have gotten in my use of Redmine to date.