#Enabling Multi-Tenancy

The process of enabling multi-tenancy requires a small amount of prep work before changing the configuration of your PencilBlue installation.

##Behaviors of Multi-Tenancy ###Sites A site in Multi-Tenancy behaves in a similar manner as previous, single-tenant versions of PencilBlue. Each site is defined with a name and a hostname(www.example.com). Sites will be in a state of active or inactive. If a site is inactive, all front-end content will result in a 404 not found response however, the site's admin dashboard will still be accessible.

###Global Namespace The Global namespace of a multi-tenant PencilBlue system serves as an "admin dashboard only" site that is used to setup new PencilBlue installations with multisite enabled as well as govern users (Administrators and Managing Editors), individual sites, plugins, and system wide settings.

###Plugins and Themes Plugins are installed on a site-by-site basis. Plugins will behave the same way as in single tenant mode within the scope of a site. The global namespace will have plugins available as well. Any plugin installed in the global namespace is available for use to all sites without that particular plugin being installed on an individual site.

Example (S3 plugin): The S3 plugin is used for storing and retrieving all media files via Amazon S3. It is used by the media service in PencilBlue by setting a config variable called mediaProvider that is visible system wide. S3 should be installed in the global namespace so that when the media service is called, it is using predefined settings set in the global namespace to manage media files.

If a site requires different plugin settings in a plugin that is installed to the global namespace, an option to override that plugin within a particular site is provided.

The Active theme and Site Logo are also applied on a site-by-site basis.

###Users The same types of users are still available with their same permissions in multi-tenancy however, we have divided them into two groups.

1. Administrators and Managing Editors belong to the global namespace and have access to all individual sites.
2. All other Users (Editors, Writers, Readers) belong to an individual site and do not have access to other sites on the system.

###Content This includes all navigation, topics, pages, articles, media, comments, and custom objects. The global namespace does not have any content associated with it. Content belongs to an individual site in the same manner as previous single tenant versions of PB.

##How To Enable Multi-Tenancy The process of setting up multi-tenancy should be a simple process whether you are setting up a new installation or converting an existing one.

###Define a Hostname for Your Global Namespace Before you change your config to enable multi-tenancy you will need to setup a hostname (a domain or subdomain. Example: "http://global.example.com") that points to your global site. The default is "http://global.localhost:8080" (You can use Google Chrome without modifying your hosts file if you intend to use this hostname in your local development environment)

###Your Config At the bottom of the example config.js file below, you will find the multisite object that contains an enabled boolean flag and a field called globalRoot. Set enabled to true and globalRoot to the hostname that you defined in the previous step. Place your config.js file in the top directory of your application space and start your application server (assuming that your mongo and redis(not using fakeredis) servers are already running).

NOTE: If you are converting an existing single-tenant installation to use multi-tenancy, your data will be converted automatically in the following manner when you start your application server:

1. A new site will be automatically created using a name with the value of siteName from your config and a hostname with the value of siteRoot from your config.
2. All of your Content Items (navigation, topics, pages, articles, media, comments, and custom objects), plugins, and users who are not administrators and managing editors will be assoicated with the newly created site.

module.exports = {
    "siteName": "My PencilBlue Site",
    "siteRoot": "http://loalhost:8080",
    "sitePort": 8080,
    "logging": {
        "level": "info"
    },
    "db": {
        "type":"mongo",
        "servers": [
          "127.0.0.1:27017"
        ],
        "name": "pencilblue",
        "writeConcern": 1
    },
    "cache": {
        "fake": true,
        "host": "localhost",
        "port": 6379
    },
    "settings": {
        "use_memory": false,
        "use_cache": false
    },
    "templates": {
        "use_memory": true,
        "use_cache": false
    },
    "plugins": {
        "caching": {
            "use_memory": false,
            "use_cache": false
        }
    },
    "registry": {
        "type": "mongo"
    },
    "session": {
        "storage": "mongo"
    },
    "media": {
        "provider": "mongo",
        "max_upload_size": 6 * 1024 * 1024
    },
    "cluster": {
        "workers": 1,
        "self_managed": true
    },
    multisite: {
        enabled: true,
        globalRoot: 'http://global.localhost:8080'
    }

##Setup Process NOTE: If you are converting an existing installation skip to step 2.

1. If you are creating a new installation of Pencilblue, visit your "globalRoot" hostname to view the /setup page. Fill out the form provided then proceed to the next step.

2. Vist your "globalRoot" hostname to login to your admin dashboard.

3. After logging in, click on the "Manage Sites" link on the side nav. Here you will be given a list of all sites created on your system. You should see your first site created automatically in the Inactive Sites list. Click "Activate" to activate your site.

Your site should now be visible. Visit your site's hostname to see it live.

##The Admin Dashboard Some general things to note when using the admin dashboard

1. Whatever hostname you are logged into indicates the site you are editing.
2. The Content section is not shown on the Admin dashboard for the global site because global does not have any content associated with it.

###Manage Sites Page

1. The Manage Sites page provides a list of all sites created on your system divided into two lists, one with active sites, another with inactive sites.
2. The Activate/Deactivate Buttons contain a dropdown of links to "Edit" and "Delete" a site (Delete is available on inactive sites only.) When editing a site you can edit the hostname and/or name of the site. Hostname can only be edited if the site is inactive (The field is locked for active sites).
3. If you click on the "Site Name" link of a particular site, you will be automatically authenticated and directed to the admin dashboard of the site you click. NOTE: if you go directly to the site's hostname without clicking on it in the manage sites page, you will be prompted to login with your credentials.

###Plugins and Themes Pages

1. If you are logged into the global site, all plugins that are installed are also inherently installed on all sites with the plugin settings set in the global site.
2. For an individual site, plugins are installed only on that particular site and its settings are not shared with other sites.
3. For an individual site, plugins that are installed in the global site will be listed at the bottom of the page with a button labeled "Override". This button installs the plugin to the individual site so that it can use a set of setting values different from all other sites including the global site.
4. Themes and logos are set on a site by site basis. By default, the PencilBlue theme is applied for sites that do not have one chosen.
5. If a logo is not set on an individual site, the logo uploaded to the global site is used.

###Settings Section

1. Site settings is available for view on all sites, however, the Apply Settings button is only enabled for the global site and disabled for individual sites.
2. The content and email pages under settings apply to the individual site that you are logged into.
3. The Libraries page used to switch web components between CDN and Bower is only accessible on the global site.