correct markdown of some descriptive files

Aurélio A. Heckert
1 parent 70a3c042
Showing 11 changed files with 563 additions and 782 deletions Show diff stats
AUTHORS.md
INSTALL.awstats.md
INSTALL.chat.md
INSTALL.email.md
INSTALL.md
INSTALL.multitenancy.md
INSTALL.varnish.md
README.md
README.rails.md
RELEASING.md
plugins/anti_spam/README.md
-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).
+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).
  
 Developers
 ==========
-= AWStats setup for Noosfero
+AWStats setup for Noosfero
+==========================
  
-AWStats is a free powerful and featureful tool that generates advanced web,
-streaming, ftp or mail server statistics, graphically.
+AWStats is a free powerful and featureful tool that generates advanced web, streaming, ftp or mail server statistics, graphically.
  
-See http://awstats.sourceforge.net/
+See http://awstats.sourceforge.net
  
 This guide supposes that the Noosfero server is running GNU/Linux Debian Squeeze.
  
-1. Install AWStats
+### 1. Install AWStats
  
-# apt-get install awstats libgeo-ip-perl geoip-database
+    # apt-get install awstats libgeo-ip-perl geoip-database
  
-2. Basic setup
+### 2. Basic setup
  
 Create AWStats config file:
+`/etc/awstats/awstats.<domain>.conf`
  
- * /etc/awstats/awstats.<domain>.conf
+    Include "/etc/awstats/awstats.conf"
+    Include "/etc/noosfero/awstats-noosfero.conf"
+    SiteDomain="<domain>"
+    HostAliases="<domain-aliases>"
  
-Include "/etc/awstats/awstats.conf"
-Include "/etc/noosfero/awstats-noosfero.conf"
-SiteDomain="<domain>"
-HostAliases="<domain-aliases>"
+`<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).
  
-<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).
+This setup is considering that the Noosfero server is running varnish (see `INSTALL.varnish`) and [varnishncsa-vhost](http://gitorious.org/varnisnncsa-vhost).
  
-This setup is considering that the Noosfero server is running varnish (see
-INSTALL.varnish) and varnishncsa-vhost [1].
-
-[1] http://gitorious.org/varnisnncsa-vhost
-
-3. Running AWStats for the first time
+### 3. Running AWStats for the first time
  
 Run awstats by hand via command line:
  
-# /usr/lib/cgi-bin/awstats.pl -config=<domain>
+    # /usr/lib/cgi-bin/awstats.pl -config=<domain>
  
 You should see something as below as output of this command:
  
-# /usr/lib/cgi-bin/awstats.pl -config=softwarelivre.org
-Create/Update database for config "/etc/awstats/awstats.softwarelivre.org.conf" by AWStats version 6.7 (build 1.892)
-From data in log file "/var/log/varnish/varnishncsa-vhost.log"...
-Phase 1 : First bypass old records, searching new record...
-Searching new records from beginning of log file...
-Phase 2 : Now process new records (Flush history on disk after 20000 hosts)...
-Jumped lines in file: 0
-Parsed lines in file: 452
- Found 0 dropped records,
- Found 0 corrupted records,
- Found 0 old records,
- Found 452 new qualified records.
+    # /usr/lib/cgi-bin/awstats.pl -config=softwarelivre.org
+    Create/Update database for config "/etc/awstats/awstats.softwarelivre.org.conf" by AWStats version 6.7 (build 1.892)
+    From data in log file "/var/log/varnish/varnishncsa-vhost.log"...
+    Phase 1 : First bypass old records, searching new record...
+    Searching new records from beginning of log file...
+    Phase 2 : Now process new records (Flush history on disk after 20000 hosts)...
+    Jumped lines in file: 0
+    Parsed lines in file: 452
+     Found 0 dropped records,
+     Found 0 corrupted records,
+     Found 0 old records,
+     Found 452 new qualified records.
  
-4. Setup frontend
+### 4. Setup frontend
  
-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.
+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.
  
-# cp /usr/share/doc/awstats/examples/apache.conf /etc/apache2/conf.d/awstats.conf
-# invoke-rc.d apache2 restart
+    # cp /usr/share/doc/awstats/examples/apache.conf /etc/apache2/conf.d/awstats.conf
+    # invoke-rc.d apache2 restart
  
-ps.: Don't forget to change the port /etc/apache/sites-enabled/000-default to
-8080.
+ps.: Don't forget to change the port `/etc/apache/sites-enabled/000-default` to `8080`.
  
-Try: http://tools.<domain>/cgi-bin/awstats.pl?config=<domain>
-(eg.: http://tools.softwarelivre.org/cgi-bin/awstats.pl?config=softwarelivre.org).
+Try: `http://tools.<domain>/cgi-bin/awstats.pl?config=<domain>`
+(eg.: `http://tools.softwarelivre.org/cgi-bin/awstats.pl?config=softwarelivre.org`).
  
-5. Schedule AWStats in crontab
+### 5. Schedule AWStats in crontab
  
- * /etc/cron.d/awstats
+`/etc/cron.d/awstats`
  
-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
+    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
  
 Done, check the AWStats frontend after one or two days to see if everything is working properly.
-== XMPP/Chat Client Setup
+XMPP/Chat Client Setup
+======================
  
 To configure XMPP/BOSH in Noosfero you need:
  
@@ -8,96 +9,87 @@ To configure XMPP/BOSH in Noosfero you need:
  
 If you use Debian 6.0 (squeeze):
  
-# apt-get install librestclient-ruby pidgin-data ruby1.8-dev
-# gem install SystemTimer
+    # apt-get install librestclient-ruby pidgin-data ruby1.8-dev
+    # gem install SystemTimer
  
-The samples of config file to configure a XMPP/BOSH server with
-ejabberd, postgresql and apache2 can be found at util/chat directory.
+The samples of config file to configure a XMPP/BOSH server with ejabberd, postgresql and apache2 can be found at util/chat directory.
  
-== XMPP/Chat Server Setup
+XMPP/Chat Server Setup
+======================
  
 This is a step-by-step guide to get a XMPP service working, in a Debian system.
  
-1. Install the required packages
+## 1. Install the required packages
  
-# apt-get install ejabberd odbc-postgresql
+    # apt-get install ejabberd odbc-postgresql
  
-2. Ejabberd configuration
+## 2. Ejabberd configuration
  
-All the following changes must be done in config file:
+All the following changes must be done in config file: `/etc/ejabberd/ejabberd.cfg`
  
- /etc/ejabberd/ejabberd.cfg
+### 2.1. Set the default admin user
  
- 2.1. Set the default admin user
+    { acl, admin, { user, "john", "www.example.com" } }.
+    { acl, admin, { user, "bart", "www.example.com" } }.
  
-{ acl, admin, { user, "john", "www.example.com" } }.
-{ acl, admin, { user, "bart", "www.example.com" } }.
+### 2.2. Set the default host
  
- 2.2. Set the default host
+    { hosts, [ "www.example.com" ] }.
  
-{ hosts, [ "www.example.com" ] }.
+### 2.3. Http-Bind activation
  
- 2.3. Http-Bind activation
+    { 5280, ejabberd_http, [
+          http_bind,
+          web_admin
+       ]
+    }
  
-{ 5280, ejabberd_http, [
-      http_bind,
-      web_admin
-   ]
-}
+    (...)
  
-(...)
+    { modules, [
+       {mod_http_bind, []},
+       ...
+    ] }.
  
-{ modules, [
-   {mod_http_bind, []},
-   ...
-] }.
+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.
  
-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.
+In non-anonymous rooms the jabber service sends the new occupant's full JID to all occupants in the room [[1]].
  
-In non-anonymous rooms the jabber service sends the new occupant's full JID to
-all occupants in the room[1].
+Add option "`{default_room_options, [{anonymous, false}]}`" to `/etc/ejabberd/ejabberd.cfg` in mod_muc session. See below:
  
-Add option "{default_room_options, [{anonymous, false}]}" to
-/etc/ejabberd/ejabberd.cfg in mod_muc session. See below:
+    { mod_muc, [
+       %%{host, "conference.@HOST@"},
+       {access, muc},
+       {access_create, muc},
+       {access_persistent, muc},
+       {access_admin, muc_admin},
+       {max_users, 500},
+       {default_room_options, [{anonymous, false}]}
+    ]},
  
-{ mod_muc, [
-   %%{host, "conference.@HOST@"},
-   {access, muc},
-   {access_create, muc},
-   {access_persistent, muc},
-   {access_admin, muc_admin},
-   {max_users, 500},
-   {default_room_options, [{anonymous, false}]}
-]},
+[1]: http://xmpp.org/extensions/xep-0045.html#enter-nonanon
  
-[1] - http://xmpp.org/extensions/xep-0045.html#enter-nonanon
  
-
- 2.4. Authentication method
+### 2.4. Authentication method
  
 To use Postgresql through ODBC, the following modifications must be done:
  
  * Disable the default method:
-
-{auth_method, internal}.
+   `{auth_method, internal}.`
  
  * Enable autheticantion through ODBC:
-
-{auth_method, odbc}.
+   `{auth_method, odbc}.`
  
  * Set database server name
+   `{odbc_server, "DSN=PostgreSQLEjabberdNoosfero"}.`
  
-{odbc_server, "DSN=PostgreSQLEjabberdNoosfero"}.
  
+### 2.5. Increase the shaper traffic limit
  
- 2.5. Increase the shaper traffic limit
+    { shaper, normal, { maxrate, 10000000 } }.
  
-{ shaper, normal, { maxrate, 10000000 } }.
  
-
- 2.6. Disable unused modules
+### 2.6. Disable unused modules
  
 Unused modules can be disabled, for example:
  
@@ -110,149 +102,135 @@ Unused modules can be disabled, for example:
  * mod_register
  
  
- 2.7. Enable ODBC modules
+### 2.7. Enable ODBC modules
  
  * mod_privacy -> mod_privacy_odbc
  * mod_private -> mod_private_odbc
  * mod_roster  -> mod_roster_odbc
  
-3. Configuring Postgresql
+## 3. Configuring Postgresql
  
 Login as noosfero user, and execute:
  
-   $ psql noosfero < /path/to/noosfero/util/chat/postgresql/ejabberd.sql
-
-Where 'noosfero' may need to be replace by the name of the database used for
-Noosfero.
+    $ psql noosfero < /path/to/noosfero/util/chat/postgresql/ejabberd.sql
  
-This will create a new schema inside the noosfero database, called 'ejabberd'.
+Where `noosfero` may need to be replace by the name of the database used for Noosfero.
  
-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.
+This will create a new schema inside the noosfero database, called `ejabberd`.
  
+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.
  
-4. ODBC configuration
+## 4. ODBC configuration
  
 The following files must be created:
  
- * /etc/odbc.ini
+`/etc/odbc.ini`:
  
-[PostgreSQLEjabberdNoosfero]
-Description      = PostgreSQL Noosfero ejabberd database
-Driver           = PostgreSQL Unicode
-Trace            = No
-TraceFile        = /tmp/psqlodbc.log
-Database         = noosfero
-Servername       = localhost
-UserName         = <DBUSER>
-Password         = <DBPASS>
-Port             =
-ReadOnly         = No
-RowVersioning    = No
-ShowSystemTables = No
-ShowOidColumn    = No
-FakeOidIndex     = No
-ConnSettings     = SET search_path TO ejabberd
+    [PostgreSQLEjabberdNoosfero]
+    Description      = PostgreSQL Noosfero ejabberd database
+    Driver           = PostgreSQL Unicode
+    Trace            = No
+    TraceFile        = /tmp/psqlodbc.log
+    Database         = noosfero
+    Servername       = localhost
+    UserName         = <DBUSER>
+    Password         = <DBPASS>
+    Port             =
+    ReadOnly         = No
+    RowVersioning    = No
+    ShowSystemTables = No
+    ShowOidColumn    = No
+    FakeOidIndex     = No
+    ConnSettings     = SET search_path TO ejabberd
  
- * /etc/odbcinst.ini
+`/etc/odbcinst.ini`:
  
-[PostgreSQL Unicode]
-Description = PostgreSQL ODBC driver (Unicode version)
-Driver      = /usr/lib/odbc/psqlodbcw.so
-Setup       = /usr/lib/odbc/libodbcpsqlS.so
-Debug       = 0
-CommLog     = 1
-UsageCount  = 3
+    [PostgreSQL Unicode]
+    Description = PostgreSQL ODBC driver (Unicode version)
+    Driver      = /usr/lib/odbc/psqlodbcw.so
+    Setup       = /usr/lib/odbc/libodbcpsqlS.so
+    Debug       = 0
+    CommLog     = 1
+    UsageCount  = 3
  
- 4.1 testing all:
+## 4.1 testing all:
  
-# isql 'PostgreSQLEjabberdNoosfero'
+    # isql 'PostgreSQLEjabberdNoosfero'
  
