INSTALL.md
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.
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.md` instead.
If you have problems with the setup, please feel free to ask questions in the development mailing list.
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.
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.
# apt-get install gcc g++ make ruby ruby-dev libxml2 zlib1g-dev libpq-dev libmagickwand-dev
# gem install bundler
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.
As root user
============
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
================
Here we are cloning the noosfero repository from git. Note: you may need to install git before.
$ git clone https://gitlab.com/noosfero/noosfero.git current
$ cd current
$ git checkout -b stable origin/stable
After cloning the repository, go ahead and install the production dependencies with bundler.
$ bundle --without cucumber development test
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. Pay special attention to the default collation defined on your setup by the environment variable LC_COLLATE because it might interfere in some sorting operations on your database. For more information checkout `man locale`.
# apt-get install postgresql
# 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.
Restart postgresql:
# systemctl restart postgresql
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
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 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)'
(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, :activated_at => Time.new)"
(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
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
Configuration - noosfero at /
-----------------------------
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
Configuration - noosfero at a /subdirectory
-------------------------------------------
This section describes how to configure noosfero at a subdirectory, what is
specially useful when you want Noosfero to share a domain name with other
applications. For example you can host noosfero at yourdomain.com/social, a
webmail application at yourdomain.com/webmail, and have a static HTML website
at yourdomain.com/.
**NOTE:** Some plugins might not work well with this setting. Before deploying
this setting, make sure you test that everything you need works properly with
it.
The configuration is similar to the main configuration instructions, except for
the following points. In the description below, replace '/subdirectory' with
the actual subdirectory you want.
1) add a `prefix: /subdirectory` line to your thin configuration file (thin.yml).
1.1) remember to restart the noosfero application server whenever you make
changes to that configuration file.
# service noosfero restart
2) add a line saying `export RAILS_RELATIVE_URL_ROOT=/subdirectory` to
/etc/default/noosfero (you can create it with just this line if it does not
exist already).
3) You should add the following apache configuration to an existing virtual
host (plus the `<Proxy balancer://noosfero>` section as displayed above):
```
Alias /subdirectory /path/to/noosfero/public
<Directory "/path/to/noosfero/public">
Options FollowSymLinks
AllowOverride None
Order Allow,Deny
Allow from all
Include /path/to/noosfero/etc/noosfero/apache/cache.conf
RewriteEngine On
RewriteBase /subdirectory
# Rewrite index to check for static index.html
RewriteRule ^$ index.html [QSA]
# Rewrite to check for Rails cached page
RewriteRule ^([^.]+)$ $1.html [QSA]
RewriteCond %{REQUEST_FILENAME} !-f
RewriteRule ^(.*)$ http://localhost:3000%{REQUEST_URI} [P,QSA,L]
</Directory>
```
3.1) remember to reload the apache server whenever any apache configuration
file changes.
# sudo service apache2 reload
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]
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