INSTALL.multitenancy

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

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.

== Separated data

The items below are separated for each hosted environment:

* Uploaded files
* Database
* Ferret index
* ActiveRecord#cache_key
* Feed updater
* Delayed Job Workers

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

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.

You must also tell the application which is the default environment.

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:

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

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

== Preparing the database

Now create the environments:

$ RAILS_ENV=production rake multitenancy:create

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

Then run the migrations for the hosting environment, and it will
run for each of its hosted environments:

RAILS_ENV=production rake db:migrate

== Start Noosfero

Run Noosfero init file as root:

# invoke-rc.d noosfero start

== Ferret

It's necessary to run only one instance of ferret_server. Don't worry
about this, Noosfero initializer had already done this for you.

== Feed updater & Delayed job

Just for your information, a daemon of feed-updater and delayed_job
must be running for each environment. Noosfero initializer do this,
relax.

== Uploaded files

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.

== Adding multitenancy support to an existing Noosfero environment

If you already have a Noosfero environment, you can turn it multitenant
by following the steps below in addition to the previous steps:

1. Reindex your database

Rebuild the Ferret index by running the following task just
for your hosting environment, do this as noosfero user:

$ RAILS_ENV=production rake multitenancy:reindex

2. Move the uploaded files to the right place

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.

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