-If the configuration was done right, the message "Connected!"
-will be displayed.
+If the configuration was done right, the message "Connected!" will be displayed.
  
  
-5. Enabling kernel polling and SMP in /etc/default/ejabberd
+## 5. Enabling kernel polling and SMP in `/etc/default/ejabberd`
  
-POLL=true
-SMP=auto
+    POLL=true
+    SMP=auto
  
+## 6. Increase the file descriptors limit for user ejabberd
  
-6. Increase the file descriptors limit for user ejabberd
+### 6.1. Uncomment this line in file `/etc/pam.d/su`:
  
- 6.1. Uncomment this line in file /etc/pam.d/su:
+    session required pam_limits.so
  
-session required pam_limits.so
+### 6.2. Add this lines to file `/etc/security/limits.conf`:
  
-
- 6.2. Add this lines to file /etc/security/limits.conf:
-
-ejabberd       hard    nofile  65536
-ejabberd       soft    nofile  65536
+    ejabberd       hard    nofile  65536
+    ejabberd       soft    nofile  65536
  
 Now, test the configuration:
  
-# cat /proc/<EJABBERD_BEAM_PROCESS_PID>/limits
-
+    # cat /proc/<EJABBERD_BEAM_PROCESS_PID>/limits
  
-7. Apache Configuration
+## 7. Apache Configuration
  
 Apache server must be configurated as follow:
  
- * /etc/apache2/sites-enabled/noosfero
+`/etc/apache2/sites-enabled/noosfero`:
  
-RewriteEngine On
-Include /usr/share/noosfero/util/chat/apache/xmpp.conf
+    RewriteEngine On
+    Include /usr/share/noosfero/util/chat/apache/xmpp.conf
  
- * /etc/apache2/apache2.conf:
+`/etc/apache2/apache2.conf`:
  
-<IfModule mpm_worker_module>
-   StartServers          8
-   MinSpareThreads       25
-   MaxSpareThreads       75
-   ThreadLimit           128
-   ThreadsPerChild       128
-   MaxClients            2048
-   MaxRequestsPerChild   0
-</IfModule>
+    <IfModule mpm_worker_module>
+       StartServers          8
+       MinSpareThreads       25
+       MaxSpareThreads       75
+       ThreadLimit           128
+       ThreadsPerChild       128
+       MaxClients            2048
+       MaxRequestsPerChild   0
+    </IfModule>
  
 Note: module proxy_http must be enabled:
  
-# a2enmod proxy_http
+    # a2enmod proxy_http
  
-8. DNS configuration
+## 8. DNS configuration
  
-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:
+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:
  
-_xmpp-client._tcp   SRV   5 100 5222 master
-conference   CNAME master
-_xmpp-client._tcp.conference   SRV   5 100 5222 master
+    _xmpp-client._tcp   SRV   5 100 5222 master
+    conference   CNAME master
+    _xmpp-client._tcp.conference   SRV   5 100 5222 master
  
-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.
+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.
  
-9. Testing this Setup
+## 9. Testing this Setup
  
 Adjust shell limits to proceed with some benchmarks and load tests: 
  
-# ulimit −s 256
-# ulimit −n 8192
-# echo 10 > /proc/sys/net/ipv4/tcp_syn_retries
+    # ulimit −s 256
+    # ulimit −n 8192
+    # echo 10 > /proc/sys/net/ipv4/tcp_syn_retries
  
 To measure the bandwidth between server and client:
  
  * at server side:
-
-# iperf −s
+   `# iperf −s`
  
  * at client side:
-
-# iperf −c server_ip
+   `# iperf −c server_ip`
  
 For heavy load tests, clone and use this software:
  
-git clone http://git.holoscopio.com/git/metal/tester.git
+    $ git clone http://git.holoscopio.com/git/metal/tester.git
-= Noosfero email setup
+Noosfero email setup
+====================
  
-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.
+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.
  
-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.
+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.
  
 To install Postfix:
  
-# apt-get install postfix
+    # apt-get install postfix
  
-During the installation process, you will be asked a few questions. Your answer
-to them will vary in 2 cases:
+During the installation process, you will be asked a few questions. Your answer to them will vary in 2 cases:
  
-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:
+**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:
  
-  General type of mail configuration: Internet site
-  System mail name: the name of your domain, e.g. "mysocialnetwork.com"
+ * General type of mail configuration: Internet site
+ * System mail name: the name of your domain, e.g. "mysocialnetwork.com"
  
-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:
+**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:
  
-  General type of mail configuration: Internet with smarthost
-  System mail name: the name of your domain, e.g. "mysocialnetwork.com"
-  SMTP relay host: smtp.yourprovider.com
+ * General type of mail configuration: Internet with smarthost
+ * System mail name: the name of your domain, e.g. "mysocialnetwork.com"
+ * SMTP relay host: smtp.yourprovider.com
  
-Note that smtp.yourprovider.com must allow your server to deliver e-mails
-through it. You should probably ask your servive provider about this.
+Note that smtp.yourprovider.com must allow your server to deliver e-mails through it. You should probably ask your servive provider about this.
  
-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
+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
  
-= Noosfero installation instructions from source for production environments
+Noosfero installation instructions from source for production environments
+==========================================================================
  
-The instructions below can be used for setting up a Noosfero production
-environment from the Noosfero sources.
+The instructions below can be used for setting up a Noosfero production environment from the Noosfero sources.
  
-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.
+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.
  
-If you want to setup a development environment instead of a production one,
-stop reading this file right now and read the file HACKING instead.
+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.
  
-For a complete installation guide, please see the following web page:
-http://noosfero.org/Development/HowToInstall
+For a complete installation guide, please see the following web page: http://noosfero.org/Development/HowToInstall
  
-If you have problems with the setup, please feel free to ask questions in the
-development mailing list.
+If you have problems with the setup, please feel free to ask questions in the development mailing list.
  
-== Requirements
+Requirements
+------------
  
-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.
+**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.
  
-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.
+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.
  
-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:
+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:
  
- # 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
+    # apt-get install ruby rake po4a libgettext-ruby-util libgettext-ruby1.8 \
+      libsqlite3-ruby rcov librmagick-ruby libredcloth-ruby libhpricot-ruby \
+      libwill-paginate-ruby iso-codes libfeedparser-ruby libdaemons-ruby thin \
+      tango-icon-theme
  
-On other systems, they may or may not be available through your regular package
-management system. Below are the links to their homepages.
+On other systems, they may or may not be available through your regular package management system. Below are the links to their homepages.
  
-* Ruby: http://www.ruby-lang.org/
-* Rake: http://rake.rubyforge.org/
-* po4a: http://po4a.alioth.debian.org/
+* Ruby: http://www.ruby-lang.org
+* Rake: http://rake.rubyforge.org
+* po4a: http://po4a.alioth.debian.org
 * Ruby-sqlite3: http://rubyforge.org/projects/sqlite-ruby
 * rcov: http://eigenclass.org/hiki/rcov
-* RMagick: http://rmagick.rubyforge.org/
-* RedCloth: http://redcloth.org/
+* RMagick: http://rmagick.rubyforge.org
+* RedCloth: http://redcloth.org
 * will_paginate: http://github.com/mislav/will_paginate/wikis
-* iso-codes: http://pkg-isocodes.alioth.debian.org/
+* iso-codes: http://pkg-isocodes.alioth.debian.org
 * feedparser: http://packages.debian.org/sid/libfeedparser-ruby
-* Daemons - http://daemons.rubyforge.org/
-* Thin: http://code.macournoyer.com/thin/
+* Daemons - http://daemons.rubyforge.org
+* Thin: http://code.macournoyer.com/thin
 * tango-icon-theme: http://tango.freedesktop.org/Tango_Icon_Library
-* Hpricot: http://hpricot.com/
+* Hpricot: http://hpricot.com
  
 If you manage to install Noosfero successfully on other systems than Debian,
 please feel free to contact the Noosfero development mailing with the
@@ -62,30 +51,21 @@ As root user
  
 Install memcached. On Debian:
  
-# apt-get install memcached
+    # apt-get install memcached
  
-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.
+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.
  
-It is recommended that you run noosfero with its own user account. To create
-such an account, please do the following:
+It is recommended that you run noosfero with its own user account. To create such an account, please do the following:
  
-# adduser --system --group noosfero --shell /bin/sh --home /var/lib/noosfero
+    # adduser --system --group noosfero --shell /bin/sh --home /var/lib/noosfero
  
-(note that you can change the $HOME directory of the user if you wish, here we
-are using /var/lib/noosfero)
+(note that you can change the `$HOME` directory of the user if you wish, here we are using `/var/lib/noosfero`)
  
-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:
+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:
  
-# sudo -u noosfero -i
-
-or
-
-# su - noosfero
+    # sudo -u noosfero -i
+    or
+    # su - noosfero
  
 As noosfero user
 ================
@@ -93,325 +73,262 @@ As noosfero user
 downloading from git
 --------------------
  
-Here we are cloning the noosfero repository from git. Note: you will need to
-install git before.
+Here we are cloning the noosfero repository from git. Note: you will need to install git before.
  
-$ git clone git://gitorious.org/noosfero/noosfero.git current
-$ cd current
-$ git checkout -b stable origin/stable
+    $ git clone git://gitorious.org/noosfero/noosfero.git current
+    $ cd current
+    $ git checkout -b stable origin/stable
  
 downloading tarball
 -------------------
  
 Note: replace 0.39.0 below from the latest stable version.
  
-$ wget http://noosfero.org/pub/Development/NoosferoVersion00x39x00/noosfero-0.39.0.tar.gz
-$ tar -zxvf noosfero-0.39.0.tar.gz
-$ ln -s noosfero-0.39.0 current
-$ cd current
+    $ wget http://noosfero.org/pub/Development/NoosferoVersion00x39x00/noosfero-0.39.0.tar.gz
+    $ tar -zxvf noosfero-0.39.0.tar.gz
+    $ ln -s noosfero-0.39.0 current
+    $ cd current
  
 Create the thin configuration file:
  
-$ thin -C config/thin.yml -e production config
+    $ thin -C config/thin.yml -e production config
  
-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.
+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.
  
-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:
+*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:
  
-$ cd /var/lib/noosfero/current/vendor
-$ wget http://ftp.de.debian.org/debian/pool/main/r/rails/rails_2.3.5.orig.tar.gz
-$ tar xzf rails_2.3.5.orig.tar.gz
-$ ln -s rails-2.3.5 rails
+    $ cd /var/lib/noosfero/current/vendor
+    $ wget http://ftp.de.debian.org/debian/pool/main/r/rails/rails_2.3.5.orig.tar.gz
+    $ tar xzf rails_2.3.5.orig.tar.gz
+    $ ln -s rails-2.3.5 rails
  
 As root user
 ============
  
 Setup Noosfero log and tmp directories:
  
-# cd /var/lib/noosfero/current
-# ./etc/init.d/noosfero setup
+    # cd /var/lib/noosfero/current
+    # ./etc/init.d/noosfero setup
  
-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.
+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.
  
-# apt-get install postgresql libpgsql-ruby
-# su postgres -c 'createuser noosfero -S -d -R'
+    # apt-get install postgresql libpgsql-ruby
+    # su postgres -c 'createuser noosfero -S -d -R'
  
-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.
+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.
  
 Restart postgresql:
+    # invoke-rc.d postgresql restart
  
-# invoke-rc.d postgresql restart
-
-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.
+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.
  
 As noosfero user
 ================
  
 Now create the databases:
  
-$ cd /var/lib/noosfero/current
-$ createdb noosfero_production
-$ createdb noosfero_development
-$ createdb noosfero_test
+    $ cd /var/lib/noosfero/current
+    $ createdb noosfero_production
+    $ createdb noosfero_development
+    $ createdb noosfero_test
  
-The development and test databases are actually optional. If you are creating a
-stricly production server, you will probably not need them.
+The development and test databases are actually optional. If you are creating a stricly production server, you will probably not need them.
  
-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:
+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:
  
-  production:
-    adapter: postgresql
-    encoding: unicode
-    database: noosfero_production
-    username: noosfero
+    production:
+      adapter: postgresql
+      encoding: unicode
+      database: noosfero_production
+      username: noosfero
  
 Now, to test the database access, you can fire the Rails database console:
  
-$ ./script/dbconsole production
+    $ ./script/dbconsole production
  
-If it connects to your database, then everything is fine. If you got an error
-message, then you have to check your database configuration.
+If it connects to your database, then everything is fine. If you got an error message, then you have to check your database configuration.
  
 Create the database structure:
  
-$ RAILS_ENV=production rake db:schema:load
+    $ RAILS_ENV=production rake db:schema:load
  
 Compile the translations:
  
-$ RAILS_ENV=production rake noosfero:translations:compile
+    $ RAILS_ENV=production rake noosfero:translations:compile
  
-Now we must create some initial data. To create your default environment
-(the first one), run the command below:
+Now we must create some initial data. To create your default environment (the first one), run the command below:
  
