aboutsummaryrefslogtreecommitdiffstats
path: root/doc/dev_beginner.bb
blob: 79d9e1c4de33f85c14e5a46fe49986e7ac83840e (plain) (blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
[h2]You want to contribute code?[/h2]
[b]...and don't know how to start?[/b]
Then this is for you.

This manual will guided you step-by-step to:
[list]
[*] debug the Red Matrix (PHP),
[*] contribute code to the project,
[*] optionally - do it all from inside a virtual machine
[/list]

This manual was tested for
[list]
[*] Lubuntu (Ubuntu 14.0) as host OS
[*] Debian (Wheezy) as guest OS running in a VM
[/list]

[h2]Content[/h2]

In this manual you will
[list=1]
[*] Install a Virtual Machine (KVM)
[*] Install Apache Web Server
[*] Install PHP, MySQL, phpMyAdmin
[*] Fork the project on github to be able to contribute
[*] Install the RED Matrix
[*] Debug the server via eclipse
[*] Contribute your changes via github
[/list]

[h2]Install a Virtual Machine (KVM)[/h2]

[url=https://wiki.debian.org/KVM]Here[/url] the installation guide for Linux Debian.
The summary:
[list=1]
[*] install KVM
[code]# apt-get install qemu-kvm libvirt-bin[/code]
[*] add yourself to the group libvirt [code]# adduser <youruser> libvirt[/code]
[*] install gui to manage virtual machines [code]# apt-get install virt-manager[/code]
[*] download an operating system to run inside the vm ([url=http://ftp.nl.debian.org/debian/dists/wheezy/main/installer-amd64/current/images/netboot/mini.iso]mini.iso[/url])
[*] start the virt manager
- create new virtual machine (click on icon)
- choose your iso image (just downloaded) as installation source
- optional: configure the new vm: ram, cpu's,...
- start virtual machine > result: linux debian starts in a new window.
[*] (optional) avoid network errors after restart of host os
[code]# virsh net-start default
# virsh net-autostart default[/code]
[/list]


[h2]Install Apache Webserver[/h2]

Open a terminal and make yourself root
[code]su -l[/code]

Create the standard group for the Apache webserver
[code]groupadd www-data[/code]
might exist already

[code]usermod -a -G www-data www-data[/code]

Check if the system is really up to date
[code]apt-get update
apt-get upgrade[/code]

Optional restart services after installation
[code]reboot[/code]

If you restarted, make yourself root
[code]su -l[/code]

Install Apache: [code]
apt-get install apache2 apache2-doc apache2-utils[/code]

Open webbrowser on PC and check [url=localhost]localhost[/url]
Should show you a page like "It works"

(Source [url=http://www.manfred-steger.de/tuts/20-der-eigene-webserver-mit-dem-raspberry-pi#]http://www.manfred-steger.de/tuts/20-der-eigene-webserver-mit-dem-raspberry-pi#[/url])


[h2]Install PHP, MySQL, phpMyAdmin[/h2]

[code]su -l
apt-get install libapache2-mod-php5 php5 php-pear php5-xcache php5-curl php5-mcrypt php5-xdebug
apt-get install php5-mysql
apt-get install mysql-server mysql-client[/code]
enter and note the mysql passwort

Optional since its already enabled during phpmyadmin setup
[code]
php5enmod mcrypt
[/code]

Install php myadmin
[code]apt-get install phpmyadmin[/code]

Configuring phpmyadmin
- Select apache2 (hint: use the tab key to select)
- Configure database for phpmyadmin with dbconfig-common?: Choose Yes

(Source #^[url=http://www.manfred-steger.de/tuts/20-der-eigene-webserver-mit-dem-raspberry-pi#]http://www.manfred-steger.de/tuts/20-der-eigene-webserver-mit-dem-raspberry-pi#[/url])

[b]Enable rewrite[/b]

The default installation of Apache2 comes with mod_rewrite installed. To check whether this is the case, verify the existence of /etc/apache2/mods-available/rewrite.load

[code]
root@debian /var/www $ nano /etc/apache2/mods-available/rewrite.load
[/code]

 (You should find the content: LoadModule rewrite_module /usr/lib/apache2/modules/mod_rewrite.so)
To enable and load mod_rewrite, do the rest of steps.
Create a symbolic link in /etc/apache2/mods-enabled

[code]
cd /var/www
root@debian /var/www $ a2enmod rewrite
[/code]

Then open up the following file, and replace every occurrence of "AllowOverride None" with "AllowOverride all".

[code]
root@debian /var/www $nano /etc/apache2/apache2.conf
[/code]
or
[code]
root@debian:/var# gedit /etc/apache2/sites-enabled/000-default 
[/code]

Finally, restart Apache2.

[code]
root@debian /var/www $service apache2 restart
[/code]

[b]Test installation[/b]

[code]cd /var/www[/code]

create a php file to test the php installation[code]nano phpinfo.php[/code]

Insert into the file:
[code]
<?php
  phpinfo();
?>
[/code]
(save CTRL+0, ENTER, CTRL+X)

open webbrowser on PC and try #^[url=http://localhost/phpinfo.php]http://localhost/phpinfo.php[/url] (page shows infos on php)

connect phpMyAdmin with MySQL database [code]nano /etc/apache2/apache2.conf
[/code]
- CTRL+V... to the end of the file
- Insert at the end of the file:  (save CTRL+0, ENTER, CTRL+X)[code]Include /etc/phpmyadmin/apache.conf[/code]

restart apache
[code]/etc/init.d/apache2 restart
apt-get update
apt-get upgrade
reboot[/code]

[b]phpMyAdmin[/b]

open webbrowser on PC and try #^[url=http://localhost/phpmyadmin]http://localhost/phpmyadmin[/url]

(Source #^[url=http://www.manfred-steger.de/tuts/20-der-eigene-webserver-mit-dem-raspberry-pi#]http://www.manfred-steger.de/tuts/20-der-eigene-webserver-mit-dem-raspberry-pi#[/url])


[b]Create an empty database... that is later used by RED[/b]

open webbrowser on PC and try #^[url=http://localhost/phpmyadmin]http://localhost/phpmyadmin[/url]

Create an empty database, for example named "red".
Create a database user, for example "red".
Grant all rights for the user "red" to the database "red".

Note the access details (hostname, username, password, database name).


[h2]Fork the project on github to be able to contribute[/h2]

Please follow the instruction in the offiical [url=http://git-scm.com/book/en/v2/GitHub-Contributing-to-a-Project] documentation[/url] of git.
It is a good idea to read the whole manual! Git is different to other version control systems in many ways.

Now you should
[list]
[*] create an account at github.com
[*] fork https://github.com/friendica/red
[*] fork https://github.com/friendica/red-addons
[/list]

If you not want to use GIT from the command line - there is a usefull Eclipse plugin named ""Eclipse Mylyn to GitHub connector".


[h2]Install RED and its Addons[/h2]

You should have created an account on github and forked the projects befor you procceed.

Delete the directory www
[code]root@debian /var/www/html $ cd ..
rm -R www/
[/code]

Install git (and optionally git-gui a client gui)
[code]apt-get install git git-gui[/code]

Download the main project red and red-addons
[code]
root@debian:/var# git clone https://github.com/yourname/red www
root@debian:/var# cd www/
root@debian:/var/www# git clone https://github.com/yourname/red-addons addon
[/code]

Make this extra folder
[code]
root@debian:/var/www# mkdir -p "store/[data]/smarty3"
[/code]

Create .htconfig.php and make it writable by the webserver
[code]
root@debian:/var# cd www/
root@debian:/var/www# chmod ou+w .htconfig.php
[/code]

Make user www-data (webserver) is the owner all the project files
[code]
root@debian:/var/www# cd ..
root@debian:/var# chown -R www-data:www-data www/
[/code]

Add yourself ("surfer" in this example) to the group www-data. Why? Later you want to modify files in eclipse or in another editor.
Then make all files writable by the group www-date you are now a member of.
[code]
root@debian:/var/www# usermod -G www-data surfer
root@debian:/var# chmod -R  g+w www/
[/code]

Restart the computer (or vm)
If you are still not able to modify the project files you can check the members of the group www-data with
[code]
cat /etc/group
[/code]

Open http://localhost and init the matrix

Befor you register a first user switch off the registration mails.
Open /var/www/.htconfig.php
and make sure "0" is set in this line
[code]
$a->config['system']['verify_email'] = 0;
[/code]
You should be able to change the file as "yourself" (instead of using root or www-data).

Important!
Run the poller  to pick up the recent "public" postings of your friends
Set up a cron job or scheduled task to run the poller once every 5-10
minutes to pick up the recent "public" postings of your friends

[code]
crontab -e
[/code]

Add
[code]
*/10 * * * * cd /var/www/; /usr/bin/php include/poller.php
[/code]

If you don't know the path to PHP type
[code]
whereis php
[/code]


[h2]Debug the server via eclipse[/h2]

[h3]Check the configuration of xdebug[/h3]

You shoud already have installed xdebug in the steps befor
[code]
apt-get install php5-xdebug
[/code]

Configuring Xdebug

Open your terminal and type as root (su -l)
[code]
gedit /etc/php5/mods-available/xdebug.ini
[/code]

if the file is empty try this location
[code]
gedit /etc/php5/conf.d/xdebug.ini
[/code]

That command should open the text editor gedit with the Xdebug configuration file
At the end of the file content append the following text

xdebug.remote_enable=on
xdebug.remote_handler=dbgp
xdebug.remote_host=localhost
xdebug.remote_port=9000

Save changes and close the editor.
In you terminal type to restart the web server.
[code]
service apache2 restart
[/code]


[h3]Install Eclipse and start debugging[/h3]

Install eclipse.
Start eclipse with default worspace (or as you like)

Install the PHP plugin
Menu > Help > Install new software...
Install "PHP Developnent Tools ..."

Optionally - Install the GitHub connector plugin
Menu > Help > Install new software...
Install "Eclipse Mylyn to GitHub connector"

Configure the PHP plugin
Menu > Window > Preferences...
> General > Webbrowser > Change to "Use external web browser"
> PHP > Debug > Debug Settings > PHP Debugger > Change to "XDebug"

Create a new PHP project
Menu > File > New Project > Choose PHP > "PHP Project"
> Choose Create project at existing location" and "/var/www"

Start debugging
Open index.php and "Debug as..."
Choose as Launch URL: "http://localhost/"

Expected:
[list]
[*] The web browser starts
[*] The debugger will stop at the first php line
[/list]


[h2]Contribute your changes via github[/h2]

There is a related page in this docs: [zrl=[baseurl]/help/git_for_non_developers]Git for Non-Developers[/zrl].
As stated befor it is recommended to read the official documentation [url=http://git-scm.com/book/en/v2/GitHub-Contributing-to-a-Project]GitHub-Contributing-to-a-Project[/url] of git.

Eclipse has a usefull plugin for GIT: "Eclipse Mylyn to GitHub connector".

Make sure you have set your data
[code]
surfer@debian:/var/www$ git config --global user.name "Your Name"
surfer@debian:/var/www$ git config --global user.email "your@mail.com"
[/code]

Create a descriptive topic branch
[code]
surfer@debian:/var/www$ git checkout -b dev_beginning
[/code]

Make sure your local repository is up-to-date with the main project.
Add the original repository as a remote named upstream if not done yet
[code]
surfer@debian:/var/www$ git remote add upstream https://github.com/friendica/red
[/code]

Fetch the newest work from that remote
[code]
surfer@debian:/var/www$ git fetch upstream
surfer@debian:/var/www$ git merge upstream/master
[/code]

Hint: You can list the branches
[code]
surfer@debian:/var/www$ git branch -v
[/code]

Make your changes. In this example it is a new doc file.

Check your modifications
[code]
surfer@debian:/var/www$ git status
[/code]

Add (stage) the new file
[code]
surfer@debian:/var/www$ git add doc/dev_beginner.bb
[/code]

Commit the changes to your local branch. This will open an editor to provide a message.
[code]
surfer@debian:/var/www$ git commit -a
[/code]

Push back up to the same topic branch online
[code]
surfer@debian:/var/www$ git push
[/code]

Now you can go to your (online) account at github and create the pull request.

In case the main devolpers want you to change something.
Make the changes, check them, commit (to local repository), push (to online repository)
[code]
surfer@debian:/var/www$ git status
surfer@debian:/var/www$ git commit -a -m "added modification of branch"
surfer@debian:/var/www$ git push dev_beginning
[/code]


#include doc/macros/main_footer.bb;