Multi-Tenancy

[resplin]

Obsolete Pages{{Obsolete}}

The official documentation is at: http://docs.alfresco.com

Multi-tenancy3.13.23.33.4SaaS
Important: This document details the multi-tenant (MT) features for Alfresco ECM. These features are currently available both in the latest Enterprise and Community releases. As always, any and all feedback is welcome via Alfresco Support and/or the community forums.

Table of Contents

• 1 Background


• 2 What is Alfresco Multi-tenancy?


• 3 Features


• 4 Download Alfresco


• 5 Enabling Multi-tenancy
  
  
  
  • 5.1 Enabling MT on latest releases (HEAD / 4.0.2 or later)
  
  
  • 5.2 Enabling MT on earlier releases (4.0.d / 4.0.1 or earlier)
  
  


• 6 Upgrading an existing Multi-tenant environment
  
  
  
  • 6.1 Upgrading MT to latest releases (HEAD / 4.0.2 or later)
  
  
  • 6.2 Upgrading MT to earlier releases (4.0.d / 4.0.1 or earlier)
  
  


• 7 Managing Tenants
  
  
  
  • 7.1 Show Tenant(s)
  
  
  • 7.2 Create Tenant
  
  
  • 7.3 Enable Tenant
  
  
  • 7.4 Disable Tenant
  
  
  • 7.5 Export/Import
    
    
    
    • 7.5.1 Export/Import of a Space
    
    
    • 7.5.2 Export/Import of a Tenant
    
    
  
  
  • 7.6 Tenant Console Help (Example)
  
  


• 8 Delegated Administration


• 9 Tenant Customisation


• 10 Tenant-Aware Interfaces


• 11 Tenant Content Routing


• 12 Backup and Restore
  
  
  
  • 12.1 Backup
  
  
  • 12.2 Restore
  
  


• 13 Implementation
  
  
  
  • 13.1 Clustering
  
  
  • 13.2 Cache size
  
  
  • 13.3 Modules
  
  


• 14 Authentication


• 15 Not Implemented

Background

By default, Alfresco supports a single-instance single-tenant (ST) environment where each tenant (such as customer, company, or organisation) will run a single instance that is installed on one server or across a cluster of servers.

Theoretically, it may also be possible to run multiple instances of Alfresco on the same development server by configuring separate database schemas (with the DB on a separate server), separate content stores, separate (non-conflicting) ports, etc. However, this adds additional complexity in terms of configuration and upgrades, and some functionality may not work independently for both instances. Hence this is not recommended or supported in a production environment.

What is Alfresco Multi-tenancy?

The Multi-tenancy (MT) features enable Alfresco ECM to be configured as a true single-instance multi-tenant environment. This enables multiple independent tenants to be hosted on a single instance, which can be installed either on a single server or across a cluster of servers. The Alfresco instance is logically partitioned such that it will appear to each tenant that they are accessing a completely separate instance of Alfresco.

Features

The features include:

• Enabling MT
  
• Managing tenants
  
• Delegated administration
  
• Tenant customisation
  
• Tenant-aware interfaces
  
• Tenant content routing
  

Download Alfresco

We recommend that you download the latest Alfresco Enterprise release, available from Alfresco Support.

Alternatively, you can download the latest Alfresco Community release.

Enabling Multi-tenancy

Enabling MT on latest releases (HEAD / 4.0.2 or later)

In the latest Alfresco Community (HEAD) or Alfresco Enterprise (4.0.2 or later) the multi-tenancy feature is pre-configured out-of-the-box, although it is not enabled by default. It will be auto-enabled if and when you create your first tenant.

Enabling MT on earlier releases (4.0.d / 4.0.1 or earlier)

If you wish to use Alfresco multi-tenancy with earlier releases of Alfresco Community (4.0.d or earlier) or Alfresco Enterprise (4.0.1 or earlier) then it is necessary to configure a multi-tenant environment by download, copying and renaming the three sample MT extension files and then restarting Alfresco.

1. Rename the following three sample MT extension files:

• alfresco/extension/mt/mt-context.xml.sample -> alfresco/extension/mt/mt-context.xml
  
• alfresco/extension/mt/mt-admin-context.xml.sample -> alfresco/extension/mt/mt-admin-context.xml
  
• alfresco/extension/mt/mt-contentstore-context.xml.sample -> alfresco/extension/mt/mt-contentstore-context.xml
  

Important All three files must be renamed to enable MT. These can be found under .../tomcat/shared/classes/... (if you are using Tomcat by default).

2. Restart Alfresco

Upgrading an existing Multi-tenant environment

To upgrade an existing MT environment, please refer to and follow the general upgrade process.

Upgrading MT to latest releases (HEAD / 4.0.2 or later)

If upgrading to the latest Alfresco Community (HEAD) or Alfresco Enterprise (4.0.2 or higher) you *must* first delete your existing MT sample extension files. It is also recommended that you backup your existing copies first. For example:

1. Backup the following three existing MT extension files:

• alfresco/extension/mt/mt-context.xml -> alfresco/extension/mt/mt-context.xml.backup
  
• alfresco/extension/mt/mt-admin-context.xml -> alfresco/extension/mt/mt-admin-context.xml.backup
  
• alfresco/extension/mt/mt-contentstore-context.xml -> alfresco/extension/mt/mt-contentstore-context.xml.backup
  

2. Either move or rename the existing MT extension directory:

• mv alfresco/extension/mt -> alfresco/extension/mt_backup_can_delete_later
  

Upgrading MT to earlier releases (4.0.d / 4.0.1 or earlier)

You must replace your existing MT sample extension files with the latest copies. It is also recommended that you backup your existing copies first. For example:

1. Backup the following three existing MT extension files:

• alfresco/extension/mt/mt-context.xml -> alfresco/extension/mt/mt-context.xml.backup
  
• alfresco/extension/mt/mt-admin-context.xml -> alfresco/extension/mt/mt-admin-context.xml.backup
  
• alfresco/extension/mt/mt-contentstore-context.xml -> alfresco/extension/mt/mt-contentstore-context.xml.backup
  

2. Replace the files with the latest MT sample extension files (available from the install bundle)

• alfresco/extension/mt/mt-context.xml.sample -> alfresco/extension/mt/mt-context.xml
  
• alfresco/extension/mt/mt-admin-context.xml.sample -> alfresco/extension/mt/mt-admin-context.xml
  
• alfresco/extension/mt/mt-contentstore-context.xml.sample -> alfresco/extension/mt/mt-contentstore-context.xml
  

Important All three files must be renamed to enable MT. If you have downloaded the tomcat bundle, these can be found under .../tomcat/shared/classes/...

3. Restart Alfresco

Managing Tenants

The super 'admin' (default Alfresco 'admin' user) has access to the default environment. This admin can be considered as super-admin. Tenants can be administered by the super 'admin' using the Tenant Admin Console.

Log in as the super 'admin' user and access:

http://localhost:8080/alfresco/faces/jsp/admin/tenantadmin-console.jsp

Show Tenant(s)

To list all tenants and show their details, type:

show tenants

To show details for a single tenant, type:

show tenant <tenant domain>

Create Tenant

To create a tenant, type:

create <tenant domain> <tenant admin password> [<root contentstore dir>]

Enable Tenant

To enable a tenant and allow tenant logins, type:

enable <tenant domain>

Disable Tenant

To disable a tenant and prevent tenant logins, type:

disable <tenant domain> 

Export/Import

Export/Import of a Space

A tenant admin can use the Web Client Admin UI to export/import spaces.

Export/Import of a Tenant

The existing 'repository export' feature can be used to export a tenant.

Note: In general, 'repository export' does not apply to certain areas, such as in-flight workflows. Also, the 'repository import' must be into the same version of Alfresco (from which the export was performed).

A tenant can be exported by the super admin using the 'export' command from the Tenant console. To export a tenant to a set of repository export files, the super admin should type:

export <tenant domain> <destination directory>

Alternatively, a tenant admin can also export the tenant using the Web Client Admin UI.