-$ RAILS_ENV=production ./script/runner 'Environment.create!(:name => "My environment", :is_default => true)'
+    $ RAILS_ENV=production ./script/runner 'Environment.create!(:name => "My environment", :is_default => true)'
  
 (of course, replace "My environment" with your environment's name!)
  
-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:
+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:
  
-$ RAILS_ENV=production ./script/runner "Environment.default.domains << Domain.new(:name => 'your.domain.com')"
+    $ RAILS_ENV=production ./script/runner "Environment.default.domains << Domain.new(:name => 'your.domain.com')"
  
 (replace "your.domain.com" with your actual domain name)
  
 Add at least one user as admin of environment:
  
-$ 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)"
+    $ 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)"
  
-(replace "adminuser", "admin@example.com", "admin" with the login, email
-and password of your environment administrator)
+(replace "adminuser", "admin@example.com", "admin" with the login, email and password of your environment administrator)
  
 To start the Noosfero application servers:
  
-$ ./script/production start
+    $ ./script/production start
  
-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.
+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.
  
  
-==================
 Apache instalation
 ==================
  
-# apt-get install apache2
+    # apt-get install apache2
  
 Apache configuration
 --------------------
  
 First you have to enable the following some apache modules:
  
-  deflate
-  expires
-  proxy
-  proxy_balancer
-  proxy_http
-  rewrite
+ * deflate
+ * expires
+ * proxy
+ * proxy_balancer
+ * proxy_http
+ * rewrite
  
-On Debian GNU/Linux system, these modules can be enabled with the following
-command line, as root:
+On Debian GNU/Linux system, these modules can be enabled with the following command line, as root:
  
-# a2enmod deflate expires proxy proxy_balancer proxy_http rewrite
+    # a2enmod deflate expires proxy proxy_balancer proxy_http rewrite
  
 In other systems the way by which you enable apache modules may be different.
  
-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.
-
-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):
-
-  <VirtualHost *:80>
-    ServerName your.domain.com
-
-    DocumentRoot "/var/lib/noosfero/current/public"
-    <Directory "/var/lib/noosfero/current/public">
-      Options FollowSymLinks
-      AllowOverride None
-      Order Allow,Deny
-      Allow from all
-    </Directory>
+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.
+
+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):
  
-    RewriteEngine On
+    <VirtualHost *:80>
+      ServerName your.domain.com
  
-    # Rewrite index to check for static index.html
-    RewriteRule ^/$ /index.html [QSA]
+      DocumentRoot "/var/lib/noosfero/current/public"
+      <Directory "/var/lib/noosfero/current/public">
+        Options FollowSymLinks
+        AllowOverride None
+        Order Allow,Deny
+        Allow from all
+      </Directory>
  
-    # Rewrite to check for Rails cached page
-    RewriteRule ^([^.]+)$ $1.html [QSA]
+      RewriteEngine On
  
-    RewriteCond %{DOCUMENT_ROOT}/%{REQUEST_FILENAME} !-f
-    RewriteRule ^.*$ balancer://noosfero%{REQUEST_URI} [P,QSA,L]
+      # Rewrite index to check for static index.html
+      RewriteRule ^/$ /index.html [QSA]
  
-    ErrorDocument 503 /503.html
+      # Rewrite to check for Rails cached page
+      RewriteRule ^([^.]+)$ $1.html [QSA]
  
-    ErrorLog /var/log/apache2/noosfero.log
-    LogLevel warn
-    CustomLog /var/log/apache2/noosfero.access.log combined
+      RewriteCond %{DOCUMENT_ROOT}/%{REQUEST_FILENAME} !-f
+      RewriteRule ^.*$ balancer://noosfero%{REQUEST_URI} [P,QSA,L]
  
-    Include /var/lib/noosfero/current/etc/noosfero/apache/cache.conf
+      ErrorDocument 503 /503.html
  
-  </VirtualHost>
+      ErrorLog /var/log/apache2/noosfero.log
+      LogLevel warn
+      CustomLog /var/log/apache2/noosfero.access.log combined
  
-  <Proxy balancer://noosfero>
-    BalancerMember http://127.0.0.1:3000
-    BalancerMember http://127.0.0.1:3001
-    Order Allow,Deny
-    Allow from All
-  </Proxy>
+      Include /var/lib/noosfero/current/etc/noosfero/apache/cache.conf
  
-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?
+    </VirtualHost>
  
-Enable that site with (as root, replace "mysite" with the actual name you gave
-to your site configuration):
+    <Proxy balancer://noosfero>
+      BalancerMember http://127.0.0.1:3000
+      BalancerMember http://127.0.0.1:3001
+      Order Allow,Deny
+      Allow from All
+    </Proxy>
  
-# a2ensite mysite
+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?
+
+Enable that site with (as root, replace "mysite" with the actual name you gave to your site configuration):
+
+    # a2ensite mysite
  
 Now restart your apache server (as root):
  
-# invoke-rc.d apache2 restart
+    # invoke-rc.d apache2 restart
  
  
 Enabling exception notifications
 ================================
  
-This is an optional step. You will need it only if you want to receive e-mail
-notifications when some exception occurs on Noosfero.
+This is an optional step. You will need it only if you want to receive e-mail notifications when some exception occurs on Noosfero.
  
-First, install this version of the gem.
-Others versions may not be compatible with Noosfero:
+First, install this version of the gem. Others versions may not be compatible with Noosfero:
  
-# gem install exception_notification -v 1.0.20090728
+    # gem install exception_notification -v 1.0.20090728
  
-You can configure the e-mails that will receive the notifications.
-Change the file config/noosfero.yml as the following example, replacing the
-e-mails by real ones:
+You can configure the e-mails that will receive the notifications. Change the file config/noosfero.yml as the following example, replacing the e-mails by real ones:
  
-  production:
-    exception_recipients: [admin@example.com, you@example.com]
+    production:
+      exception_recipients: [admin@example.com, you@example.com]
  
  
-============
 Maintainance
 ============
  
-To ease the maintainance, install a symbolic link for the Noosfero startup
-script in your server and add it to the system initialization and shutdown
-sequences (as root):
-
-# ln -s /var/lib/noosfero/current/etc/init.d/noosfero /etc/init.d/noosfero
-# update-rc.d noosfero defaults
- Adding system startup for /etc/init.d/noosfero ...
-   /etc/rc0.d/K20noosfero -> ../init.d/noosfero
-   /etc/rc1.d/K20noosfero -> ../init.d/noosfero
-   /etc/rc6.d/K20noosfero -> ../init.d/noosfero
-   /etc/rc2.d/S20noosfero -> ../init.d/noosfero
-   /etc/rc3.d/S20noosfero -> ../init.d/noosfero
-   /etc/rc4.d/S20noosfero -> ../init.d/noosfero
-   /etc/rc5.d/S20noosfero -> ../init.d/noosfero
+To ease the maintainance, install a symbolic link for the Noosfero startup script in your server and add it to the system initialization and shutdown sequences (as root):
+
+    # ln -s /var/lib/noosfero/current/etc/init.d/noosfero /etc/init.d/noosfero
+    # update-rc.d noosfero defaults
+     Adding system startup for /etc/init.d/noosfero ...
+       /etc/rc0.d/K20noosfero -> ../init.d/noosfero
+       /etc/rc1.d/K20noosfero -> ../init.d/noosfero
+       /etc/rc6.d/K20noosfero -> ../init.d/noosfero
+       /etc/rc2.d/S20noosfero -> ../init.d/noosfero
+       /etc/rc3.d/S20noosfero -> ../init.d/noosfero
+       /etc/rc4.d/S20noosfero -> ../init.d/noosfero
+       /etc/rc5.d/S20noosfero -> ../init.d/noosfero
  
 Now to start Noosfero, you do as root:
  
-# invoke-rc.d noosfero start
+    # invoke-rc.d noosfero start
  
 To stop Noosfero:
  
-# invoke-rc.d noosfero start
+    # invoke-rc.d noosfero start
  
 To restart Noosfero:
  
-# invoke-rc.d noosfero restart
+    # invoke-rc.d noosfero restart
  
-Noosfero will be automatically started during system boot, and automatically
-stopped if the system shuts down for some reason (or during the shutdown part
-of a reboot).
+Noosfero will be automatically started during system boot, and automatically stopped if the system shuts down for some reason (or during the shutdown part of a reboot).
  
-=============
 Rotating logs
 =============
  
-Noosfero provides an example logrotate configuation to rotate its logs. To use
-it, create a symbolic link in /etc/logrotate.d/:
+Noosfero provides an example logrotate configuation to rotate its logs. To use it, create a symbolic link in `/etc/logrotate.d/`:
  
-# cd /etc/logrotate.d/
-# ln -s /var/lib/noosfero/current/etc/logrotate.d/noosfero
+    # cd /etc/logrotate.d/
+    # ln -s /var/lib/noosfero/current/etc/logrotate.d/noosfero
  
-Note that the provided file assumes Noosfero logging is being done in
-/var/log/noosfero (which is the case if you followed the instructions above
-correctly). If the logs are stored elsewhere, it's recommended that you copy
-the file over to /etc/logrotate.d/ and modify it to point to your local log
-directly.
+Note that the provided file assumes Noosfero logging is being done in `/var/log/noosfero` (which is the case if you followed the instructions above correctly). If the logs are stored elsewhere, it's recommended that you copy the file over to `/etc/logrotate.d/` and modify it to point to your local log directly.
  
-=========
 Upgrading
 =========
  
-If you followed the steps in this document and installed Noosfero from the git
-repository, then upgrading is easy. First, you need to allow the noosfero user
-to restart the memcached server with sudo, by adding the following line in
-/etc/sudoers:
+If you followed the steps in this document and installed Noosfero from the git repository, then upgrading is easy. First, you need to allow the noosfero user to restart the memcached server with sudo, by adding the following line in `/etc/sudoers`:
  
-noosfero ALL=NOPASSWD: /etc/init.d/memcached
+    noosfero ALL=NOPASSWD: /etc/init.d/memcached
  
 Then, to perform an upgrade, do the following as the noosfero user:
  
-$ cd /var/lib/noosfero/current
-$ ./script/git-upgrade
+    $ cd /var/lib/noosfero/current
+    $ ./script/git-upgrade
  
-The git-upgrade script will take care of everything for you. It will first stop
-the service, then fetch the current source code, upgrade database, compile
-translations, and then start the service again.
+The `git-upgrade` script will take care of everything for you. It will first stop the service, then fetch the current source code, upgrade database, compile translations, and then start the service again.
  
-Note 1: make sure your local git repository is following the "stable" branch,
-just like the instructions above. The "master" branch is not recommended for
-use in production environments.
+*Note 1*: make sure your local git repository is following the "stable" branch, just like the instructions above. The `master` branch is **not** recommended for use in production environments.
  
-Note 2: always read the release notes before upgrading. Sometimes there will be
-steps that must be performed manually. If that is the case, you can invoke the
-git-upgrade script with the special parameter "--shell" that will give you a
-shell after the upgrade, which you can use to perform any manual steps
-required:
+*Note 2*: always read the release notes before upgrading. Sometimes there will be steps that must be performed manually. If that is the case, you can invoke the `git-upgrade` script with the special parameter `--shell` that will give you a shell after the upgrade, which you can use to perform any manual steps required:
  
-$ ./script/git-upgrade --shell
+    $ ./script/git-upgrade --shell
-== Multitenancy support
+Multitenancy support
+====================
  
-Multitenancy refers to a principle in software architecture where a
-single instance of the software runs on a server, serving multiple
-client organizations (tenants). Multitenancy is contrasted with a
-multi-instance architecture where separate software instances (or
-hardware systems) are set up for different client organizations. With
-a multitenant architecture, a software application is designed to
-virtually partition its data and configuration, and each client
-organization works with a customized virtual application instance.
+Multitenancy refers to a principle in software architecture where a single instance of the software runs on a server, serving multiple client organizations (tenants). Multitenancy is contrasted with a multi-instance architecture where separate software instances (or hardware systems) are set up for different client organizations. With a multitenant architecture, a software application is designed to virtually partition its data and configuration, and each client organization works with a customized virtual application instance.
  
 Today this feature is available only for PostgreSQL databases.
  
-This document assumes that you have a new fully PostgresSQL default Noosfero
-installation as explained at the INSTALL file.
+This document assumes that you have a new fully PostgresSQL default Noosfero installation as explained at the `INSTALL.md` file.
  
-== Separated data
+Separated data
+--------------
  
 The items below are separated for each hosted environment:
  
@@ -25,139 +19,115 @@ The items below are separated for each hosted environment:
 * Feed updater
 * Delayed Job Workers
  
-== Database configuration file
+Database configuration file
+---------------------------
  
-The file config/database.yml must follow a structure in order to
-achieve multitenancy support. In this example, we will set 3
-different environments: env1, env2 and env3.
+The file config/database.yml must follow a structure in order to achieve multitenancy support. In this example, we will set 3 different environments: env1, env2 and env3.
  
 Each "hosted" environment must have an entry like this:
  
