Multi-Tenancy

From AlfrescoWiki

Important: This document details the new multi-tenant (MT) features for Alfresco ECM. These features are currently available for testing and evaluation. As always, any and all feedback is welcome via the forums.

Contents 1 Background 2 What is Alfresco Multi-tenancy? 3 Features 4 Enabling Multi-tenancy 5 Managing Tenants 5.1 Show Tenant(s) 5.2 Create Tenant 5.3 Delete Tenant (only available in HEAD) 5.4 Enable Tenant 5.5 Disable Tenant 5.6 Export/Import 5.6.1 Export/Import of a Space 5.6.2 Export/Import of a Tenant (only available in HEAD) 5.7 Tenant Console Help (Example) 6 Delegated Administration 7 Tenant Customisation 8 Tenant-Aware Interfaces 9 Tenant Content Routing 10 Backup and Restore 10.1 Backup 10.2 Restore 11 Implementation 12 Clustering 13 Modules (only available in HEAD) 14 Not Implemented

[edit] 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 is also possible to run multiple instances of Alfresco on the same server by configuring separate database schemas, separate content stores, separate (non-conflicting) ports, etc. However, this adds additional complexity in terms of configuration and upgrades.

[edit] What is Alfresco Multi-tenancy?

The new 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.

[edit] Features

The new features include:

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

[edit] Enabling Multi-tenancy

You can configure a multi-tenant environment by downloading Alfresco, renaming the three sample MT extension files and restarting Alfresco.

1. Download Alfresco

To receive the most up-to-date HEAD changes, please [download the latest nightly 2.9.0C_dev build] and take a note of the file date. Alternatively, you can [download the Alfresco 2.9 Labs release]. We do not recommend using Alfresco 2.9B (build 683) due to a known issue when creating and displaying tenant users.

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

3. Restart Alfresco

[edit] Managing Tenants

The super 'admin' (default Alfresco 'admin' user) has access to the default environment. This admin can be considered a super tenant). 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

[edit] 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>

[edit] Create Tenant

To create a tenant, type:

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

[edit] Delete Tenant (only available in HEAD)

To delete a tenant, type:

delete <tenant domain> 

This is a Work in Progress.

[edit] Enable Tenant

To enable a tenant and allow tenant logins, type:

enable <tenant domain>

[edit] Disable Tenant

To disable a tenant and prevent tenant logins, type:

disable <tenant domain> 

[edit] Export/Import

[edit] Export/Import of a Space

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

[edit] Export/Import of a Tenant (only available in HEAD)

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

Work in Progress: 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.

[edit] 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.

ok> quit | exit

    Quit this console.


##
##  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> delete <tenant domain>

    BETA - Delete tenant. 
	
    Note: This currently requires a server restart to clear the index threads. Also
    tenant index directories should be deleted manually.
	
	Example:   delete 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
##

[edit] 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.

[edit] 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.

[edit] 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 Web Client
• WebDAV
• FTP
• Web Scripts (only available in HEAD)

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')
• for Web Scripts, authentication will always be required (even if a script has no required authentication)
• CIFS is not currently supported

[edit] 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.

[edit] 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:

[edit] 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.

[edit] 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.

[edit] 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. This also means that indexes are partitioned, since Alfresco maintains an index per store.

All ECM-related services are partitioned including node services, security services, workflow services, search services, dictionary services etc.

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

The logging has also been updated to enable NDC (nested diagnostic context). For a ST environment, the log output will now show the username context. For a MT environment, the log output will also show the tenant context.

[edit] Clustering

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

Note: If you wish to support a large number of tenants (eg. > 99) in a clustered environment, then you should review and increase the sample clustered cache sizes (see ehcache-custom-cluster.xml.sample.cluster).

[edit] Modules (only available in HEAD)

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.

[edit] Not Implemented

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

• CIFS
• WCM
• Portlets