A tenant can be imported by the super admin using the 'import' command from the Tenant console. To import a tenant from an existing set of repository export files, the super admin should type:

import <tenant domain> <source directory> [<root contentstore dir>]

Note: If an existing tenant needs to be re-imported, the tenant must be deleted first. Currently, in order to cleanly delete a tenant, the server must be restarted to clear the index threads. The tenant-specific index directories and tenant-specific content directories should also be manually deleted before starting the import.

Tenant Console Help (Example)

For more details on each command, refer to the Tenant Console help. Here's a snapshot:

##
##  Meta commands
##

ok> help

    List this help.

ok> r

    Repeat last command.


##
##  Tenant Commands - for administering tenants
##


ok> show tenants

    List all tenants and show their details.
    
ok> show tenant <tenant domain>

    Show tenant details - status (ie. whether enabled or disabled) and root contentstore directory.

    Example:   show tenant yyy.zzz.com

ok> create <tenant domain> <tenant admin password> [<root contentstore dir>]

    Create empty tenant. By default the tenant will be enabled. It will have an admin
    user called 'admin@<tenant domain>' with supplied admin password. All users
    that the admin creates, will login using '<username>@<tenant domain>'. 
    The root of the contentstore directory can be optionally specified, otherwise 
    it will default to the repository default root contentstore (as specified by 
    the dir.contentstore property). The default workflows will also be bootstrapped.
    
    Examples:  create zzz.com l3tm31n /usr/tenantstores/zzz
               create yyy.zzz.com g00dby3 /usr/tenantstores/yyy.zzz
               create myorg h3ll0

ok> changeAdminPassword <tenant domain> <tenant admin password>

    Useful if the tenant's admin (admin@<tenant domain>) has forgotten their password.
    
    Example:   changeAdminPassword yyy.zzz.com n3wpassw0rd

ok> enable <tenant domain>

    Enable tenant so that is active and available for new logins
    
    Example:   enable yyy.zzz.com

ok> disable <tenant domain>

    Disable tenant so that is inactive. Existing logins will fail on next usage.
    
    Example:   enable yyy.zzz.com
    
ok> export <tenant domain> <destination directory>

    Export tenant to given destination directory. Export filenames will be suffixed with '<tenant domain>_'.
    
    Example:   export yyy.zzz.com /usr/exportdir
    
ok> import <tenant domain> <source directory> [<root contentstore dir>]

    BETA - create tenant by importing the tenant files from the given source directory. The import filenames must
    be suffixed with '<tenant domain>_'.
 
    Note: If importing into a previously deleted tenant then the server must be stopped after the delete
    (and tenant indexes manually deleted) before restarting and performing the import.
 
    Example:   import yyy.zzz.com /usr/exportdir /usr/tenantstores/yyy.zzz

##
##  end
##

Delegated Administration

Once a tenant is created and enabled, then the tenant admin can log in to the Alfresco Web Client and access the Administration Console within the context of their tenant domain. If for example, a tenant/organisation called 'acme' is created, the tenant admin can log in as 'admin@acme' and create users such as 'alice@acme', 'bob@acme', 'eve@acme'.

The admin features currently available to the tenant admin include:

• Manage system users (including user Usages and Quotas)
  
• Manage user groups
  
• Category management
  
• Import
  
• Export (*)
  
• System information
  
• Node browser
  

Note (*) - a 'Complete Repository' export will be within the context of the tenant (or non-tenant) admin.

Tenant Customisation

The MT features also depend on the the new Dynamic Models features. This provides tenants the ability to customize their Alfresco environment, including models, workflows and web client UI.

Tenant-Aware Interfaces

The client-facing interfaces and APIs remain unchanged and are accessed within the context of the authenticated user's tenant domain. This includes:

• Alfresco Explorer (JSF-based web client)
  
• Alfresco Share (since 3.2)
  
• WebDAV
  
• FTP
  
• Web Scripts
  
• CMIS (since 3.2)
  

Users will authenticate using their fully-qualified userid (such as 'alice@acme').

Notes:

• tenant 'guest' authentication is allowed, but must be within the context of a tenant (such as 'guest@acme')
  
• tenant-specific Web Scripts held in the repository will always require authentication (ie. web script description document requires <authentication> setting which should not be 'none')
  
• CIFS is not currently supported
  

Tenant Content Routing

The super 'admin' will typically create tenants, such that the physical content for each tenant is stored on a separate root directory (possibly a separate mounted drive). This also allows accurate physical disk usage to be derived by measuring the disk used at the root location.

If no root directory is supplied when creating the tenant, the default root directory is used to store content for multiple tenants (in addition to any 'default' content). In this case, the content will be intermingled which may not be desirable.

Backup and Restore

Since all tenants share the same database schema, the steps for a cold backup and restore are similar to the simple backup process. The steps also must take the use of tenant-based Content Routing (if applicable)into account. For example:

Backup

1. Stop the application server (ensures no one can make changes while backing up or restoring.
   
2. Export the database to Alfresco dir.root.
   
3. If dir.root has enough space, copy each of the Tenant Root directories under dir.root/<tenantid>(or back them up separately).
   
4. Back up the entire Alfresco dir.root.
   
5. Start the application server.
   

Restore

1. Stop the application server.
   
2. Copy the existing dir.root to a temp location.
   
3. Copy each of the existing Tenant Root directories to a temp location.
   
4. Restore the dir.root.
   
5. Copy each dir.root/<tenantid> to their respective Tenant Root directories.
   
6. Import the database from dir.root.
   
7. Start the application server.
   

Implementation

To implement MT, the Alfresco ECM has been logically partitioned such that each tenant has access to their own set of tenant-specific stores. These stores are typically routed to their own physical root directory. Also, if using Lucene (Alfresco 3.4.x or Alfresco 4.0.x configured for 'lucene' search subsystem) then the Lucene index files are partitioned, since Alfresco maintains a Lucene index per store.

All ECM-related services are partitioned including node services, security services, workflow services, search/index services, dictionary services etc. Also, in order to support MT Alfresco Share, additional partitioned services include site services, activity services, invite services, avm services etc.

The meta-data is logically partitioned within the DB schema.

Clustering

The MT features have been designed and implemented to work in a clustered configuration.

Cache size

If you wish to support a large number of tenants (eg. > 99) then you will need to review and increase the cache size for all of the tenant caches, that are by default configured to 100 (including the default domain). Please refer to:

• cache-context.xml
  
• ehcache-custom-cluster.xml.sample.cluster
  

Tenant-based caches currently include:

• webScriptsRegistryCache (RepositoryContainer)
  
• prefixesCache (NamespaceDAOImpl)
  
• compiledModelsCache (DictionaryDAOImpl)
  
• messagesCache (MessageServiceImpl)
  
• loadedResourceBundlesCache (MessageServiceImpl)
  
• resourceBundleBaseNamesCache (MessageServiceImpl)
  

Modules

Alfresco supports the ability to pre-package AMPs (Alfresco Module Packages) into the Alfresco WAR which will be installed into the default domain on startup. In a multi-tenant environment, the module will also be installed into each tenant domain when the tenant is created or imported.
Note: As of Alfresco 4.2d, the functionality of a AMP may still apply to tenants depending on the implementation, but ModuleComponents will not be installed into each tenant domain. See ALF-19207

Authentication

Currently, the only authentication method supported is 'alfresco'.

Not Implemented

The following are not supported/implemented/tested in a multi-tenant enterprise environment.

• CIFS
  
• WCM
  
• RM
  
• Portlets
  
• Delete Tenant (partial - pending ALF-4600)
  
• LDAP, NTLM and authentication methods other than 'alfresco'
  
• Inbound Email
  
• Content Replication
  
• IMAP
  
• SPP / VTI (SharePoint Protocol)
  
• reloadable Share config (if using dynamic models)
  
• GoogleDocs integration
  
• Applying ModuleComponent to individual tenants (as of 4.2d - pending ALF-19207)
  

If you're interested in any of these features, please let us know the details and comment/vote for the related JIRAs.