-env1_production:
-  adapter: postgresql
-  encoding: unicode
-  database: noosfero
-  schema_search_path: public
-  username: noosfero
-  domains:
-    - env1.com
-    - env1.org
-
-env2_production:
-  adapter: postgresql
-  encoding: unicode
-  database: noosfero
-  schema_search_path: env2
-  username: noosfero
-  domains:
-    - env2.com
-    - env2.org
-
-env3_production:
-  adapter: postgresql
-  encoding: unicode
-  database: noosfero
-  schema_search_path: env3
-  username: noosfero
-  domains:
-    - env3.com
-    - env3.net
-
-The "hosted" environments define, besides the schema_search_path, a
-list of domains that, when accessed, tells which database the
-application should use. Also, the environment name must end with
-'_hosting', where 'hosting' is the name of the hosting environment.
+    env1_production:
+      adapter: postgresql
+      encoding: unicode
+      database: noosfero
+      schema_search_path: public
+      username: noosfero
+      domains:
+        - env1.com
+        - env1.org
+
+    env2_production:
+      adapter: postgresql
+      encoding: unicode
+      database: noosfero
+      schema_search_path: env2
+      username: noosfero
+      domains:
+        - env2.com
+        - env2.org
+
+    env3_production:
+      adapter: postgresql
+      encoding: unicode
+      database: noosfero
+      schema_search_path: env3
+      username: noosfero
+      domains:
+        - env3.com
+        - env3.net
+
+The "hosted" environments define, besides the `schema_search_path`, a list of domains that, when accessed, tells which database the application should use. Also, the environment name must end with "`_<hosting>`", where `<hosting>` is the name of the hosting environment.
  
 You must also tell the application which is the default environment.
  
-production:
-  env1_production
+    production:
+      env1_production
  
-On the example above there are only three hosted environments, but it
-can be more than three. The schemas 'env2' and 'env3' must already
-exist in the same database of the hosting environment. As postgres
-user, you can create them typing:
+On the example above there are only three hosted environments, but it can be more than three. The schemas `env2` and `env3` must already exist in the same database of the hosting environment. As postgres user, you can create them typing:
  
-$ psql database_name -c "CREATE SCHEMA env2 AUTHORIZATION database_user"
-$ psql database_name -c "CREATE SCHEMA env3 AUTHORIZATION database_user"
+    $ psql database_name -c "CREATE SCHEMA env2 AUTHORIZATION database_user"
+    $ psql database_name -c "CREATE SCHEMA env3 AUTHORIZATION database_user"
  
-Replace database_name and database_user above with your stuff.
+Replace `database_name` and `database_user` above with your stuff.
  
-So, yet on this same example, when a user accesses http://env2.com or
-http://env2.org, the Noosfero application running on production will
-turn the database schema to 'env2'. When the access is from domains
-http://env3.com or http://env3.net, the schema to be loaded will be
-'env3'.
+So, yet on this same example, when a user accesses http://env2.com or http://env2.org, the Noosfero application running on production will turn the database schema to `env2`. When the access is from domains http://env3.com or http://env3.net, the schema to be loaded will be `env3`.
  
-There is an example of this file in config/database.yml.multitenancy
+There is an example of this file in `config/database.yml.multitenancy`
  
-== Preparing the database
+Preparing the database
+----------------------
  
 Now create the environments:
  
-$ RAILS_ENV=production rake multitenancy:create
+    $ RAILS_ENV=production rake multitenancy:create
  
-This command above will create the hosted environment files equal to
-their hosting environment, here called 'production'.
+This command above will create the hosted environment files equal to their hosting environment, here called 'production'.
  
 Run db:schema:load for each other environment:
  
-$ RAILS_ENV=env2_production rake db:schema:load
-$ RAILS_ENV=env3_production rake db:schema:load
+    $ RAILS_ENV=env2_production rake db:schema:load
+    $ RAILS_ENV=env3_production rake db:schema:load
  
-Then run the migrations for the hosting environment, and it will
-run for each of its hosted environments:
+Then run the migrations for the hosting environment, and it will run for each of its hosted environments:
  
-RAILS_ENV=production rake db:migrate
+    RAILS_ENV=production rake db:migrate
  
-== Start Noosfero
+Start Noosfero
+--------------
  
 Run Noosfero init file as root:
  
-# invoke-rc.d noosfero start
+    # invoke-rc.d noosfero start
  
-== Solr
+Feed updater & Delayed job
+--------------------------
  
-It's necessary to run only one instance of Solr. Don't worry
-about this, Noosfero initializer had already done this for you.
+Just for your information, a daemon of `feed-updater` and `delayed_job` must be running for each environment. Noosfero initializer do this, relax.
  
-== Feed updater & Delayed job
+Uploaded files
+--------------
  
-Just for your information, a daemon of feed-updater and delayed_job
-must be running for each environment. Noosfero initializer do this,
-relax.
+When running with PostgreSQL, Noosfero uploads stuff to a folder named the same way as the running schema. Inside the upload folder root, for example, will be `public/image_uploads/env2` and `public/image_uploads/env3`.
  
-== Uploaded files
+Adding multitenancy support to an existing Noosfero environment
+---------------------------------------------------------------
  
-When running with PostgreSQL, Noosfero uploads stuff to a folder named
-the same way as the running schema. Inside the upload folder root, for
-example, will be public/image_uploads/env2 and public/image_uploads/env3.
+If you already have a Noosfero environment, you can turn it multitenant by following the steps below in addition to the previous steps:
  
-== Adding multitenancy support to an existing Noosfero environment
+### 1. Reindex your database
  
-If you already have a Noosfero environment, you can turn it multitenant
-by following the steps below in addition to the previous steps:
+Rebuild the Solr index by running the following task just for your hosting environment, do this as noosfero user:
  
-1. Reindex your database
+    $ RAILS_ENV=production rake multitenancy:reindex
  
-Rebuild the Solr index by running the following task just
-for your hosting environment, do this as noosfero user:
+### 2. Move the uploaded files to the right place
  
-$ RAILS_ENV=production rake multitenancy:reindex
+Add a directory with the same name as your schema name (by default this name is `public`) in the root of each upload directory, for example, `public/articles/0000` will be moved to `public/articles/public/0000`. Do this with the directories `public/image_uploads`, `public/articles` and `public/thumbnails`.
  
-2. Move the uploaded files to the right place
+### 3. Fix paths on activities
  
-Add a directory with the same name as your schema name (by default this
-name is 'public') in the root of each upload directory, for example,
-public/articles/0000 will be moved to public/articles/public/0000. Do this
-with the directories public/image_uploads, public/articles and public/thumbnails.
+The profile activities store static paths to the images, so it's necessary to fix these paths. You can do this easily by setting an alias on your webserver. On Apache you can add the three rules below, where 'public' is the schema name:
  
-3. Fix paths on activities
-
-The profile activities store static paths to the images, so it's necessary to fix
-these paths. You can do this easily by setting an alias on your webserver.
-On Apache you can add the three rules below, where 'public' is the schema name:
-
-  RewriteRule ^/articles(.+) /articles/public$1
-  RewriteRule ^/image_uploads(.+) /image_uploads/public$1
-  RewriteRule ^/thumbnails(.+) /thumbnails/public$1
+    RewriteRule ^/articles(.+) /articles/public$1
+    RewriteRule ^/image_uploads(.+) /image_uploads/public$1
+    RewriteRule ^/thumbnails(.+) /thumbnails/public$1
-= Setting up Varnish for your Noosfero site
+Setting up Varnish for your Noosfero site
+=========================================
  
-Varnish is a HTTP caching server, and using it together with Noosfero is highly
-recommended. See http://www.varnish-cache.org/ for more information on Varnish.
+Varnish is a HTTP caching server, and using it together with Noosfero is highly recommended. See http://www.varnish-cache.org/ for more information on Varnish.
  
 Varnish can be set up to use with Noosfero with the following steps:
  
-1) setup Noosfero with apache according to the INSTALL file. If you used the
-Debian package to install noosfero, you don't need to do anything about this.
+1) setup Noosfero with apache according to the `INSTALL.md` file. If you used the Debian package to install noosfero, you don't need to do anything about this.
  
 2) install Varnish
  
-  # apt-get install varnish
+    # apt-get install varnish
  
 Install the RPAF apache module (or skip this step if not using apache):
  
-  # apt-get install libapache2-mod-rpaf
+    # apt-get install libapache2-mod-rpaf
  
-3) Change Apache to listen on port 8080 instead of 80
+3) Change Apache to listen on port `8080` instead of `80`
  
-3a) Edit /etc/apache2/ports.conf, and:
+3a) Edit `/etc/apache2/ports.conf`, and:
  
-  * change 'NameVirtualHost *:80' to 'NameVirtualHost *:8080'
-  * change 'Listen 80' to 'Listen 127.0.0.1:8080'
+  * change `NameVirtualHost *:80` to `NameVirtualHost *:8080`
+  * change `Listen 80` to `Listen 127.0.0.1:8080`
  
