Download as
Browse Code »

Commit af25d9e0c38a19ce95d5bf278e360f5f230001b8

Authored by Aurélio A. Heckert
1 parent 70a3c042
Exists in staging and in 42 other branches all_pending_tasks_api, api-articles-period, api_roles, caching-rails4, captcha_serpro_plugin, comments_permissions, content-manager-hostspot, elasticsearch, elasticsearch_api, elasticsearch_categories, elasticsearch_filter, elasticsearch_sort, elasticsearch_to_merge, elasticsearch_view, environment-exposes-api, export-comment-api, export-comment-paragraph, export_data, external_followers, federation-webfinger, federation_followers, federation_followers_backend, federation_oauth_provider, federation_webfinger, fix_event_date_issue, fix_notification_email, fix_string_downcase_and_upcase, follower_permition, json_cookie_serializer, login-captcha, master, master_profile_followers, oauth_external_login, oauth_login, private-scraps, private-scraps-rebase, production, production-vendorized, profile_api_improvements, tasks_keep_filter_params, user_mention, webfinger_server

correct markdown of some descriptive files

Showing 11 changed files with 563 additions and 782 deletions   Show diff stats
AUTHORS.md
  Diff comments   View file @af25d9e
1   -If you are not listed here, but should be, please write to the noosfero mailing
2   -list: http://listas.softwarelivre.org/cgi-bin/mailman/listinfo/noosfero-dev
3   -(this list requires subscription to post, but since you are an author of
4   -noosfero, that's not a problem).
  1 +If you are not listed here, but should be, please write to the noosfero mailing list: http://listas.softwarelivre.org/cgi-bin/mailman/listinfo/noosfero-dev (this list requires subscription to post, but since you are an author of noosfero, that's not a problem).
5 2  
6 3 Developers
7 4 ==========
... ...
INSTALL.awstats.md
  Diff comments   View file @af25d9e
1   -= AWStats setup for Noosfero
  1 +AWStats setup for Noosfero
  2 +==========================
2 3  
3   -AWStats is a free powerful and featureful tool that generates advanced web,
4   -streaming, ftp or mail server statistics, graphically.
  4 +AWStats is a free powerful and featureful tool that generates advanced web, streaming, ftp or mail server statistics, graphically.
5 5  
6   -See http://awstats.sourceforge.net/
  6 +See http://awstats.sourceforge.net
7 7  
8 8 This guide supposes that the Noosfero server is running GNU/Linux Debian Squeeze.
9 9  
10   -1. Install AWStats
  10 +### 1. Install AWStats
11 11  
12   -# apt-get install awstats libgeo-ip-perl geoip-database
  12 + # apt-get install awstats libgeo-ip-perl geoip-database
13 13  
14   -2. Basic setup
  14 +### 2. Basic setup
15 15  
16 16 Create AWStats config file:
  17 +`/etc/awstats/awstats.<domain>.conf`
17 18  
18   - * /etc/awstats/awstats.<domain>.conf
  19 + Include "/etc/awstats/awstats.conf"
  20 + Include "/etc/noosfero/awstats-noosfero.conf"
  21 + SiteDomain="<domain>"
  22 + HostAliases="<domain-aliases>"
19 23  
20   -Include "/etc/awstats/awstats.conf"
21   -Include "/etc/noosfero/awstats-noosfero.conf"
22   -SiteDomain="<domain>"
23   -HostAliases="<domain-aliases>"
  24 +`<domain>` should be the domain used in your Noosfero server (eg.: `softwarelivre.org`) and the `<domain-aliases>` should be a list with all aliases that you configured in apache (eg.: `www.softwarelivre.org`, `www2.softwarelivre.org`, etc).
24 25  
25   -<domain> should be the domain used in your Noosfero server (eg.:
26   -softwarelivre.org) and the <domain-aliases> should be a list with all aliases
27   -that you configured in apache (eg.: www.softwarelivre.org
28   -www2.softwarelivre.org etc).
  26 +This setup is considering that the Noosfero server is running varnish (see `INSTALL.varnish`) and [varnishncsa-vhost](http://gitorious.org/varnisnncsa-vhost).
29 27  
30   -This setup is considering that the Noosfero server is running varnish (see
31   -INSTALL.varnish) and varnishncsa-vhost [1].
32   -
33   -[1] http://gitorious.org/varnisnncsa-vhost
34   -
35   -3. Running AWStats for the first time
  28 +### 3. Running AWStats for the first time
36 29  
37 30 Run awstats by hand via command line:
38 31  
39   -# /usr/lib/cgi-bin/awstats.pl -config=<domain>
  32 + # /usr/lib/cgi-bin/awstats.pl -config=<domain>
40 33  
41 34 You should see something as below as output of this command:
42 35  
43   -# /usr/lib/cgi-bin/awstats.pl -config=softwarelivre.org
44   -Create/Update database for config "/etc/awstats/awstats.softwarelivre.org.conf" by AWStats version 6.7 (build 1.892)
45   -From data in log file "/var/log/varnish/varnishncsa-vhost.log"...
46   -Phase 1 : First bypass old records, searching new record...
47   -Searching new records from beginning of log file...
48   -Phase 2 : Now process new records (Flush history on disk after 20000 hosts)...
49   -Jumped lines in file: 0
50   -Parsed lines in file: 452
51   - Found 0 dropped records,
52   - Found 0 corrupted records,
53   - Found 0 old records,
54   - Found 452 new qualified records.
  36 + # /usr/lib/cgi-bin/awstats.pl -config=softwarelivre.org
  37 + Create/Update database for config "/etc/awstats/awstats.softwarelivre.org.conf" by AWStats version 6.7 (build 1.892)
  38 + From data in log file "/var/log/varnish/varnishncsa-vhost.log"...
  39 + Phase 1 : First bypass old records, searching new record...
  40 + Searching new records from beginning of log file...
  41 + Phase 2 : Now process new records (Flush history on disk after 20000 hosts)...
  42 + Jumped lines in file: 0
  43 + Parsed lines in file: 452
  44 + Found 0 dropped records,
  45 + Found 0 corrupted records,
  46 + Found 0 old records,
  47 + Found 452 new qualified records.
55 48  
56   -4. Setup frontend
  49 +### 4. Setup frontend
57 50  
58   -You should create a new subdomain to have access to the AWStats, usually
59   -something like tools.<domain> (eg.: tools.softwarelivre.org). Don't include
60   -this subdomain in HostAliases in the AWStats neither in SiteAlias in the
61   -Apache.
  51 +You should create a new subdomain to have access to the AWStats, usually something like tools.<domain> (eg.: tools.softwarelivre.org). Don't include this subdomain in HostAliases in the AWStats neither in SiteAlias in the Apache.
62 52  
63   -# cp /usr/share/doc/awstats/examples/apache.conf /etc/apache2/conf.d/awstats.conf
64   -# invoke-rc.d apache2 restart
  53 + # cp /usr/share/doc/awstats/examples/apache.conf /etc/apache2/conf.d/awstats.conf
  54 + # invoke-rc.d apache2 restart
65 55  
66   -ps.: Don't forget to change the port /etc/apache/sites-enabled/000-default to
67   -8080.
  56 +ps.: Don't forget to change the port `/etc/apache/sites-enabled/000-default` to `8080`.
68 57  
69   -Try: http://tools.<domain>/cgi-bin/awstats.pl?config=<domain>
70   -(eg.: http://tools.softwarelivre.org/cgi-bin/awstats.pl?config=softwarelivre.org).
  58 +Try: `http://tools.<domain>/cgi-bin/awstats.pl?config=<domain>`
  59 +(eg.: `http://tools.softwarelivre.org/cgi-bin/awstats.pl?config=softwarelivre.org`).
71 60  
72   -5. Schedule AWStats in crontab
  61 +### 5. Schedule AWStats in crontab
73 62  
74   - * /etc/cron.d/awstats
  63 +`/etc/cron.d/awstats`
75 64  
76   -0,10,20,30,40,50 * * * * www-data [ -x /usr/lib/cgi-bin/awstats.pl -a -f /etc/awstats/awstats.<domain>.conf -a -r /var/log/apache/access.log ] && /usr/lib/cgi-bin/awstats.pl -config=<domain> -update >/dev/null
  65 + 0,10,20,30,40,50 * * * * www-data [ -x /usr/lib/cgi-bin/awstats.pl -a -f /etc/awstats/awstats.<domain>.conf -a -r /var/log/apache/access.log ] && /usr/lib/cgi-bin/awstats.pl -config=<domain> -update >/dev/null
77 66  
78 67 Done, check the AWStats frontend after one or two days to see if everything is working properly.
... ...
INSTALL.chat.md
  Diff comments   View file @af25d9e
1   -== XMPP/Chat Client Setup
  1 +XMPP/Chat Client Setup
  2 +======================
2 3  
3 4 To configure XMPP/BOSH in Noosfero you need:
4 5  
... ... @@ -8,96 +9,87 @@ To configure XMPP/BOSH in Noosfero you need:
8 9  
9 10 If you use Debian 6.0 (squeeze):
10 11  
11   -# apt-get install librestclient-ruby pidgin-data ruby1.8-dev
12   -# gem install SystemTimer
  12 + # apt-get install librestclient-ruby pidgin-data ruby1.8-dev
  13 + # gem install SystemTimer
13 14  
14   -The samples of config file to configure a XMPP/BOSH server with
15   -ejabberd, postgresql and apache2 can be found at util/chat directory.
  15 +The samples of config file to configure a XMPP/BOSH server with ejabberd, postgresql and apache2 can be found at util/chat directory.
16 16  
17   -== XMPP/Chat Server Setup
  17 +XMPP/Chat Server Setup
  18 +======================
18 19  
19 20 This is a step-by-step guide to get a XMPP service working, in a Debian system.
20 21  
21   -1. Install the required packages
  22 +## 1. Install the required packages
22 23  
23   -# apt-get install ejabberd odbc-postgresql
  24 + # apt-get install ejabberd odbc-postgresql
24 25  
25   -2. Ejabberd configuration
  26 +## 2. Ejabberd configuration
26 27  
27   -All the following changes must be done in config file:
  28 +All the following changes must be done in config file: `/etc/ejabberd/ejabberd.cfg`
28 29  
29   - /etc/ejabberd/ejabberd.cfg
  30 +### 2.1. Set the default admin user
30 31  
31   - 2.1. Set the default admin user
  32 + { acl, admin, { user, "john", "www.example.com" } }.
  33 + { acl, admin, { user, "bart", "www.example.com" } }.
32 34  
33   -{ acl, admin, { user, "john", "www.example.com" } }.
34   -{ acl, admin, { user, "bart", "www.example.com" } }.
  35 +### 2.2. Set the default host
35 36  
36   - 2.2. Set the default host
  37 + { hosts, [ "www.example.com" ] }.
37 38  
38   -{ hosts, [ "www.example.com" ] }.
  39 +### 2.3. Http-Bind activation
39 40  
40   - 2.3. Http-Bind activation
  41 + { 5280, ejabberd_http, [
  42 + http_bind,
  43 + web_admin
  44 + ]
  45 + }
41 46  
42   -{ 5280, ejabberd_http, [
43   - http_bind,
44   - web_admin
45   - ]
46   -}
  47 + (...)
47 48  
48   -(...)
  49 + { modules, [
  50 + {mod_http_bind, []},
  51 + ...
  52 + ] }.
49 53  
50   -{ modules, [
51   - {mod_http_bind, []},
52   - ...
53   -] }.
  54 +Ejabberd creates semi-anonymous rooms by default, but Noosfero's Jabber client needs non-anonymous room, then we need to change default params of creation rooms in ejabberd to create non-anonymous rooms.
54 55  
55   -Ejabberd creates semi-anonymous rooms by default, but Noosfero's Jabber client
56   -needs non-anonymous room, then we need to change default params of creation
57   -rooms in ejabberd to create non-anonymous rooms.
  56 +In non-anonymous rooms the jabber service sends the new occupant's full JID to all occupants in the room [[1]].
58 57  
59   -In non-anonymous rooms the jabber service sends the new occupant's full JID to
60   -all occupants in the room[1].
  58 +Add option "`{default_room_options, [{anonymous, false}]}`" to `/etc/ejabberd/ejabberd.cfg` in mod_muc session. See below:
61 59  
62   -Add option "{default_room_options, [{anonymous, false}]}" to
63   -/etc/ejabberd/ejabberd.cfg in mod_muc session. See below:
  60 + { mod_muc, [
  61 + %%{host, "conference.@HOST@"},
  62 + {access, muc},
  63 + {access_create, muc},
  64 + {access_persistent, muc},
  65 + {access_admin, muc_admin},
  66 + {max_users, 500},
  67 + {default_room_options, [{anonymous, false}]}
  68 + ]},
64 69  
65   -{ mod_muc, [
66   - %%{host, "conference.@HOST@"},
67   - {access, muc},
68   - {access_create, muc},
69   - {access_persistent, muc},
70   - {access_admin, muc_admin},
71   - {max_users, 500},
72   - {default_room_options, [{anonymous, false}]}
73   -]},
  70 +[1]: http://xmpp.org/extensions/xep-0045.html#enter-nonanon
74 71  
75   -[1] - http://xmpp.org/extensions/xep-0045.html#enter-nonanon
76 72  
77   -
78   - 2.4. Authentication method
  73 +### 2.4. Authentication method
79 74  
80 75 To use Postgresql through ODBC, the following modifications must be done:
81 76  
82 77 * Disable the default method:
83   -
84   -{auth_method, internal}.
  78 + `{auth_method, internal}.`
85 79  
86 80 * Enable autheticantion through ODBC:
87   -
88   -{auth_method, odbc}.
  81 + `{auth_method, odbc}.`
89 82  
90 83 * Set database server name
  84 + `{odbc_server, "DSN=PostgreSQLEjabberdNoosfero"}.`
91 85  
92   -{odbc_server, "DSN=PostgreSQLEjabberdNoosfero"}.
93 86  
  87 +### 2.5. Increase the shaper traffic limit
94 88  
95   - 2.5. Increase the shaper traffic limit
  89 + { shaper, normal, { maxrate, 10000000 } }.
96 90  
97   -{ shaper, normal, { maxrate, 10000000 } }.
98 91  
99   -
100   - 2.6. Disable unused modules
  92 +### 2.6. Disable unused modules
101 93  
102 94 Unused modules can be disabled, for example:
103 95  
... ... @@ -110,149 +102,135 @@ Unused modules can be disabled, for example:
110 102 * mod_register
111 103  
112 104  
113   - 2.7. Enable ODBC modules
  105 +### 2.7. Enable ODBC modules
114 106  
115 107 * mod_privacy -> mod_privacy_odbc
116 108 * mod_private -> mod_private_odbc
117 109 * mod_roster -> mod_roster_odbc
118 110  
119   -3. Configuring Postgresql
  111 +## 3. Configuring Postgresql
120 112  
121 113 Login as noosfero user, and execute:
122 114  
123   - $ psql noosfero < /path/to/noosfero/util/chat/postgresql/ejabberd.sql
124   -
125   -Where 'noosfero' may need to be replace by the name of the database used for
126   -Noosfero.
  115 + $ psql noosfero < /path/to/noosfero/util/chat/postgresql/ejabberd.sql
127 116  
128   -This will create a new schema inside the noosfero database, called 'ejabberd'.
  117 +Where `noosfero` may need to be replace by the name of the database used for Noosfero.
129 118  
130   -Note 'noosfero' user should have permission to create Postgresql schemas. Also,
131   -there should be at least one domain with 'is_default = true' in 'domains'
132   -table, otherwise people won't be able to see their friends online.
  119 +This will create a new schema inside the noosfero database, called `ejabberd`.
133 120  
  121 +Note `noosfero` user should have permission to create Postgresql schemas. Also, there should be at least one domain with `is_default = true` in `domains` table, otherwise people won't be able to see their friends online.
134 122  
135   -4. ODBC configuration
  123 +## 4. ODBC configuration
136 124  
137 125 The following files must be created:
138 126  
139   - * /etc/odbc.ini
  127 +`/etc/odbc.ini`:
140 128  
141   -[PostgreSQLEjabberdNoosfero]
142   -Description = PostgreSQL Noosfero ejabberd database
143   -Driver = PostgreSQL Unicode
144   -Trace = No
145   -TraceFile = /tmp/psqlodbc.log
146   -Database = noosfero
147   -Servername = localhost
148   -UserName = <DBUSER>
149   -Password = <DBPASS>
150   -Port =
151   -ReadOnly = No
152   -RowVersioning = No
153   -ShowSystemTables = No
154   -ShowOidColumn = No
155   -FakeOidIndex = No
156   -ConnSettings = SET search_path TO ejabberd
  129 + [PostgreSQLEjabberdNoosfero]
  130 + Description = PostgreSQL Noosfero ejabberd database
  131 + Driver = PostgreSQL Unicode
  132 + Trace = No
  133 + TraceFile = /tmp/psqlodbc.log
  134 + Database = noosfero
  135 + Servername = localhost
  136 + UserName = <DBUSER>
  137 + Password = <DBPASS>
  138 + Port =
  139 + ReadOnly = No
  140 + RowVersioning = No
  141 + ShowSystemTables = No
  142 + ShowOidColumn = No
  143 + FakeOidIndex = No
  144 + ConnSettings = SET search_path TO ejabberd
157 145  
158   - * /etc/odbcinst.ini
  146 +`/etc/odbcinst.ini`:
159 147  
160   -[PostgreSQL Unicode]
161   -Description = PostgreSQL ODBC driver (Unicode version)
162   -Driver = /usr/lib/odbc/psqlodbcw.so
163   -Setup = /usr/lib/odbc/libodbcpsqlS.so
164   -Debug = 0
165   -CommLog = 1
166   -UsageCount = 3
  148 + [PostgreSQL Unicode]
  149 + Description = PostgreSQL ODBC driver (Unicode version)
  150 + Driver = /usr/lib/odbc/psqlodbcw.so
  151 + Setup = /usr/lib/odbc/libodbcpsqlS.so
  152 + Debug = 0
  153 + CommLog = 1
  154 + UsageCount = 3
167 155  
168   - 4.1 testing all:
  156 +## 4.1 testing all:
169 157  
170   -# isql 'PostgreSQLEjabberdNoosfero'
  158 + # isql 'PostgreSQLEjabberdNoosfero'
171 159  
172   -If the configuration was done right, the message "Connected!"
173   -will be displayed.
  160 +If the configuration was done right, the message "Connected!" will be displayed.
174 161  
175 162  
176   -5. Enabling kernel polling and SMP in /etc/default/ejabberd
  163 +## 5. Enabling kernel polling and SMP in `/etc/default/ejabberd`
177 164  
178   -POLL=true
179   -SMP=auto
  165 + POLL=true
  166 + SMP=auto
180 167  
  168 +## 6. Increase the file descriptors limit for user ejabberd
181 169  
182   -6. Increase the file descriptors limit for user ejabberd
  170 +### 6.1. Uncomment this line in file `/etc/pam.d/su`:
183 171  
184   - 6.1. Uncomment this line in file /etc/pam.d/su:
  172 + session required pam_limits.so
185 173  
186   -session required pam_limits.so
  174 +### 6.2. Add this lines to file `/etc/security/limits.conf`:
187 175  
188   -
189   - 6.2. Add this lines to file /etc/security/limits.conf:
190   -
191   -ejabberd hard nofile 65536
192   -ejabberd soft nofile 65536
  176 + ejabberd hard nofile 65536
  177 + ejabberd soft nofile 65536
193 178  
194 179 Now, test the configuration:
195 180  
196   -# cat /proc/<EJABBERD_BEAM_PROCESS_PID>/limits
197   -
  181 + # cat /proc/<EJABBERD_BEAM_PROCESS_PID>/limits
198 182  
199   -7. Apache Configuration
  183 +## 7. Apache Configuration
200 184  
201 185 Apache server must be configurated as follow:
202 186  
203   - * /etc/apache2/sites-enabled/noosfero
  187 +`/etc/apache2/sites-enabled/noosfero`:
204 188  
205   -RewriteEngine On
206   -Include /usr/share/noosfero/util/chat/apache/xmpp.conf
  189 + RewriteEngine On
  190 + Include /usr/share/noosfero/util/chat/apache/xmpp.conf
207 191  
208   - * /etc/apache2/apache2.conf:
  192 +`/etc/apache2/apache2.conf`:
209 193  
210   -<IfModule mpm_worker_module>
211   - StartServers 8
212   - MinSpareThreads 25
213   - MaxSpareThreads 75
214   - ThreadLimit 128
215   - ThreadsPerChild 128
216   - MaxClients 2048
217   - MaxRequestsPerChild 0
218   -</IfModule>
  194 + <IfModule mpm_worker_module>
  195 + StartServers 8
  196 + MinSpareThreads 25
  197 + MaxSpareThreads 75
  198 + ThreadLimit 128
  199 + ThreadsPerChild 128
  200 + MaxClients 2048
  201 + MaxRequestsPerChild 0
  202 + </IfModule>
219 203  
220 204 Note: module proxy_http must be enabled:
221 205  
222   -# a2enmod proxy_http
  206 + # a2enmod proxy_http
223 207  
224   -8. DNS configuration
  208 +## 8. DNS configuration
225 209  
226   -For this point, we assume you are using BIND as your DNS server. You need to
227   -add the following entries to the DNS zone file corresponding to the domain
228   -of your noosfero site:
  210 +For this point, we assume you are using BIND as your DNS server. You need to add the following entries to the DNS zone file corresponding to the domain of your noosfero site:
229 211  
230   -_xmpp-client._tcp SRV 5 100 5222 master
231   -conference CNAME master
232   -_xmpp-client._tcp.conference SRV 5 100 5222 master
  212 + _xmpp-client._tcp SRV 5 100 5222 master
  213 + conference CNAME master
  214 + _xmpp-client._tcp.conference SRV 5 100 5222 master
233 215  
234   -If you are running a DNS server other than BIND, you will have to figure out
235   -how to create equivalente rules for your zone file. Patches to this
236   -documentation are welcome.
  216 +If you are running a DNS server other than BIND, you will have to figure out how to create equivalente rules for your zone file. Patches to this documentation are welcome.
237 217  
238   -9. Testing this Setup
  218 +## 9. Testing this Setup
239 219  
240 220 Adjust shell limits to proceed with some benchmarks and load tests:
241 221  
242   -# ulimit −s 256
243   -# ulimit −n 8192
244   -# echo 10 > /proc/sys/net/ipv4/tcp_syn_retries
  222 + # ulimit −s 256
  223 + # ulimit −n 8192
  224 + # echo 10 > /proc/sys/net/ipv4/tcp_syn_retries
245 225  
246 226 To measure the bandwidth between server and client:
247 227  
248 228 * at server side:
249   -
250   -# iperf −s
  229 + `# iperf −s`
251 230  
252 231 * at client side:
253   -
254   -# iperf −c server_ip
  232 + `# iperf −c server_ip`
255 233  
256 234 For heavy load tests, clone and use this software:
257 235  
258   -git clone http://git.holoscopio.com/git/metal/tester.git
  236 + $ git clone http://git.holoscopio.com/git/metal/tester.git
... ...
INSTALL.email.md
  Diff comments   View file @af25d9e
1   -= Noosfero email setup
  1 +Noosfero email setup
  2 +====================
2 3  
3   -If you know mail systems well, you just need to make sure that the local MTA,
4   -listening on localhost:25, is able to deliver e-mails to the internet. Any mail
5   -server will do it. You can stop reading now.
  4 +If you know mail systems well, you just need to make sure that the local MTA, listening on localhost:25, is able to deliver e-mails to the internet. Any mail server will do it. You can stop reading now.
6 5  
7   -If you are not an email specialist, then follow the instructions below. We
8   -suggest that you use the Postfix mail server, since it is easy to configure and
9   -very reliable. Just follow the instructions below.
  6 +If you are not an email specialist, then follow the instructions below. We suggest that you use the Postfix mail server, since it is easy to configure and very reliable. Just follow the instructions below.
10 7  
11 8 To install Postfix:
12 9  
13   -# apt-get install postfix
  10 + # apt-get install postfix
14 11  
15   -During the installation process, you will be asked a few questions. Your answer
16   -to them will vary in 2 cases:
  12 +During the installation process, you will be asked a few questions. Your answer to them will vary in 2 cases:
17 13  
18   -Case 1: you can send e-mails directly to the internet. This will be the case
19   -for most commercial private servers. Your answers should be:
  14 +**Case 1**: you can send e-mails directly to the internet. This will be the case for most commercial private servers. Your answers should be:
20 15  
21   - General type of mail configuration: Internet site
22   - System mail name: the name of your domain, e.g. "mysocialnetwork.com"
  16 + * General type of mail configuration: Internet site
  17 + * System mail name: the name of your domain, e.g. "mysocialnetwork.com"
23 18  
24   -Case 2: you cannot, or don't want to, send e-mail directly to the internet.
25   -This happens for example if your server is not allowed to make outbound
26   -connections on port 25, or if you want to concentrate all your outbound mail
27   -through a single SMTP server. Your answers in this case should be:
  19 +**Case 2**: you cannot, or don't want to, send e-mail directly to the internet. This happens for example if your server is not allowed to make outbound connections on port 25, or if you want to concentrate all your outbound mail through a single SMTP server. Your answers in this case should be:
28 20  
29   - General type of mail configuration: Internet with smarthost
30   - System mail name: the name of your domain, e.g. "mysocialnetwork.com"
31   - SMTP relay host: smtp.yourprovider.com
  21 + * General type of mail configuration: Internet with smarthost
  22 + * System mail name: the name of your domain, e.g. "mysocialnetwork.com"
  23 + * SMTP relay host: smtp.yourprovider.com
32 24  
33   -Note that smtp.yourprovider.com must allow your server to deliver e-mails
34   -through it. You should probably ask your servive provider about this.
  25 +Note that smtp.yourprovider.com must allow your server to deliver e-mails through it. You should probably ask your servive provider about this.
35 26  
36   -There is another possibility: if you are installing on a shared server, and
37   -don't have permission to configure the local MTA, you can instruct Noosfero to
38   -send e-mails directly through an external server. Please note that this should
39   -be your last option, since contacting an external SMTP server directly may slow
40   -down your Noosfero application server. To configure Noosfero to send e-mails
41   -through an external SMTP server, follow the instructions on
42   -http://noosfero.org/Development/SMTPMailSending
  27 +There is another possibility: if you are installing on a shared server, and don't have permission to configure the local MTA, you can instruct Noosfero to send e-mails directly through an external server. Please note that this should be your last option, since contacting an external SMTP server directly may slow down your Noosfero application server. To configure Noosfero to send e-mails through an external SMTP server, follow the instructions on http://noosfero.org/Development/SMTPMailSending
43 28  
... ...
INSTALL.md
  Diff comments   View file @af25d9e
1   -= Noosfero installation instructions from source for production environments
  1 +Noosfero installation instructions from source for production environments
  2 +==========================================================================
2 3  
3   -The instructions below can be used for setting up a Noosfero production
4   -environment from the Noosfero sources.
  4 +The instructions below can be used for setting up a Noosfero production environment from the Noosfero sources.
5 5  
6   -Before you start installing Noosfero manually, see the information about the
7   -Noosfero Debian package at http://noosfero.org/Development/DebianPackage. Using
8   -the Debian packages on a Debian stable system is the recommended method for
9   -installing production environments.
  6 +Before you start installing Noosfero manually, see the information about the Noosfero Debian package at http://noosfero.org/Development/DebianPackage. Using the Debian packages on a Debian stable system is the recommended method for installing production environments.
10 7  
11   -If you want to setup a development environment instead of a production one,
12   -stop reading this file right now and read the file HACKING instead.
  8 +If you want to setup a development environment instead of a production one, stop reading this file right now and read the file `HACKING.md` instead.
13 9  
14   -For a complete installation guide, please see the following web page:
15   -http://noosfero.org/Development/HowToInstall
  10 +For a complete installation guide, please see the following web page: http://noosfero.org/Development/HowToInstall
16 11  
17   -If you have problems with the setup, please feel free to ask questions in the
18   -development mailing list.
  12 +If you have problems with the setup, please feel free to ask questions in the development mailing list.
19 13  
20   -== Requirements
  14 +Requirements
  15 +------------
21 16  
22   -DISCLAIMER: this installation procedure is tested with Debian stable, which is
23   -currently the only recommended operating system for production usage. It is
24   -possible that you can install it on other systems, and if you do so, please
25   -report it on one of the Noosfero mailing lists, and please send a patch
26   -updating these instructions.
  17 +**DISCLAIMER**: this installation procedure is tested with Debian stable, which is currently the only recommended operating system for production usage. It is possible that you can install it on other systems, and if you do so, please report it on one of the Noosfero mailing lists, and please send a patch updating these instructions.
27 18  
28   -Noosfero is written in Ruby with the "Rails
29   -framework":http://www.rubyonrails.org, so the process of setting it up is
30   -pretty similar to other Rails applications.
  19 +Noosfero is written in Ruby with the "[Rails framework](http://www.rubyonrails.org)", so the process of setting it up is pretty similar to other Rails applications.
31 20  
32   -You need to install some packages Noosfero depends on. On Debian GNU/Linux or
33   -Debian-based systems, all of these packages are available through the Debian
34   -archive. You can install them with the following command:
  21 +You need to install some packages Noosfero depends on. On Debian GNU/Linux or Debian-based systems, all of these packages are available through the Debian archive. You can install them with the following command:
35 22  
36   - # apt-get install ruby rake po4a libgettext-ruby-util libgettext-ruby1.8 libsqlite3-ruby rcov librmagick-ruby libredcloth-ruby libwill-paginate-ruby iso-codes libfeedparser-ruby libdaemons-ruby thin tango-icon-theme libhpricot-ruby
  23 + # apt-get install ruby rake po4a libgettext-ruby-util libgettext-ruby1.8 \
  24 + libsqlite3-ruby rcov librmagick-ruby libredcloth-ruby libhpricot-ruby \
  25 + libwill-paginate-ruby iso-codes libfeedparser-ruby libdaemons-ruby thin \
  26 + tango-icon-theme
37 27  
38   -On other systems, they may or may not be available through your regular package
39   -management system. Below are the links to their homepages.
  28 +On other systems, they may or may not be available through your regular package management system. Below are the links to their homepages.
40 29  
41   -* Ruby: http://www.ruby-lang.org/
42   -* Rake: http://rake.rubyforge.org/
43   -* po4a: http://po4a.alioth.debian.org/
  30 +* Ruby: http://www.ruby-lang.org
  31 +* Rake: http://rake.rubyforge.org
  32 +* po4a: http://po4a.alioth.debian.org
44 33 * Ruby-sqlite3: http://rubyforge.org/projects/sqlite-ruby
45 34 * rcov: http://eigenclass.org/hiki/rcov
46   -* RMagick: http://rmagick.rubyforge.org/
47   -* RedCloth: http://redcloth.org/
  35 +* RMagick: http://rmagick.rubyforge.org
  36 +* RedCloth: http://redcloth.org
48 37 * will_paginate: http://github.com/mislav/will_paginate/wikis
49   -* iso-codes: http://pkg-isocodes.alioth.debian.org/
  38 +* iso-codes: http://pkg-isocodes.alioth.debian.org
50 39 * feedparser: http://packages.debian.org/sid/libfeedparser-ruby
51   -* Daemons - http://daemons.rubyforge.org/
52   -* Thin: http://code.macournoyer.com/thin/
  40 +* Daemons - http://daemons.rubyforge.org
  41 +* Thin: http://code.macournoyer.com/thin
53 42 * tango-icon-theme: http://tango.freedesktop.org/Tango_Icon_Library
54   -* Hpricot: http://hpricot.com/
  43 +* Hpricot: http://hpricot.com
55 44  
56 45 If you manage to install Noosfero successfully on other systems than Debian,
57 46 please feel free to contact the Noosfero development mailing with the
... ... @@ -62,30 +51,21 @@ As root user
62 51  
63 52 Install memcached. On Debian:
64 53  
65   -# apt-get install memcached
  54 + # apt-get install memcached
66 55  
67   -Study whether you need to raise the ammount of memory it uses for caching,
68   -depending on the demand you expect for your site. If you are going to run a
69   -high-traffic site, you will want to raise the ammount of memory reserved for
70   -caching.
  56 +Study whether you need to raise the ammount of memory it uses for caching, depending on the demand you expect for your site. If you are going to run a high-traffic site, you will want to raise the ammount of memory reserved for caching.
71 57  
72   -It is recommended that you run noosfero with its own user account. To create
73   -such an account, please do the following:
  58 +It is recommended that you run noosfero with its own user account. To create such an account, please do the following:
74 59  
75   -# adduser --system --group noosfero --shell /bin/sh --home /var/lib/noosfero
  60 + # adduser --system --group noosfero --shell /bin/sh --home /var/lib/noosfero
76 61  
77   -(note that you can change the $HOME directory of the user if you wish, here we
78   -are using /var/lib/noosfero)
  62 +(note that you can change the `$HOME` directory of the user if you wish, here we are using `/var/lib/noosfero`)
79 63  
80   -The --system option will tell adduser to create a system user, i.e. this user
81   -will not have a password and cannot login to the system directly. To become
82   -this user, you have to use sudo:
  64 +The `--system` option will tell adduser to create a system user, i.e. this user will not have a password and cannot login to the system directly. To become this user, you have to use sudo:
83 65  
84   -# sudo -u noosfero -i
85   -
86   -or
87   -
88   -# su - noosfero
  66 + # sudo -u noosfero -i
  67 + or
  68 + # su - noosfero
89 69  
90 70 As noosfero user
91 71 ================
... ... @@ -93,325 +73,262 @@ As noosfero user
93 73 downloading from git
94 74 --------------------
95 75  
96   -Here we are cloning the noosfero repository from git. Note: you will need to
97   -install git before.
  76 +Here we are cloning the noosfero repository from git. Note: you will need to install git before.
98 77  
99   -$ git clone git://gitorious.org/noosfero/noosfero.git current
100   -$ cd current
101   -$ git checkout -b stable origin/stable
  78 + $ git clone git://gitorious.org/noosfero/noosfero.git current
  79 + $ cd current
  80 + $ git checkout -b stable origin/stable
102 81  
103 82 downloading tarball
104 83 -------------------
105 84  
106 85 Note: replace 0.39.0 below from the latest stable version.
107 86  
108   -$ wget http://noosfero.org/pub/Development/NoosferoVersion00x39x00/noosfero-0.39.0.tar.gz
109   -$ tar -zxvf noosfero-0.39.0.tar.gz
110   -$ ln -s noosfero-0.39.0 current
111   -$ cd current
  87 + $ wget http://noosfero.org/pub/Development/NoosferoVersion00x39x00/noosfero-0.39.0.tar.gz
  88 + $ tar -zxvf noosfero-0.39.0.tar.gz
  89 + $ ln -s noosfero-0.39.0 current
  90 + $ cd current
112 91  
113 92 Create the thin configuration file:
114 93  
115   -$ thin -C config/thin.yml -e production config
  94 + $ thin -C config/thin.yml -e production config
116 95  
117   -Edit config/thin.yml to suit your needs. Make sure your apache
118   -configuration matches the thin cluster configuration, specially in respect
119   -to the ports and numbers of thin instances.
  96 +Edit config/thin.yml to suit your needs. Make sure your apache configuration matches the thin cluster configuration, specially in respect to the ports and numbers of thin instances.
120 97  
121   -Note: currently Noosfero only supports Rails 2.3.5, which is the version in
122   -Debian Squeeze. If you have a Rails version newer than that, Noosfero will
123   -probably not work. You can install Rails 2.3.5 into your Noosfero installation
124   -with the following procedure:
  98 +*Note*: currently Noosfero only supports Rails 2.3.5, which is the version in Debian Squeeze. If you have a Rails version newer than that, Noosfero will probably not work. You can install Rails 2.3.5 into your Noosfero installation with the following procedure:
125 99  
126   -$ cd /var/lib/noosfero/current/vendor
127   -$ wget http://ftp.de.debian.org/debian/pool/main/r/rails/rails_2.3.5.orig.tar.gz
128   -$ tar xzf rails_2.3.5.orig.tar.gz
129   -$ ln -s rails-2.3.5 rails
  100 + $ cd /var/lib/noosfero/current/vendor
  101 + $ wget http://ftp.de.debian.org/debian/pool/main/r/rails/rails_2.3.5.orig.tar.gz
  102 + $ tar xzf rails_2.3.5.orig.tar.gz
  103 + $ ln -s rails-2.3.5 rails
130 104  
131 105 As root user
132 106 ============
133 107  
134 108 Setup Noosfero log and tmp directories:
135 109  
136   -# cd /var/lib/noosfero/current
137   -# ./etc/init.d/noosfero setup
  110 + # cd /var/lib/noosfero/current
  111 + # ./etc/init.d/noosfero setup
138 112  
139   -Now it's time to setup the database. In this example we are using PostgreSQL,
140   -so if you are planning to use a different database this steps won't apply.
  113 +Now it's time to setup the database. In this example we are using PostgreSQL, so if you are planning to use a different database this steps won't apply.
141 114  
142   -# apt-get install postgresql libpgsql-ruby
143   -# su postgres -c 'createuser noosfero -S -d -R'
  115 + # apt-get install postgresql libpgsql-ruby
  116 + # su postgres -c 'createuser noosfero -S -d -R'
144 117  
145   -By default Rails will try to connect on postgresql through 5432 port,
146   -you can check it on /etc/postgresql/8.4/main/postgresql.conf file.
  118 +By default Rails will try to connect on postgresql through 5432 port, you can check it on `/etc/postgresql/8.4/main/postgresql.conf` file.
147 119  
148 120 Restart postgresql:
  121 + # invoke-rc.d postgresql restart
149 122  
150   -# invoke-rc.d postgresql restart
151   -
152   -Noosfero needs a functional e-mail setup to work: the local mail system should
153   -be able to deliver e-mail to the internet, either directly or through an
154   -external SMTP server. Please check the documentation at the INSTALL.email file.
  123 +Noosfero needs a functional e-mail setup to work: the local mail system should be able to deliver e-mail to the internet, either directly or through an external SMTP server. Please check the documentation at the INSTALL.email file.
155 124  
156 125 As noosfero user
157 126 ================
158 127  
159 128 Now create the databases:
160 129  
161   -$ cd /var/lib/noosfero/current
162   -$ createdb noosfero_production
163   -$ createdb noosfero_development
164   -$ createdb noosfero_test
  130 + $ cd /var/lib/noosfero/current
  131 + $ createdb noosfero_production
  132 + $ createdb noosfero_development
  133 + $ createdb noosfero_test
165 134  
166   -The development and test databases are actually optional. If you are creating a
167   -stricly production server, you will probably not need them.
  135 +The development and test databases are actually optional. If you are creating a stricly production server, you will probably not need them.
168 136  
169   -Now we want to configure Noosfero for accessing the database we just created.
170   -To do that, you can 1) copy config/database.yml.pgsql to config/database.yml,
171   -or create config/database.yml from scratch with the following content:
  137 +Now we want to configure Noosfero for accessing the database we just created. To do that, you can 1) copy `config/database.yml.pgsql` to `config/database.yml`, or create `config/database.yml` from scratch with the following content:
172 138  
173   - production:
174   - adapter: postgresql
175   - encoding: unicode
176   - database: noosfero_production
177   - username: noosfero
  139 + production:
  140 + adapter: postgresql
  141 + encoding: unicode
  142 + database: noosfero_production
  143 + username: noosfero
178 144  
179 145 Now, to test the database access, you can fire the Rails database console:
180 146  
181   -$ ./script/dbconsole production
  147 + $ ./script/dbconsole production
182 148  
183   -If it connects to your database, then everything is fine. If you got an error
184   -message, then you have to check your database configuration.
  149 +If it connects to your database, then everything is fine. If you got an error message, then you have to check your database configuration.
185 150  
186 151 Create the database structure:
187 152  
188   -$ RAILS_ENV=production rake db:schema:load
  153 + $ RAILS_ENV=production rake db:schema:load
189 154  
190 155 Compile the translations:
191 156  
192   -$ RAILS_ENV=production rake noosfero:translations:compile
  157 + $ RAILS_ENV=production rake noosfero:translations:compile
193 158  
194   -Now we must create some initial data. To create your default environment
195   -(the first one), run the command below:
  159 +Now we must create some initial data. To create your default environment (the first one), run the command below:
196 160  
197   -$ RAILS_ENV=production ./script/runner 'Environment.create!(:name => "My environment", :is_default => true)'
  161 + $ RAILS_ENV=production ./script/runner 'Environment.create!(:name => "My environment", :is_default => true)'
198 162  
199 163 (of course, replace "My environment" with your environment's name!)
200 164  
201   -And now you have to add the domain name you will be using for your noosfero
202   -site to the list of domains of that default environment you just created:
  165 +And now you have to add the domain name you will be using for your noosfero site to the list of domains of that default environment you just created:
203 166  
204   -$ RAILS_ENV=production ./script/runner "Environment.default.domains << Domain.new(:name => 'your.domain.com')"
  167 + $ RAILS_ENV=production ./script/runner "Environment.default.domains << Domain.new(:name => 'your.domain.com')"
205 168  
206 169 (replace "your.domain.com" with your actual domain name)
207 170  
208 171 Add at least one user as admin of environment:
209 172  
210   -$ RAILS_ENV=production ./script/runner "User.create(:login => 'adminuser', :email => 'admin@example.com', :password => 'admin', :password_confirmation => 'admin', :environment => Environment.default, :activated_at => Time.new)"
  173 + $ RAILS_ENV=production ./script/runner "User.create(:login => 'adminuser', :email => 'admin@example.com', :password => 'admin', :password_confirmation => 'admin', :environment => Environment.default, :activated_at => Time.new)"
211 174  
212   -(replace "adminuser", "admin@example.com", "admin" with the login, email
213   -and password of your environment administrator)
  175 +(replace "adminuser", "admin@example.com", "admin" with the login, email and password of your environment administrator)
214 176  
215 177 To start the Noosfero application servers:
216 178  
217   -$ ./script/production start
  179 + $ ./script/production start
218 180  
219   -At this point you have a functional Noosfero installation running, the only
220   -thing left is to configure your webserver as a reverse proxy to pass requests
221   -to them.
  181 +At this point you have a functional Noosfero installation running, the only thing left is to configure your webserver as a reverse proxy to pass requests to them.
222 182  
223 183  
224   -==================
225 184 Apache instalation
226 185 ==================
227 186  
228   -# apt-get install apache2
  187 + # apt-get install apache2
229 188  
230 189 Apache configuration
231 190 --------------------
232 191  
233 192 First you have to enable the following some apache modules:
234 193  
235   - deflate
236   - expires
237   - proxy
238   - proxy_balancer
239   - proxy_http
240   - rewrite
  194 + * deflate
  195 + * expires
  196 + * proxy
  197 + * proxy_balancer
  198 + * proxy_http
  199 + * rewrite
241 200  
242   -On Debian GNU/Linux system, these modules can be enabled with the following
243   -command line, as root:
  201 +On Debian GNU/Linux system, these modules can be enabled with the following command line, as root:
244 202  
245   -# a2enmod deflate expires proxy proxy_balancer proxy_http rewrite
  203 + # a2enmod deflate expires proxy proxy_balancer proxy_http rewrite
246 204  
247 205 In other systems the way by which you enable apache modules may be different.
248 206  
249   -Now with the Apache configuration. You can use the template below, replacing
250   -/var/lib/noosfero/current with the directory in which your noosfero
251   -installation is, your.domain.com with the domain name of your noosfero site.
252   -We are assuming that you are running two thin instances on ports 3000 and
253   -3001. If your setup is different you'll need to adjust <Proxy> section. If you
254   -don't understand something in the configuration, please refer to the apache
255   -documentation.
256   -
257   -Add a file called "mysite" (or whatever name you want to give to your noosfero
258   -site) to /etc/apache2/sites-available with the following content, and customize
259   -as needed (as usual, make sure you replace "your.domain.com" with you actual
260   -domain name, and "/var/lib/noosfero/current" with the directory where Noosfero
261   -is installed):
262   -
263   - <VirtualHost *:80>
264   - ServerName your.domain.com
265   -
266   - DocumentRoot "/var/lib/noosfero/current/public"
267   - <Directory "/var/lib/noosfero/current/public">
268   - Options FollowSymLinks
269   - AllowOverride None
270   - Order Allow,Deny
271   - Allow from all
272   - </Directory>
  207 +Now with the Apache configuration. You can use the template below, replacing `/var/lib/noosfero/current` with the directory in which your noosfero installation is, your.domain.com with the domain name of your noosfero site. We are assuming that you are running two thin instances on ports 3000 and 3001. If your setup is different you'll need to adjust `<Proxy>` section. If you don't understand something in the configuration, please refer to the apache documentation.
  208 +
  209 +Add a file called "mysite" (or whatever name you want to give to your noosfero site) to `/etc/apache2/sites-available` with the following content, and customize as needed (as usual, make sure you replace "your.domain.com" with you actual domain name, and "`/var/lib/noosfero/current`" with the directory where Noosfero is installed):
273 210  
274   - RewriteEngine On
  211 + <VirtualHost *:80>
  212 + ServerName your.domain.com
275 213  
276   - # Rewrite index to check for static index.html
277   - RewriteRule ^/$ /index.html [QSA]
  214 + DocumentRoot "/var/lib/noosfero/current/public"
  215 + <Directory "/var/lib/noosfero/current/public">
  216 + Options FollowSymLinks
  217 + AllowOverride None
  218 + Order Allow,Deny
  219 + Allow from all
  220 + </Directory>
278 221  
279   - # Rewrite to check for Rails cached page
280   - RewriteRule ^([^.]+)$ $1.html [QSA]
  222 + RewriteEngine On
281 223  
282   - RewriteCond %{DOCUMENT_ROOT}/%{REQUEST_FILENAME} !-f
283   - RewriteRule ^.*$ balancer://noosfero%{REQUEST_URI} [P,QSA,L]
  224 + # Rewrite index to check for static index.html
  225 + RewriteRule ^/$ /index.html [QSA]
284 226  
285   - ErrorDocument 503 /503.html
  227 + # Rewrite to check for Rails cached page
  228 + RewriteRule ^([^.]+)$ $1.html [QSA]
286 229  
287   - ErrorLog /var/log/apache2/noosfero.log
288   - LogLevel warn
289   - CustomLog /var/log/apache2/noosfero.access.log combined
  230 + RewriteCond %{DOCUMENT_ROOT}/%{REQUEST_FILENAME} !-f
  231 + RewriteRule ^.*$ balancer://noosfero%{REQUEST_URI} [P,QSA,L]
290 232  
291   - Include /var/lib/noosfero/current/etc/noosfero/apache/cache.conf
  233 + ErrorDocument 503 /503.html
292 234  
293   - </VirtualHost>
  235 + ErrorLog /var/log/apache2/noosfero.log
  236 + LogLevel warn
  237 + CustomLog /var/log/apache2/noosfero.access.log combined
294 238  
295   - <Proxy balancer://noosfero>
296   - BalancerMember http://127.0.0.1:3000
297   - BalancerMember http://127.0.0.1:3001
298   - Order Allow,Deny
299   - Allow from All
300   - </Proxy>
  239 + Include /var/lib/noosfero/current/etc/noosfero/apache/cache.conf
301 240  
302   -The cache.conf file included in the end of the <VirtualHost> section is
303   -important, since it will tell apache to pass expiration and cache headers to
304   -clients so that the site feels faster for users. Do we need to say that using
305   -that configuration is strongly recommended?
  241 + </VirtualHost>
306 242  
307   -Enable that site with (as root, replace "mysite" with the actual name you gave
308   -to your site configuration):
  243 + <Proxy balancer://noosfero>
  244 + BalancerMember http://127.0.0.1:3000
  245 + BalancerMember http://127.0.0.1:3001
  246 + Order Allow,Deny
  247 + Allow from All
  248 + </Proxy>
309 249  
310   -# a2ensite mysite
  250 +The cache.conf file included in the end of the <VirtualHost> section is important, since it will tell apache to pass expiration and cache headers to clients so that the site feels faster for users. Do we need to say that using that configuration is strongly recommended?
  251 +
  252 +Enable that site with (as root, replace "mysite" with the actual name you gave to your site configuration):
  253 +
  254 + # a2ensite mysite
311 255  
312 256 Now restart your apache server (as root):
313 257  
314   -# invoke-rc.d apache2 restart
  258 + # invoke-rc.d apache2 restart
315 259  
316 260  
317 261 Enabling exception notifications
318