INSTALL

= Noosfero installation 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.

Below we have the instructions for installing Noosfero dependencies and setting
up a production environment. If you have problems with the setup, please feel
free to ask questions in the development mailing list.

== Requirements

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-ruby-data libgettext-ruby1.8 libsqlite3-ruby rcov librmagick-ruby libredcloth-ruby libwill-paginate-ruby iso-codes libfeedparser-ruby libferret-ruby libdaemons-ruby thin tango-icon-theme libhpricot-ruby

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-GetText: http://www.yotabanana.com/hiki/ruby-gettext.html?ruby-gettext (at least version 1.9.0)
* Ruby-sqlite3: http://rubyforge.org/projects/sqlite-ruby
* rcov: http://eigenclass.org/hiki/rcov
* Ferret: http://ferret.davebalmain.com/trac
* 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/
* feedparser: http://packages.debian.org/sid/libfeedparser-ruby
* 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/

Note: the tango-icon-theme package is not available in Debian Lenny's main
repository, because back then it was not DFSG-free (Debian Squeeze will have it
in main). You can either add the non-free repository to your sources.list file,
or download the .deb directly and install it manually with `dpkg -i`. In this
case will need do install hicolor-icon-theme as well bacause tango-icon-theme
depends on it.  After that you can try the command line above again, but
without "tango-icon-theme".

More Informations to install the tango-icon-theme on Debian Lenny:
* http://packages.debian.org/en/lenny/all/tango-icon-theme/download

If you manage to install Noosfero successfully on other systems than Debian,
please feel free to contact the Noosfero development mailing with the
instructions for doing so, and we'll include it here.

=== Setting up a production environment

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.

As root user
============

NOTE: these instructions are for seting up a *production* environment. If you
are going to do Noosfero development, you don't need to do these steps. Stop
here and see the HACKING file instead.

Install memcached. On Debian:

# 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.

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

(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:

# sudo -u noosfero -i

or

# su - noosfero

As noosfero user
================

downloading from git
--------------------

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

downloading tarball
-------------------

Note: replace 0.27.1 below from the latest stable version.

$ wget http://noosfero.org/pub/Development/NoosferoVersion00x27x01/noosfero-0.27.1.tar.gz
$ tar -zxvf noosfero-0.27.1.tar.gz
$ ln -s noosfero-0.27.1 current
$ cd current

Copy config/ferret_server.yml.dist to config/ferret_server.yml. You will
probably not need to customize this configuration, but have a look at it.

Create the thin configuration file:

$ thin -C config/thin.yml 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.

Note: currently Noosfero only supports Rails 2.1.0, which is the version in
Debian Lenny. If you have a Rails version newer than that, Noosfero will
probably not work. You can install Rails 2.1.0 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.1.0.orig.tar.gz
$ tar xzf rails_2.1.0.orig.tar.gz
$ ln -s rails-2.1.0 rails

As root user
============

Setup Noosfero log and tmp directories:

# 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.

# 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, but
Debian start postgresql on port 5433, then is needed to change postgresql to
start on port 5432 in /etc/postgresql/8.3/main/postgresql.conf file.

Restart postgresql:

# invoke-rc.d postgresql-8.3 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.

If you know mail systems well, you just need to make sure thet the local MTA,
listening on localhost:25, is able to deliver e-mails to the internet. Any mail
server will do it.

If you are not a mail specialist, 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

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:

  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:

  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.

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

As noosfero user
================

Now create the databases:

$ 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.

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

Now, to test the database access, you can fire the Rails database console:

$ ./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.

Create the database structure:

$ RAILS_ENV=production rake db:schema:load

Compile the translations:

$ RAILS_ENV=production rake noosfero:translations:compile

Now we have to 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)'

(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:

$ 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)"

(replace "adminuser", "admin@example.com", "admin" with the login, email
and password of your environment admin)

To start the Noosfero application servers:

$ ./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.

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.

First, install this version of the gem.
Others versions may not be compatible with Noosfero:

# 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:

  production:
    exception_recipients: [admin@example.com, you@example.com]

==================
Apache instalation
==================

# apt-get install apache2

Apache configuration
--------------------

First you have to enable the following some apache modules:

  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:

# 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>

    RewriteEngine On

    # Rewrite index to check for static index.html
    RewriteRule ^/$ /index.html [QSA]

    # Rewrite to check for Rails cached page
    RewriteRule ^([^.]+)$ $1.html [QSA]

    RewriteCond %{DOCUMENT_ROOT}/%{REQUEST_FILENAME} !-f
    RewriteRule ^.*$ balancer://noosfero%{REQUEST_URI} [P,QSA,L]

    ErrorDocument 503 /503.html

    ErrorLog /var/log/apache2/noosfero.log
    LogLevel warn
    CustomLog /var/log/apache2/noosfero.access.log combined

    Include /var/lib/noosfero/current/etc/noosfero/apache/cache.conf

  </VirtualHost>

  <Proxy balancer://noosfero>
    BalancerMember http://127.0.0.1:3000
    BalancerMember http://127.0.0.1:3001
    Order Allow,Deny
    Allow from All
  </Proxy>

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

============
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

Now to start Noosfero, you do as root:

# invoke-rc.d noosfero start

To stop Noosfero:

# invoke-rc.d noosfero start

To restart Noosfero:

# 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).

=============
Rotating logs
=============

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

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:

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

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 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