-3b) Edit /etc/apache2/sites-enabled/*, and change '<VirtualHost *:80>' to
-'<VirtualHost *:8080>'
+3b) Edit `/etc/apache2/sites-enabled/*`, and change `<VirtualHost *:80>` to `<VirtualHost *:8080>`
  
 3c) Restart apache
  
-  # invoke-rc.d apache2 restart
+    # invoke-rc.d apache2 restart
  
 4) Varnish configuration
  
-4a) Edit /etc/default/varnish
+4a) Edit `/etc/default/varnish`
  
-   * change the line that says "START=no" to say "START=yes"
-   * change '-a :6081' to '-a :80'
+   * change the line that says `START=no` to say `START=yes`
+   * change `-a :6081` to `-a :80`
  
-4b) Edit /etc/varnish/default.vcl and add the following lines at the end:
+4b) Edit `/etc/varnish/default.vcl` and add the following lines at the end:
  
-  include "/etc/noosfero/varnish-noosfero.vcl";
-  include "/etc/noosfero/varnish-accept-language.vcl";
+    include "/etc/noosfero/varnish-noosfero.vcl";
+    include "/etc/noosfero/varnish-accept-language.vcl";
  
-On manual installations, change "/etc/noosfero/*" to
-"{Rails.root}/etc/noosfero/*"
+On manual installations, change `/etc/noosfero/*` to `{Rails.root}/etc/noosfero/*`
  
-NOTE: it is very important that the *.vcl files are included in that order,
-i.e. *first* include "varnish-noosfero.vcl", and *after*
-"noosfero-accept-language.cvl".
+**NOTE**: it is very important that the `*.vcl` files are included in that order, i.e. *first* include `varnish-noosfero.vcl`, and *after* `noosfero-accept-language.cvl`.
  
 4c) Restart Varnish
  
-  # invoke-rc.d varnish restart
+    # invoke-rc.d varnish restart
  
 5) Enable varnish logging:
  
-5a) Edit /etc/default/varnishncsa and uncomment the line that contains:
+5a) Edit `/etc/default/varnishncsa` and uncomment the line that contains:
  
-VARNISHNCSA_ENABLED=1
+    VARNISHNCSA_ENABLED=1
  
-The varnish log will be written to /var/log/varnish/varnishncsa.log in an
-apache-compatible format. You should change your statistics generation software
-(e.g. awstats) to use that instead of apache logs.
+The varnish log will be written to `/var/log/varnish/varnishncsa.log` in an apache-compatible format. You should change your statistics generation software (e.g. awstats) to use that instead of apache logs.
  
 5b) Restart Varnish Logging service
  
-  # invoke-rc.d varnishncsa restart
+    # invoke-rc.d varnishncsa restart
  
-Thanks to Cosimo Streppone for varnish-accept-language. See
-http://github.com/cosimo/varnish-accept-language for more information.
+Thanks to Cosimo Streppone for varnish-accept-language. See http://github.com/cosimo/varnish-accept-language for more information.
 Noosfero - a web-based social platform
 ======================================
  
-http://www.noosfero.org/
+http://www.noosfero.org
  
 Documentation
 -------------
  
 The following documentation is available:
  
-File                  Purpose
-~~~~~~~~~~~~~~~~~~~~  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-INSTALL               install instructions
-INSTALL.awstats       install instructions - access statistics service
-INSTALL.chat          install instructions - chat service
-INSTALL.email         install instructions - email service
-INSTALL.multitenancy  install instructions - multiple sites
-INSTALL.varnish       install instructions - varnish HTTP caching (recommended)
-HACKING               development instruction
-RELEASING             instructions for doing releases
-doc/noosfero/*        user documentation (available through the app itself)
+    File                     Purpose
+    -----------------------  --------------------------------------------------------
+    INSTALL.md               install instructions
+    INSTALL.awstats.md       install instructions - access statistics service
+    INSTALL.chat.md          install instructions - chat service
+    INSTALL.email.md         install instructions - email service
+    INSTALL.multitenancy.md  install instructions - multiple sites
+    INSTALL.varnish.md       install instructions - varnish HTTP caching (recommended)
+    HACKING.md               development instruction
+    RELEASING.md             instructions for doing releases
+    doc/noosfero/*           user documentation (available through the app itself)
  
  
 Authors and copyright
@@ -26,8 +26,8 @@ Authors and copyright
  
 Authorship and copyright information is available in the files listed below.
  
-File                  Purpose
-~~~~~~~~~~~~~~~~~~~~  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-AUTHORS               list of authors (updated at each release)
-COPYRIGHT             Copyright statement for the project
-COPYING               Full text of the project license
+    File                  Purpose
+    --------------------  -----------------------------------------
+    AUTHORS.md            list of authors (updated at each release)
+    COPYRIGHT             Copyright statement for the project
+    COPYING               Full text of the project license
-== Welcome to Rails
-
-Rails is a web-application and persistence framework that includes everything
-needed to create database-backed web-applications according to the
-Model-View-Control pattern of separation. This pattern splits the view (also
-called the presentation) into "dumb" templates that are primarily responsible
-for inserting pre-built data in between HTML tags. The model contains the
-"smart" domain objects (such as Account, Product, Person, Post) that holds all
-the business logic and knows how to persist themselves to a database. The
-controller handles the incoming requests (such as Save New Account, Update
-Product, Show Post) by manipulating the model and directing data to the view.
-
-In Rails, the model is handled by what's called an object-relational mapping
-layer entitled Active Record. This layer allows you to present the data from
-database rows as objects and embellish these data objects with business logic
-methods. You can read more about Active Record in 
-link:files/vendor/rails/activerecord/README.html.
-
-The controller and view are handled by the Action Pack, which handles both
-layers by its two parts: Action View and Action Controller. These two layers
-are bundled in a single package due to their heavy interdependence. This is
-unlike the relationship between the Active Record and Action Pack that is much
-more separate. Each of these packages can be used independently outside of
-Rails.  You can read more about Action Pack in 
-link:files/vendor/rails/actionpack/README.html.
-
-
-== Getting started
-
-1. Start the web server: <tt>ruby script/server</tt> (run with --help for options)
-2. Go to http://localhost:3000/ and get "Welcome aboard: You’re riding the Rails!"
-3. Follow the guidelines to start developing your application
+Welcome to Rails
+================
  
+Rails is a web-application and persistence framework that includes everything needed to create database-backed web-applications according to the Model-View-Control pattern of separation. This pattern splits the view (also called the presentation) into "dumb" templates that are primarily responsible for inserting pre-built data in between HTML tags. The model contains the "smart" domain objects (such as Account, Product, Person, Post) that holds all the business logic and knows how to persist themselves to a database. The controller handles the incoming requests (such as Save New Account, Update Product, Show Post) by manipulating the model and directing data to the view.
  
-== Web servers
+In Rails, the model is handled by what's called an object-relational mapping layer entitled Active Record. This layer allows you to present the data from database rows as objects and embellish these data objects with business logic methods. You can read more about Active Record in `.../rails/activerecord/README.html`.
  
-Rails uses the built-in web server in Ruby called WEBrick by default, so you don't
-have to install or configure anything to play around. 
+The controller and view are handled by the Action Pack, which handles both layers by its two parts: Action View and Action Controller. These two layers are bundled in a single package due to their heavy interdependence. This is unlike the relationship between the Active Record and Action Pack that is much more separate. Each of these packages can be used independently outside of Rails. You can read more about Action Pack in `.../rails/actionpack/README.html`.
  
-If you have lighttpd installed, though, it'll be used instead when running script/server.
-It's considerably faster than WEBrick and suited for production use, but requires additional
-installation and currently only works well on OS X/Unix (Windows users are encouraged
-to start with WEBrick). We recommend version 1.4.11 and higher. You can download it from
-http://www.lighttpd.net.
  
-If you want something that's halfway between WEBrick and lighttpd, we heartily recommend
-Mongrel. It's a Ruby-based web server with a C-component (so it requires compilation) that
-also works very well with Windows. See more at http://mongrel.rubyforge.org/.
+Getting started
+---------------
  
-But of course its also possible to run Rails with the premiere open source web server Apache.
-To get decent performance, though, you'll need to install FastCGI. For Apache 1.3, you want
-to use mod_fastcgi. For Apache 2.0+, you want to use mod_fcgid.
+1. Start the web server: `ruby script/server` (run with `--help` for options)
+2. Go to http://localhost:3000/ and get "Welcome aboard: You’re riding the Rails!"
+3. Follow the guidelines to start developing your application
  
-See http://wiki.rubyonrails.com/rails/pages/FastCGI for more information on FastCGI.
+Web servers
+-----------
  
-== Example for Apache conf
+Rails uses the built-in web server in Ruby called WEBrick by default, so you don't have to install or configure anything to play around. 
  
-  <VirtualHost *:80>
-    ServerName rails
-    DocumentRoot /path/application/public/
-    ErrorLog /path/application/log/server.log
-  
-    <Directory /path/application/public/>
-      Options ExecCGI FollowSymLinks
-      AllowOverride all
-      Allow from all
-      Order allow,deny
-    </Directory>
-  </VirtualHost>
+If you have lighttpd installed, though, it'll be used instead when running script/server. It's considerably faster than WEBrick and suited for production use, but requires additional installation and currently only works well on OS X/Unix (Windows users are encouraged to start with WEBrick). We recommend version 1.4.11 and higher. You can download it from http://www.lighttpd.net.
  
-NOTE: Be sure that CGIs can be executed in that directory as well. So ExecCGI
-should be on and ".cgi" should respond. All requests from 127.0.0.1 go
-through CGI, so no Apache restart is necessary for changes. All other requests
-go through FCGI (or mod_ruby), which requires a restart to show changes.
+If you want something that's halfway between WEBrick and lighttpd, we heartily recommend Mongrel. It's a Ruby-based web server with a C-component (so it requires compilation) that also works very well with Windows. See more at http://mongrel.rubyforge.org/.
  
+But of course its also possible to run Rails with the premiere open source web server Apache. To get decent performance, though, you'll need to install FastCGI. For Apache 1.3, you want to use mod_fastcgi. For Apache 2.0+, you want to use mod_fcgid.
  
-== Debugging Rails
+See http://wiki.rubyonrails.com/rails/pages/FastCGI for more information on FastCGI.
  
-Have "tail -f" commands running on both the server.log, production.log, and
-test.log files. Rails will automatically display debugging and runtime
-information to these files. Debugging info will also be shown in the browser
-on requests from 127.0.0.1.
+Example for Apache conf
+-----------------------
  
+    <VirtualHost *:80>
+      ServerName rails
+      DocumentRoot /path/application/public/
+      ErrorLog /path/application/log/server.log
+    
+      <Directory /path/application/public/>
+        Options ExecCGI FollowSymLinks
+        AllowOverride all
+        Allow from all
+        Order allow,deny
+      </Directory>
+    </VirtualHost>
  
-== Breakpoints
+NOTE: Be sure that CGIs can be executed in that directory as well. So ExecCGI should be on and ".cgi" should respond. All requests from 127.0.0.1 go through CGI, so no Apache restart is necessary for changes. All other requests go through FCGI (or mod_ruby), which requires a restart to show changes.
  
-Breakpoint support is available through the script/breakpointer client. This
-means that you can break out of execution at any point in the code, investigate
-and change the model, AND then resume execution! Example:
+Debugging Rails
+---------------
  
-  class WeblogController < ActionController::Base
-    def index
-      @posts = Post.find_all
-      breakpoint "Breaking out from the list"
+Have "tail -f" commands running on both the server.log, production.log, and test.log files. Rails will automatically display debugging and runtime information to these files. Debugging info will also be shown in the browser on requests from 127.0.0.1.
+
+Breakpoints
+-----------
+
+Breakpoint support is available through the script/breakpointer client. This means that you can break out of execution at any point in the code, investigate and change the model, AND then resume execution! Example:
+
+    class WeblogController < ActionController::Base
+      def index
+        @posts = Post.find_all
+        breakpoint "Breaking out from the list"
+      end
     end
-  end
  
-So the controller will accept the action, run the first line, then present you
-with a IRB prompt in the breakpointer window. Here you can do things like:
+So the controller will accept the action, run the first line, then present you with a IRB prompt in the breakpointer window. Here you can do things like:
  
 Executing breakpoint "Breaking out from the list" at .../webrick_server.rb:16 in 'breakpoint'
  
-  >> @posts.inspect
-  => "[#<Post:0x14a6be8 @attributes={\"title\"=>nil, \"body\"=>nil, \"id\"=>\"1\"}>, 
-       #<Post:0x14a6620 @attributes={\"title\"=>\"Rails you know!\", \"body\"=>\"Only ten..\", \"id\"=>\"2\"}>]"
-  >> @posts.first.title = "hello from a breakpoint"
-  => "hello from a breakpoint"
+    >> @posts.inspect
+    => "[#<Post:0x14a6be8 @attributes={\"title\"=>nil, \"body\"=>nil, \"id\"=>\"1\"}>, 
+         #<Post:0x14a6620 @attributes={\"title\"=>\"Rails you know!\", \"body\"=>\"Only ten..\", \"id\"=>\"2\"}>]"
+    >> @posts.first.title = "hello from a breakpoint"
+    => "hello from a breakpoint"
  
 ...and even better is that you can examine how your runtime objects actually work:
  
-  >> f = @posts.first 
-  => #<Post:0x13630c4 @attributes={"title"=>nil, "body"=>nil, "id"=>"1"}>
-  >> f.
-  Display all 152 possibilities? (y or n)
+    >> f = @posts.first 
+    => #<Post:0x13630c4 @attributes={"title"=>nil, "body"=>nil, "id"=>"1"}>
+    >> f.
+    Display all 152 possibilities? (y or n)
  
 Finally, when you're ready to resume execution, you press CTRL-D
  
+Console
+-------
  
-== Console
-
-You can interact with the domain model by starting the console through script/console. 
-Here you'll have all parts of the application configured, just like it is when the
-application is running. You can inspect domain models, change values, and save to the
-database. Starting the script without arguments will launch it in the development environment.
-Passing an argument will specify a different environment, like <tt>script/console production</tt>.
+You can interact with the domain model by starting the console through script/console. Here you'll have all parts of the application configured, just like it is when the application is running. You can inspect domain models, change values, and save to the database. Starting the script without arguments will launch it in the development environment. Passing an argument will specify a different environment, like `script/console production`.
  
-To reload your controllers and models after launching the console run <tt>reload!</tt>
+To reload your controllers and models after launching the console run `reload!`
  
+Description of contents
+-----------------------
  
-
-== Description of contents
-
-app
+* `app`
   Holds all the code that's specific to this particular application.
  
-app/controllers
-  Holds controllers that should be named like weblog_controller.rb for
-  automated URL mapping. All controllers should descend from
-  ActionController::Base.
+* `app/controllers`
+  Holds controllers that should be named like weblog_controller.rb for automated URL mapping. All controllers should descend from `ActionController::Base`.
  
-app/models
-  Holds models that should be named like post.rb.
-  Most models will descend from ActiveRecord::Base.
+* `app/models`
+  Holds models that should be named like post.rb. Most models will descend from `ActiveRecord::Base`.
  
-app/views
-  Holds the template files for the view that should be named like
-  weblog/index.rhtml for the WeblogController#index action. All views use eRuby
-  syntax. This directory can also be used to keep stylesheets, images, and so on
-  that can be symlinked to public.
+* `app/views`
+  Holds the template files for the view that should be named like `weblog/index.rhtml` for the `WeblogController#index` action. All views use eRuby syntax. This directory can also be used to keep stylesheets, images, and so on that can be symlinked to public.
  
-app/helpers
-  Holds view helpers that should be named like weblog_helper.rb.
+* `app/helpers`
+  Holds view helpers that should be named like `weblog_helper.rb`.
  
-app/apis
+* `app/apis`
   Holds API classes for web services.
  
-config
+* `config`
   Configuration files for the Rails environment, the routing map, the database, and other dependencies.
  
-components
+* `components`
   Self-contained mini-applications that can bundle together controllers, models, and views.
  
-db
-  Contains the database schema in schema.rb.  db/migrate contains all
-  the sequence of Migrations for your schema.
+* `db`
+  Contains the database schema in `schema.rb`.
+
+* `db/migrate`
+  Contains all the sequence of Migrations for your schema.
  
-lib
-  Application specific libraries. Basically, any kind of custom code that doesn't
-  belong under controllers, models, or helpers. This directory is in the load path.
+* `lib`
+  Application specific libraries. Basically, any kind of custom code that doesn't belong under controllers, models, or helpers. This directory is in the load path.
  
-public
-  The directory available for the web server. Contains subdirectories for images, stylesheets,
-  and javascripts. Also contains the dispatchers and the default HTML files.
+* `public`
+  The directory available for the web server. Contains subdirectories for images, stylesheets, and javascripts. Also contains the dispatchers and the default HTML files.
  
-script
+* `script`
   Helper scripts for automation and generation.
  
-test
+* `test`
   Unit and functional tests along with fixtures.
  
-vendor
-  External libraries that the application depends on. Also includes the plugins subdirectory.
-  This directory is in the load path.
+* `vendor`
+  External libraries that the application depends on. Also includes the plugins subdirectory. This directory is in the load path.
-= Noosfero release tasks
+Noosfero release tasks
+======================
  
 This file documents release-related activities.
  
-== Working with translations
+Working with translations
+-------------------------
  
-* Update translation files: <tt>rake updatepo</tt>. Then <tt>git commit</tt> them.
+* Update translation files: `rake updatepo`. Then `git commit` them.
 * Send the PO files to the translators.
-* Get the PO files back from translators, put in po/ under the correct language
-  name (e.,g. po/pt_BR/) and <tt>git commit</tt>.
-* test translations: <tt>rake makemo</tt> and browse the application on the web.
+* Get the PO files back from translators, put in `po/` under the correct language name (e.,g. `po/pt_BR/`) and `git commit`.
+* test translations: `rake makemo` and browse the application on the web.
  
-== Releasing noosfero
+Releasing noosfero
+------------------
  
 Considering you are on a Debian GNU/Linux or Debian-based system
- # apt-get install devscripts debhelper
+
+    # apt-get install devscripts debhelper
  
 To prepare a release of noosfero, you must follow the steps below:
  
 * Finish all requirements and bugs assigned to the to-be-released version
 * Make sure all tests pass
 * Write release notes at the version's wiki topic
-* Generate packages with <tt>rake noosfero:release[(stable|test)]</tt>. This task will:
+* Generate packages with `rake noosfero:release[(stable|test)]`. This task will:
   * Update the version in lib/noosfero.rb and debian/changelog.
   * Create the tarbal and the deb pkg under pkg/ directory.
   * Create a git tag and push it.
@@ -28,13 +31,9 @@ To prepare a release of noosfero, you must follow the steps below:
 * Test that the tarball and deb package are ok
 * Go to the version's wiki topic and edit it to reflect the new reality
 * Edit the topic WebPreferences and update DEBIAN_REPOSITORY_TOPICS setting
-* Attach the generated packages to that topic. Before attaching calculate the
-  sha1 of the package (with sha1sum and paste the SHA1 hash as comment in the
-  attachment form)
+* Attach the generated packages to that topic. Before attaching calculate the sha1 of the package (with sha1sum and paste the SHA1 hash as comment in the attachment form)
 * Download the attached and verify the MD5 hash
 * Update an eventual demonstration version that you run.
-* Write an announcement e-mail to the relevant mailing lists pointing to the
-  release notes, and maybe to the demonstration version.
+* Write an announcement e-mail to the relevant mailing lists pointing to the release notes, and maybe to the demonstration version.
  
-If you had any problem during these steps, you can do <tt>rake clobber_package</tt> to
-completely delete the generated packages and start the process again.
+If you had any problem during these steps, you can do `rake clobber_package` to completely delete the generated packages and start the process again.
 README - AntiSpam (AntiSpam Plugin)
-=======================================
+===================================
  
-Plugin that checks comments against a spam checking service compatible
-with the Akismet API.
+Plugin that checks comments against a spam checking service compatible with the Akismet API.
  
  
 Enable Plugin
@@ -10,12 +9,12 @@ Enable Plugin
  
 Also, you need to enable AntiSpam Plugin at your Noosfero:
  
-cd <your_noosfero_dir>
-./script/noosfero-plugins enable anti_spam
+    cd <your_noosfero_dir>
+    ./script/noosfero-plugins enable anti_spam
  
  
 Activate Plugin
--------------
+---------------
  
 As a Noosfero administrator user, go to administrator panel:
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	==========
...	...
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.
...	...
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
...	...
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
...	...
1		-== Multitenancy support
	1	+Multitenancy support
	2	+====================
2	3
3		-Multitenancy refers to a principle in software architecture where a
4		-single instance of the software runs on a server, serving multiple
5		-client organizations (tenants). Multitenancy is contrasted with a
6		-multi-instance architecture where separate software instances (or
7		-hardware systems) are set up for different client organizations. With
8		-a multitenant architecture, a software application is designed to
9		-virtually partition its data and configuration, and each client
10		-organization works with a customized virtual application instance.
	4	+Multitenancy refers to a principle in software architecture where a single instance of the software runs on a server, serving multiple client organizations (tenants). Multitenancy is contrasted with a multi-instance architecture where separate software instances (or hardware systems) are set up for different client organizations. With a multitenant architecture, a software application is designed to virtually partition its data and configuration, and each client organization works with a customized virtual application instance.
11	5
12	6	Today this feature is available only for PostgreSQL databases.
13	7
14		-This document assumes that you have a new fully PostgresSQL default Noosfero
15		-installation as explained at the INSTALL file.
	8	+This document assumes that you have a new fully PostgresSQL default Noosfero installation as explained at the `INSTALL.md` file.
16	9
17		-== Separated data
	10	+Separated data
	11	+--------------
18	12
19	13	The items below are separated for each hosted environment:
20	14
...	...	@@ -25,139 +19,115 @@ The items below are separated for each hosted environment:
25	19	* Feed updater
26	20	* Delayed Job Workers
27	21
28		-== Database configuration file
	22	+Database configuration file
	23	+---------------------------
29	24
30		-The file config/database.yml must follow a structure in order to
31		-achieve multitenancy support. In this example, we will set 3
32		-different environments: env1, env2 and env3.
	25	+The file config/database.yml must follow a structure in order to achieve multitenancy support. In this example, we will set 3 different environments: env1, env2 and env3.
33	26
34	27	Each "hosted" environment must have an entry like this:
35	28
36		-env1_production:
37		- adapter: postgresql
38		- encoding: unicode
39		- database: noosfero
40		- schema_search_path: public
41		- username: noosfero
42		- domains:
43		- - env1.com
44		- - env1.org
45		-
46		-env2_production:
47		- adapter: postgresql
48		- encoding: unicode
49		- database: noosfero
50		- schema_search_path: env2
51		- username: noosfero
52		- domains:
53		- - env2.com
54		- - env2.org
55		-
56		-env3_production:
57		- adapter: postgresql
58		- encoding: unicode
59		- database: noosfero
60		- schema_search_path: env3
61		- username: noosfero
62		- domains:
63		- - env3.com
64		- - env3.net
65		-
66		-The "hosted" environments define, besides the schema_search_path, a
67		-list of domains that, when accessed, tells which database the
68		-application should use. Also, the environment name must end with
69		-'_hosting', where 'hosting' is the name of the hosting environment.
	29	+ env1_production:
	30	+ adapter: postgresql
	31	+ encoding: unicode
	32	+ database: noosfero
	33	+ schema_search_path: public
	34	+ username: noosfero
	35	+ domains:
	36	+ - env1.com
	37	+ - env1.org
	38	+
	39	+ env2_production:
	40	+ adapter: postgresql
	41	+ encoding: unicode
	42	+ database: noosfero
	43	+ schema_search_path: env2
	44	+ username: noosfero
	45	+ domains:
	46	+ - env2.com
	47	+ - env2.org
	48	+
	49	+ env3_production:
	50	+ adapter: postgresql
	51	+ encoding: unicode
	52	+ database: noosfero
	53	+ schema_search_path: env3
	54	+ username: noosfero
	55	+ domains:
	56	+ - env3.com
	57	+ - env3.net
	58	+
	59	+The "hosted" environments define, besides the `schema_search_path`, a list of domains that, when accessed, tells which database the application should use. Also, the environment name must end with "`_<hosting>`", where `<hosting>` is the name of the hosting environment.
70	60
71	61	You must also tell the application which is the default environment.
72	62
73		-production:
74		- env1_production
	63	+ production:
	64	+ env1_production
75	65
76		-On the example above there are only three hosted environments, but it
77		-can be more than three. The schemas 'env2' and 'env3' must already
78		-exist in the same database of the hosting environment. As postgres
79		-user, you can create them typing:
	66	+On the example above there are only three hosted environments, but it can be more than three. The schemas `env2` and `env3` must already exist in the same database of the hosting environment. As postgres user, you can create them typing:
80	67
81		-$ psql database_name -c "CREATE SCHEMA env2 AUTHORIZATION database_user"
82		-$ psql database_name -c "CREATE SCHEMA env3 AUTHORIZATION database_user"
	68	+ $ psql database_name -c "CREATE SCHEMA env2 AUTHORIZATION database_user"
	69	+ $ psql database_name -c "CREATE SCHEMA env3 AUTHORIZATION database_user"
83	70
84		-Replace database_name and database_user above with your stuff.
	71	+Replace `database_name` and `database_user` above with your stuff.
85	72
86		-So, yet on this same example, when a user accesses http://env2.com or
87		-http://env2.org, the Noosfero application running on production will
88		-turn the database schema to 'env2'. When the access is from domains
89		-http://env3.com or http://env3.net, the schema to be loaded will be
90		-'env3'.
	73	+So, yet on this same example, when a user accesses http://env2.com or http://env2.org, the Noosfero application running on production will turn the database schema to `env2`. When the access is from domains http://env3.com or http://env3.net, the schema to be loaded will be `env3`.
91	74
92		-There is an example of this file in config/database.yml.multitenancy
	75	+There is an example of this file in `config/database.yml.multitenancy`
93	76
94		-== Preparing the database
	77	+Preparing the database
	78	+----------------------
95	79
96	80	Now create the environments:
97	81
98		-$ RAILS_ENV=production rake multitenancy:create
	82	+ $ RAILS_ENV=production rake multitenancy:create
99	83
100		-This command above will create the hosted environment files equal to
101		-their hosting environment, here called 'production'.
	84	+This command above will create the hosted environment files equal to their hosting environment, here called 'production'.
102	85
103	86	Run db:schema:load for each other environment:
104	87
105		-$ RAILS_ENV=env2_production rake db:schema:load
106		-$ RAILS_ENV=env3_production rake db:schema:load
	88	+ $ RAILS_ENV=env2_production rake db:schema:load
	89	+ $ RAILS_ENV=env3_production rake db:schema:load
107	90
108		-Then run the migrations for the hosting environment, and it will
109		-run for each of its hosted environments:
	91	+Then run the migrations for the hosting environment, and it will run for each of its hosted environments:
110	92
111		-RAILS_ENV=production rake db:migrate
	93	+ RAILS_ENV=production rake db:migrate
112	94
113		-== Start Noosfero
	95	+Start Noosfero
	96	+--------------
114	97
115	98	Run Noosfero init file as root:
116	99
117		-# invoke-rc.d noosfero start
	100	+ # invoke-rc.d noosfero start
118	101
119		-== Solr
	102	+Feed updater & Delayed job
	103	+--------------------------
120	104
121		-It's necessary to run only one instance of Solr. Don't worry
122		-about this, Noosfero initializer had already done this for you.
	105	+Just for your information, a daemon of `feed-updater` and `delayed_job` must be running for each environment. Noosfero initializer do this, relax.
123	106
124		-== Feed updater & Delayed job
	107	+Uploaded files
	108	+--------------
125	109
126		-Just for your information, a daemon of feed-updater and delayed_job
127		-must be running for each environment. Noosfero initializer do this,
128		-relax.
	110	+When running with PostgreSQL, Noosfero uploads stuff to a folder named the same way as the running schema. Inside the upload folder root, for example, will be `public/image_uploads/env2` and `public/image_uploads/env3`.
129	111
130		-== Uploaded files
	112	+Adding multitenancy support to an existing Noosfero environment
	113	+---------------------------------------------------------------
131	114
132		-When running with PostgreSQL, Noosfero uploads stuff to a folder named
133		-the same way as the running schema. Inside the upload folder root, for
134		-example, will be public/image_uploads/env2 and public/image_uploads/env3.
	115	+If you already have a Noosfero environment, you can turn it multitenant by following the steps below in addition to the previous steps:
135	116
136		-== Adding multitenancy support to an existing Noosfero environment
	117	+### 1. Reindex your database
137	118
138		-If you already have a Noosfero environment, you can turn it multitenant
139		-by following the steps below in addition to the previous steps:
	119	+Rebuild the Solr index by running the following task just for your hosting environment, do this as noosfero user:
140	120
141		-1. Reindex your database
	121	+ $ RAILS_ENV=production rake multitenancy:reindex
142	122
143		-Rebuild the Solr index by running the following task just
144		-for your hosting environment, do this as noosfero user:
	123	+### 2. Move the uploaded files to the right place
145	124
146		-$ RAILS_ENV=production rake multitenancy:reindex
	125	+Add a directory with the same name as your schema name (by default this name is `public`) in the root of each upload directory, for example, `public/articles/0000` will be moved to `public/articles/public/0000`. Do this with the directories `public/image_uploads`, `public/articles` and `public/thumbnails`.
147	126
148		-2. Move the uploaded files to the right place
	127	+### 3. Fix paths on activities
149	128
150		-Add a directory with the same name as your schema name (by default this
151		-name is 'public') in the root of each upload directory, for example,
152		-public/articles/0000 will be moved to public/articles/public/0000. Do this
153		-with the directories public/image_uploads, public/articles and public/thumbnails.
	129	+The profile activities store static paths to the images, so it's necessary to fix these paths. You can do this easily by setting an alias on your webserver. On Apache you can add the three rules below, where 'public' is the schema name:
154	130
155		-3. Fix paths on activities
156		-
157		-The profile activities store static paths to the images, so it's necessary to fix
158		-these paths. You can do this easily by setting an alias on your webserver.
159		-On Apache you can add the three rules below, where 'public' is the schema name:
160		-
161		- RewriteRule ^/articles(.+) /articles/public$1
162		- RewriteRule ^/image_uploads(.+) /image_uploads/public$1
163		- RewriteRule ^/thumbnails(.+) /thumbnails/public$1
	131	+ RewriteRule ^/articles(.+) /articles/public$1
	132	+ RewriteRule ^/image_uploads(.+) /image_uploads/public$1
	133	+ RewriteRule ^/thumbnails(.+) /thumbnails/public$1
...	...
1		-= Setting up Varnish for your Noosfero site
	1	+Setting up Varnish for your Noosfero site
	2	+=========================================
2	3
3		-Varnish is a HTTP caching server, and using it together with Noosfero is highly
4		-recommended. See http://www.varnish-cache.org/ for more information on Varnish.
	4	+Varnish is a HTTP caching server, and using it together with Noosfero is highly recommended. See http://www.varnish-cache.org/ for more information on Varnish.
5	5
6	6	Varnish can be set up to use with Noosfero with the following steps:
7	7
8		-1) setup Noosfero with apache according to the INSTALL file. If you used the
9		-Debian package to install noosfero, you don't need to do anything about this.
	8	+1) setup Noosfero with apache according to the `INSTALL.md` file. If you used the Debian package to install noosfero, you don't need to do anything about this.
10	9
11	10	2) install Varnish
12	11
13		- # apt-get install varnish
	12	+ # apt-get install varnish
14	13
15	14	Install the RPAF apache module (or skip this step if not using apache):
16	15
17		- # apt-get install libapache2-mod-rpaf
	16	+ # apt-get install libapache2-mod-rpaf
18	17
19		-3) Change Apache to listen on port 8080 instead of 80
	18	+3) Change Apache to listen on port `8080` instead of `80`
20	19
21		-3a) Edit /etc/apache2/ports.conf, and:
	20	+3a) Edit `/etc/apache2/ports.conf`, and:
22	21
23		- * change 'NameVirtualHost :80' to 'NameVirtualHost :8080'
24		- * change 'Listen 80' to 'Listen 127.0.0.1:8080'
	22	+ * change `NameVirtualHost :80` to `NameVirtualHost :8080`
	23	+ * change `Listen 80` to `Listen 127.0.0.1:8080`
25	24
26		-3b) Edit /etc/apache2/sites-enabled/, and change '<VirtualHost :80>' to
27		-'<VirtualHost *:8080>'
	25	+3b) Edit `/etc/apache2/sites-enabled/`, and change `<VirtualHost :80>` to `<VirtualHost *:8080>`
28	26
29	27	3c) Restart apache
30	28
31		- # invoke-rc.d apache2 restart
	29	+ # invoke-rc.d apache2 restart
32	30
33	31	4) Varnish configuration
34	32
35		-4a) Edit /etc/default/varnish
	33	+4a) Edit `/etc/default/varnish`
36	34
37		- * change the line that says "START=no" to say "START=yes"
38		- * change '-a :6081' to '-a :80'
	35	+ * change the line that says `START=no` to say `START=yes`
	36	+ * change `-a :6081` to `-a :80`
39	37
40		-4b) Edit /etc/varnish/default.vcl and add the following lines at the end:
	38	+4b) Edit `/etc/varnish/default.vcl` and add the following lines at the end:
41	39
42		- include "/etc/noosfero/varnish-noosfero.vcl";
43		- include "/etc/noosfero/varnish-accept-language.vcl";
	40	+ include "/etc/noosfero/varnish-noosfero.vcl";
	41	+ include "/etc/noosfero/varnish-accept-language.vcl";
44	42
45		-On manual installations, change "/etc/noosfero/*" to
46		-"{Rails.root}/etc/noosfero/*"
	43	+On manual installations, change `/etc/noosfero/` to `{Rails.root}/etc/noosfero/`
47	44
48		-NOTE: it is very important that the *.vcl files are included in that order,
49		-i.e. first include "varnish-noosfero.vcl", and after
50		-"noosfero-accept-language.cvl".
	45	+NOTE: it is very important that the `.vcl` files are included in that order, i.e. first* include `varnish-noosfero.vcl`, and after `noosfero-accept-language.cvl`.
51	46
52	47	4c) Restart Varnish
53	48
54		- # invoke-rc.d varnish restart
	49	+ # invoke-rc.d varnish restart
55	50
56	51	5) Enable varnish logging:
57	52
58		-5a) Edit /etc/default/varnishncsa and uncomment the line that contains:
	53	+5a) Edit `/etc/default/varnishncsa` and uncomment the line that contains:
59	54
60		-VARNISHNCSA_ENABLED=1
	55	+ VARNISHNCSA_ENABLED=1
61	56
62		-The varnish log will be written to /var/log/varnish/varnishncsa.log in an
63		-apache-compatible format. You should change your statistics generation software
64		-(e.g. awstats) to use that instead of apache logs.
	57	+The varnish log will be written to `/var/log/varnish/varnishncsa.log` in an apache-compatible format. You should change your statistics generation software (e.g. awstats) to use that instead of apache logs.
65	58
66	59	5b) Restart Varnish Logging service
67	60
68		- # invoke-rc.d varnishncsa restart
	61	+ # invoke-rc.d varnishncsa restart
69	62
70		-Thanks to Cosimo Streppone for varnish-accept-language. See
71		-http://github.com/cosimo/varnish-accept-language for more information.
	63	+Thanks to Cosimo Streppone for varnish-accept-language. See http://github.com/cosimo/varnish-accept-language for more information.
...	...
1	1	Noosfero - a web-based social platform
2	2	======================================
3	3
4		-http://www.noosfero.org/
	4	+http://www.noosfero.org
5	5
6	6	Documentation
7	7	-------------
8	8
9	9	The following documentation is available:
10	10
11		-File Purpose
12		-~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
13		-INSTALL install instructions
14		-INSTALL.awstats install instructions - access statistics service
15		-INSTALL.chat install instructions - chat service
16		-INSTALL.email install instructions - email service
17		-INSTALL.multitenancy install instructions - multiple sites
18		-INSTALL.varnish install instructions - varnish HTTP caching (recommended)
19		-HACKING development instruction
20		-RELEASING instructions for doing releases
21		-doc/noosfero/* user documentation (available through the app itself)
	11	+ File Purpose
	12	+ ----------------------- --------------------------------------------------------
	13	+ INSTALL.md install instructions
	14	+ INSTALL.awstats.md install instructions - access statistics service
	15	+ INSTALL.chat.md install instructions - chat service
	16	+ INSTALL.email.md install instructions - email service
	17	+ INSTALL.multitenancy.md install instructions - multiple sites
	18	+ INSTALL.varnish.md install instructions - varnish HTTP caching (recommended)
	19	+ HACKING.md development instruction
	20	+ RELEASING.md instructions for doing releases
	21	+ doc/noosfero/* user documentation (available through the app itself)
22	22
23	23
24	24	Authors and copyright
...	...	@@ -26,8 +26,8 @@ Authors and copyright
26	26
27	27	Authorship and copyright information is available in the files listed below.
28	28
29		-File Purpose
30		-~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
31		-AUTHORS list of authors (updated at each release)
32		-COPYRIGHT Copyright statement for the project
33		-COPYING Full text of the project license
	29	+ File Purpose
	30	+ -------------------- -----------------------------------------
	31	+ AUTHORS.md list of authors (updated at each release)
	32	+ COPYRIGHT Copyright statement for the project
	33	+ COPYING Full text of the project license
...	...
1		-== Welcome to Rails
2		-
3		-Rails is a web-application and persistence framework that includes everything
4		-needed to create database-backed web-applications according to the
5		-Model-View-Control pattern of separation. This pattern splits the view (also
6		-called the presentation) into "dumb" templates that are primarily responsible
7		-for inserting pre-built data in between HTML tags. The model contains the
8		-"smart" domain objects (such as Account, Product, Person, Post) that holds all
9		-the business logic and knows how to persist themselves to a database. The
10		-controller handles the incoming requests (such as Save New Account, Update
11		-Product, Show Post) by manipulating the model and directing data to the view.
12		-
13		-In Rails, the model is handled by what's called an object-relational mapping
14		-layer entitled Active Record. This layer allows you to present the data from
15		-database rows as objects and embellish these data objects with business logic
16		-methods. You can read more about Active Record in
17		-link:files/vendor/rails/activerecord/README.html.
18		-
19		-The controller and view are handled by the Action Pack, which handles both
20		-layers by its two parts: Action View and Action Controller. These two layers
21		-are bundled in a single package due to their heavy interdependence. This is
22		-unlike the relationship between the Active Record and Action Pack that is much
23		-more separate. Each of these packages can be used independently outside of
24		-Rails. You can read more about Action Pack in
25		-link:files/vendor/rails/actionpack/README.html.
26		-
27		-
28		-== Getting started
29		-
30		-1. Start the web server: <tt>ruby script/server</tt> (run with --help for options)
31		-2. Go to http://localhost:3000/ and get "Welcome aboard: You’re riding the Rails!"
32		-3. Follow the guidelines to start developing your application
	1	+Welcome to Rails
	2	+================
33	3
	4	+Rails is a web-application and persistence framework that includes everything needed to create database-backed web-applications according to the Model-View-Control pattern of separation. This pattern splits the view (also called the presentation) into "dumb" templates that are primarily responsible for inserting pre-built data in between HTML tags. The model contains the "smart" domain objects (such as Account, Product, Person, Post) that holds all the business logic and knows how to persist themselves to a database. The controller handles the incoming requests (such as Save New Account, Update Product, Show Post) by manipulating the model and directing data to the view.
34	5
35		-== Web servers
	6	+In Rails, the model is handled by what's called an object-relational mapping layer entitled Active Record. This layer allows you to present the data from database rows as objects and embellish these data objects with business logic methods. You can read more about Active Record in `.../rails/activerecord/README.html`.
36	7
37		-Rails uses the built-in web server in Ruby called WEBrick by default, so you don't
38		-have to install or configure anything to play around.
	8	+The controller and view are handled by the Action Pack, which handles both layers by its two parts: Action View and Action Controller. These two layers are bundled in a single package due to their heavy interdependence. This is unlike the relationship between the Active Record and Action Pack that is much more separate. Each of these packages can be used independently outside of Rails. You can read more about Action Pack in `.../rails/actionpack/README.html`.
39	9
40		-If you have lighttpd installed, though, it'll be used instead when running script/server.
41		-It's considerably faster than WEBrick and suited for production use, but requires additional
42		-installation and currently only works well on OS X/Unix (Windows users are encouraged
43		-to start with WEBrick). We recommend version 1.4.11 and higher. You can download it from
44		-http://www.lighttpd.net.
45	10
46		-If you want something that's halfway between WEBrick and lighttpd, we heartily recommend
47		-Mongrel. It's a Ruby-based web server with a C-component (so it requires compilation) that
48		-also works very well with Windows. See more at http://mongrel.rubyforge.org/.
	11	+Getting started
	12	+---------------
49	13
50		-But of course its also possible to run Rails with the premiere open source web server Apache.
51		-To get decent performance, though, you'll need to install FastCGI. For Apache 1.3, you want
52		-to use mod_fastcgi. For Apache 2.0+, you want to use mod_fcgid.
	14	+1. Start the web server: `ruby script/server` (run with `--help` for options)
	15	+2. Go to http://localhost:3000/ and get "Welcome aboard: You’re riding the Rails!"
	16	+3. Follow the guidelines to start developing your application
53	17
54		-See http://wiki.rubyonrails.com/rails/pages/FastCGI for more information on FastCGI.
	18	+Web servers
	19	+-----------
55	20
56		-== Example for Apache conf
	21	+Rails uses the built-in web server in Ruby called WEBrick by default, so you don't have to install or configure anything to play around.
57	22
58		- <VirtualHost *:80>
59		- ServerName rails
60		- DocumentRoot /path/application/public/
61		- ErrorLog /path/application/log/server.log
62		-
63		- <Directory /path/application/public/>
64		- Options ExecCGI FollowSymLinks
65		- AllowOverride all
66		- Allow from all
67		- Order allow,deny
68		- </Directory>
69		- </VirtualHost>
	23	+If you have lighttpd installed, though, it'll be used instead when running script/server. It's considerably faster than WEBrick and suited for production use, but requires additional installation and currently only works well on OS X/Unix (Windows users are encouraged to start with WEBrick). We recommend version 1.4.11 and higher. You can download it from http://www.lighttpd.net.
70	24
71		-NOTE: Be sure that CGIs can be executed in that directory as well. So ExecCGI
72		-should be on and ".cgi" should respond. All requests from 127.0.0.1 go
73		-through CGI, so no Apache restart is necessary for changes. All other requests
74		-go through FCGI (or mod_ruby), which requires a restart to show changes.
	25	+If you want something that's halfway between WEBrick and lighttpd, we heartily recommend Mongrel. It's a Ruby-based web server with a C-component (so it requires compilation) that also works very well with Windows. See more at http://mongrel.rubyforge.org/.
75	26
	27	+But of course its also possible to run Rails with the premiere open source web server Apache. To get decent performance, though, you'll need to install FastCGI. For Apache 1.3, you want to use mod_fastcgi. For Apache 2.0+, you want to use mod_fcgid.
76	28
77		-== Debugging Rails
	29	+See http://wiki.rubyonrails.com/rails/pages/FastCGI for more information on FastCGI.
78	30
79		-Have "tail -f" commands running on both the server.log, production.log, and
80		-test.log files. Rails will automatically display debugging and runtime
81		-information to these files. Debugging info will also be shown in the browser
82		-on requests from 127.0.0.1.
	31	+Example for Apache conf
	32	+-----------------------
83	33
	34	+ <VirtualHost *:80>
	35	+ ServerName rails
	36	+ DocumentRoot /path/application/public/
	37	+ ErrorLog /path/application/log/server.log
	38	+
	39	+ <Directory /path/application/public/>
	40	+ Options ExecCGI FollowSymLinks
	41	+ AllowOverride all
	42	+ Allow from all
	43	+ Order allow,deny
	44	+ </Directory>
	45	+ </VirtualHost>
84	46
85		-== Breakpoints
	47	+NOTE: Be sure that CGIs can be executed in that directory as well. So ExecCGI should be on and ".cgi" should respond. All requests from 127.0.0.1 go through CGI, so no Apache restart is necessary for changes. All other requests go through FCGI (or mod_ruby), which requires a restart to show changes.
86	48
87		-Breakpoint support is available through the script/breakpointer client. This
88		-means that you can break out of execution at any point in the code, investigate
89		-and change the model, AND then resume execution! Example:
	49	+Debugging Rails
	50	+---------------
90	51
91		- class WeblogController < ActionController::Base
92		- def index
93		- @posts = Post.find_all
94		- breakpoint "Breaking out from the list"
	52	+Have "tail -f" commands running on both the server.log, production.log, and test.log files. Rails will automatically display debugging and runtime information to these files. Debugging info will also be shown in the browser on requests from 127.0.0.1.
	53	+
	54	+Breakpoints
	55	+-----------
	56	+
	57	+Breakpoint support is available through the script/breakpointer client. This means that you can break out of execution at any point in the code, investigate and change the model, AND then resume execution! Example:
	58	+
	59	+ class WeblogController < ActionController::Base
	60	+ def index
	61	+ @posts = Post.find_all
	62	+ breakpoint "Breaking out from the list"
	63	+ end
95	64	end
96		- end
97	65
98		-So the controller will accept the action, run the first line, then present you
99		-with a IRB prompt in the breakpointer window. Here you can do things like:
	66	+So the controller will accept the action, run the first line, then present you with a IRB prompt in the breakpointer window. Here you can do things like:
100	67
101	68	Executing breakpoint "Breaking out from the list" at .../webrick_server.rb:16 in 'breakpoint'
102	69
103		- >> @posts.inspect
104		- => "[#<Post:0x14a6be8 @attributes={\"title\"=>nil, \"body\"=>nil, \"id\"=>\"1\"}>,
105		- #<Post:0x14a6620 @attributes={\"title\"=>\"Rails you know!\", \"body\"=>\"Only ten..\", \"id\"=>\"2\"}>]"
106		- >> @posts.first.title = "hello from a breakpoint"
107		- => "hello from a breakpoint"
	70	+ >> @posts.inspect
	71	+ => "[#<Post:0x14a6be8 @attributes={\"title\"=>nil, \"body\"=>nil, \"id\"=>\"1\"}>,
	72	+ #<Post:0x14a6620 @attributes={\"title\"=>\"Rails you know!\", \"body\"=>\"Only ten..\", \"id\"=>\"2\"}>]"
	73	+ >> @posts.first.title = "hello from a breakpoint"
	74	+ => "hello from a breakpoint"
108	75
109	76	...and even better is that you can examine how your runtime objects actually work:
110	77
111		- >> f = @posts.first
112		- => #<Post:0x13630c4 @attributes={"title"=>nil, "body"=>nil, "id"=>"1"}>
113		- >> f.
114		- Display all 152 possibilities? (y or n)
	78	+ >> f = @posts.first
	79	+ => #<Post:0x13630c4 @attributes={"title"=>nil, "body"=>nil, "id"=>"1"}>
	80	+ >> f.
	81	+ Display all 152 possibilities? (y or n)
115	82
116	83	Finally, when you're ready to resume execution, you press CTRL-D
117	84
	85	+Console
	86	+-------
118	87
119		-== Console
120		-
121		-You can interact with the domain model by starting the console through script/console.
122		-Here you'll have all parts of the application configured, just like it is when the
123		-application is running. You can inspect domain models, change values, and save to the
124		-database. Starting the script without arguments will launch it in the development environment.
125		-Passing an argument will specify a different environment, like <tt>script/console production</tt>.
	88	+You can interact with the domain model by starting the console through script/console. Here you'll have all parts of the application configured, just like it is when the application is running. You can inspect domain models, change values, and save to the database. Starting the script without arguments will launch it in the development environment. Passing an argument will specify a different environment, like `script/console production`.
126	89
127		-To reload your controllers and models after launching the console run <tt>reload!</tt>
	90	+To reload your controllers and models after launching the console run `reload!`
128	91
	92	+Description of contents
	93	+-----------------------
129	94
130		-
131		-== Description of contents
132		-
133		-app
	95	+* `app`
134	96	Holds all the code that's specific to this particular application.
135	97
136		-app/controllers
137		- Holds controllers that should be named like weblog_controller.rb for
138		- automated URL mapping. All controllers should descend from
139		- ActionController::Base.
	98	+* `app/controllers`
	99	+ Holds controllers that should be named like weblog_controller.rb for automated URL mapping. All controllers should descend from `ActionController::Base`.
140	100
141		-app/models
142		- Holds models that should be named like post.rb.
143		- Most models will descend from ActiveRecord::Base.
	101	+* `app/models`
	102	+ Holds models that should be named like post.rb. Most models will descend from `ActiveRecord::Base`.
144	103
145		-app/views
146		- Holds the template files for the view that should be named like
147		- weblog/index.rhtml for the WeblogController#index action. All views use eRuby
148		- syntax. This directory can also be used to keep stylesheets, images, and so on
149		- that can be symlinked to public.
	104	+* `app/views`
	105	+ Holds the template files for the view that should be named like `weblog/index.rhtml` for the `WeblogController#index` action. All views use eRuby syntax. This directory can also be used to keep stylesheets, images, and so on that can be symlinked to public.
150	106
151		-app/helpers
152		- Holds view helpers that should be named like weblog_helper.rb.
	107	+* `app/helpers`
	108	+ Holds view helpers that should be named like `weblog_helper.rb`.
153	109
154		-app/apis
	110	+* `app/apis`
155	111	Holds API classes for web services.
156	112
157		-config
	113	+* `config`
158	114	Configuration files for the Rails environment, the routing map, the database, and other dependencies.
159	115
160		-components
	116	+* `components`
161	117	Self-contained mini-applications that can bundle together controllers, models, and views.
162	118
163		-db
164		- Contains the database schema in schema.rb. db/migrate contains all
165		- the sequence of Migrations for your schema.
	119	+* `db`
	120	+ Contains the database schema in `schema.rb`.
	121	+
	122	+* `db/migrate`
	123	+ Contains all the sequence of Migrations for your schema.
166	124
167		-lib
168		- Application specific libraries. Basically, any kind of custom code that doesn't
169		- belong under controllers, models, or helpers. This directory is in the load path.
	125	+* `lib`
	126	+ Application specific libraries. Basically, any kind of custom code that doesn't belong under controllers, models, or helpers. This directory is in the load path.
170	127
171		-public
172		- The directory available for the web server. Contains subdirectories for images, stylesheets,
173		- and javascripts. Also contains the dispatchers and the default HTML files.
	128	+* `public`
	129	+ The directory available for the web server. Contains subdirectories for images, stylesheets, and javascripts. Also contains the dispatchers and the default HTML files.
174	130
175		-script
	131	+* `script`
176	132	Helper scripts for automation and generation.
177	133
178		-test
	134	+* `test`
179	135	Unit and functional tests along with fixtures.
180	136
181		-vendor
182		- External libraries that the application depends on. Also includes the plugins subdirectory.
183		- This directory is in the load path.
	137	+* `vendor`
	138	+ External libraries that the application depends on. Also includes the plugins subdirectory. This directory is in the load path.
...	...
1		-= Noosfero release tasks
	1	+Noosfero release tasks
	2	+======================
2	3
3	4	This file documents release-related activities.
4	5
5		-== Working with translations
	6	+Working with translations
	7	+-------------------------
6	8
7		-* Update translation files: <tt>rake updatepo</tt>. Then <tt>git commit</tt> them.
	9	+* Update translation files: `rake updatepo`. Then `git commit` them.
8	10	* Send the PO files to the translators.
9		-* Get the PO files back from translators, put in po/ under the correct language
10		- name (e.,g. po/pt_BR/) and <tt>git commit</tt>.
11		-* test translations: <tt>rake makemo</tt> and browse the application on the web.
	11	+* Get the PO files back from translators, put in `po/` under the correct language name (e.,g. `po/pt_BR/`) and `git commit`.
	12	+* test translations: `rake makemo` and browse the application on the web.
12	13
13		-== Releasing noosfero
	14	+Releasing noosfero
	15	+------------------
14	16
15	17	Considering you are on a Debian GNU/Linux or Debian-based system
16		- # apt-get install devscripts debhelper
	18	+
	19	+ # apt-get install devscripts debhelper
17	20
18	21	To prepare a release of noosfero, you must follow the steps below:
19	22
20	23	* Finish all requirements and bugs assigned to the to-be-released version
21	24	* Make sure all tests pass
22	25	* Write release notes at the version's wiki topic
23		-* Generate packages with <tt>rake noosfero:release[(stable\|test)]</tt>. This task will:
	26	+* Generate packages with `rake noosfero:release[(stable\|test)]`. This task will:
24	27	* Update the version in lib/noosfero.rb and debian/changelog.
25	28	* Create the tarbal and the deb pkg under pkg/ directory.
26	29	* Create a git tag and push it.
...	...	@@ -28,13 +31,9 @@ To prepare a release of noosfero, you must follow the steps below:
28	31	* Test that the tarball and deb package are ok
29	32	* Go to the version's wiki topic and edit it to reflect the new reality
30	33	* Edit the topic WebPreferences and update DEBIAN_REPOSITORY_TOPICS setting
31		-* Attach the generated packages to that topic. Before attaching calculate the
32		- sha1 of the package (with sha1sum and paste the SHA1 hash as comment in the
33		- attachment form)
	34	+* Attach the generated packages to that topic. Before attaching calculate the sha1 of the package (with sha1sum and paste the SHA1 hash as comment in the attachment form)
34	35	* Download the attached and verify the MD5 hash
35	36	* Update an eventual demonstration version that you run.
36		-* Write an announcement e-mail to the relevant mailing lists pointing to the
37		- release notes, and maybe to the demonstration version.
	37	+* Write an announcement e-mail to the relevant mailing lists pointing to the release notes, and maybe to the demonstration version.
38	38
39		-If you had any problem during these steps, you can do <tt>rake clobber_package</tt> to
40		-completely delete the generated packages and start the process again.
	39	+If you had any problem during these steps, you can do `rake clobber_package` to completely delete the generated packages and start the process again.
...	...
1	1	README - AntiSpam (AntiSpam Plugin)
2		-=======================================
	2	+===================================
3	3
4		-Plugin that checks comments against a spam checking service compatible
5		-with the Akismet API.
	4	+Plugin that checks comments against a spam checking service compatible with the Akismet API.
6	5
7	6
8	7	Enable Plugin
...	...	@@ -10,12 +9,12 @@ Enable Plugin
10	9
11	10	Also, you need to enable AntiSpam Plugin at your Noosfero:
12	11
13		-cd <your_noosfero_dir>
14		-./script/noosfero-plugins enable anti_spam
	12	+ cd <your_noosfero_dir>
	13	+ ./script/noosfero-plugins enable anti_spam
15	14
16	15
17	16	Activate Plugin
18		--------------
	17	+---------------
19	18
20	19	As a Noosfero administrator user, go to administrator panel:
21	20
...	...