Software Público Brasileiro

= 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-ruby1.8 libsqlite3-ruby rcov librmagick-ruby libredcloth-ruby libwill-paginate-ruby iso-codes libfeedparser-ruby libferret-ruby libdaemons-ruby mongrel mongrel-cluster 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.

* 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/
* Mongrel: http://mongrel.rubyforge.org/
* tango-icon-theme: http://tango.freedesktop.org/Tango_Icon_Library

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

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

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:

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

# sudo adduser --system --group noosfero --shell /bin/sh --home /var/lib/noosfero 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

# sudo su - noosfero

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

Enter the directory where you unpacked noosfero (or do it now and enter the
directory). Here we are cloning the noosfero repository from git, but you can
do it with a tarball as well.

$ git clone git://git.colivre.coop.br/noosfero.git current
$ cd current
$ git checkout -b stable origin/stable

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 mongrel configuration file:

$ mongrel_rails cluster::configure

Edit config/mongrel_cluster.yml to suit your needs. Make sure your apache
configuration matches the mongrel cluster configuration, specially in respect
to the ports and numbers of mongrel 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
# sudo 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'
Shall the new role be a superuser? (y/n) n
Shall the new role be allowed to create databases? (y/n) y
Shall the new role be allowed to create more new roles? (y/n) n

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

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)

Compile the translations:

$ RAILS_ENV=production rake noosfero:translations:compile

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.

====================
Apache configuration
====================

Firts 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 mongrel 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).

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