PA OXaaS APSv2 Deployment Guide: Difference between revisions

From Open-Xchange
 
(26 intermediate revisions by 3 users not shown)
Line 1: Line 1:
= Deployment Guide for the OX as a Service APSv2 package into Odin Service Automation =
= Deployment Guide for the OX as a Service APSv2 package into Odin Service Automation =


This APS 2.0 package is only for the Open-Xchange own OXaaS platform or similar respective compatible deployments or copies of this platform. The package is designed for syndication and on-premise customers with Odin Service Automation 5.5 and higher.
This APS 2.0 package is only for the Open-Xchange own OXaaS platform or similar respective compatible deployments or copies of this platform. The package is designed for syndication and on-premise customers with Odin Service Automation 6.0.4 and higher.


This guide describes the integration for the OX as a Service APSv2 package into Odin Service Automation. This guide is intended for providers that use Odin Service Automation and want to sell Open-Xchange services to customers.
This guide describes the integration for the OX as a Service APSv2 package into Odin Service Automation. This guide is intended for providers that use Odin Service Automation and want to sell Open-Xchange services to customers.
Line 60: Line 60:
   |'''Definition'''
   |'''Definition'''
  |-
  |-
   |OpenXChange-xxxx.app.zip Package
   |Open-Xchange-xxxx.app.zip Package
   |Open-Xchange is the name of the package and xx-xx is the placeholder for a specific version of the APS
   |Open-Xchange is the name of the package and xx-xx is the placeholder for a specific version of the APS
  |-
  |-
   |Foldername
   |Foldername
   |Name of the folder where a specific file is located. In this case, “openxchange”
   |Name of the folder where a specific file is located. In this case, “open-xchange”
  |-
  |-
   |https://endpoint-ipor-dns
   |https://endpoint-ip-or-dns
   |IP or URL of the environment
   |IP or URL of the environment
  |-
  |-
Line 75: Line 75:
=== About Open-Xchange===
=== About Open-Xchange===
The standard business model of Open-Xchange consists of two major components: a platform fee and a revenue share. With the platform fee the customer pays the basic access to the hosted service or the software and it usually includes a certain amount of basic packages that are ideally distributed to a wide audience of users by bundling them into other products.
The standard business model of Open-Xchange consists of two major components: a platform fee and a revenue share. With the platform fee the customer pays the basic access to the hosted service or the software and it usually includes a certain amount of basic packages that are ideally distributed to a wide audience of users by bundling them into other products.
== Integration Prerequisites ==
Before you start integrating Open-Xchange into OSA, learn about the necessary preparations for the process.
=== Prerequisites for the OSA Platform ===
The APS Package v1.1-9 requires POA v6.0.4 or higher and OX App Suite 7.6.2 or higher.
=== Prerequisites for the Endpoint ===
{|border="2" rules="all" align="left">
  |'''Prerequisites'''
  |'''Notification code server'''
|-
  |Description
  |Specific node with Apache and PHP used to install the system script.
|-
  |Software
  |
* Apache >= 2.2.15 with mod_ssl
* PHP >= 5.3.3
* aps_php_runtime >= 2.1-292
|-
  |Platform
  |
* PBA Rest API must be enabled (to install it, follow this link: https://doc.apsstandard.org/2.1/pa/upsell/deploy/)
|-
|}
=== Preparing the Endpoint Host Server ===
Open-Xchange APS Package requires an application host server to be set up before it can be successfully imported and used in OSA. This endpoint server can be provisioned as a VPS or a VM in the same infrastructure as OSA systems. Please make sure you have OSA (POA + PBA) infrastructure set up properly before continuing. The Provider’s guide for setting up OSA can be found at http://download.pa.parallels.com/pa/6.0/doc/.
You can either choose the automated endpoint deployment by using the endpoint.sh script file or use the manual installation process by continuing reading this chapter. For more information about automated endpoint deployment, please refer to https://doc.apsstandard.org/2.1/pa/deployment/#automated-setup-based-onendpoint-sh for instructions of use and download here the script endpoint.sh: http://doc.apsstandard.org/2.1/pa/deployment/#automated-setup-based-onendpoint-
sh.
Please verify if the endpoint is compliant with the above-mentioned prerequisites.
These deployment instructions are based on the fresh installation of CentOS 6. All required packages are installed and managed by its yum package manager.
Before carrying out the steps described below, you must have:
* Server path
* Credentials: ID and password
# Install PHP interpreter via yum install PHP and Apache HTTP server via yum install httpd if your Linux distribution does not include them. Please check your installed version of PHP via:
#:[root@endpoint ~]# php -version
#:And ensure your Apache HTTP server is up and running:
#:[root@endpoint ~]# service httpd status
#:The answer should be:
#:httpd (pid 5749) is running...
#:The default document root directory for Apache HTTP Server is located at ''/var/www/html/''.
# The application host server requires the APS PHP Runtime library. Check if you have installed the appropriate version by using the following command:
#:[root@endpoint~]# rpm –qa | grep aps
#:Otherwise, it can be downloaded from ''http://doc.apsstandard.org/tools/php_lib/''.
#:If you need to copy files from different servers, we recommend using an FTP client.
#:If you have an older version installed, execute the command below:
#:[root@endpoint~]# rpm -Uvh aps-php-runtime-{version}.noarch.rpm
#:If you do not have PHP runtime installed on your server, do the following:
#:[root@endpoint~]# rpm -ivh aps-php-runtime-{version}.noarch.rpm
#:Where ''aps-php-runtime-{version}.noarch.rpm'' is the name of the PHP runtime library, and {version} is the version number you download from the above link. After the installation, the ''/usr/share/aps/php'' directory will be added to the system ''php.ini'' file automatically.
=== Open-Xchange Services Provided===
Below is the list of resources provided by Open-Xchange:
{|border="2" rules="all" align="left">
  |'''Resource Name'''
  |'''Resource Class'''
  |'''Limit'''
  |'''Auto-Provide'''
|-
  |OX Globals
  |Application Service Reference
  |1
  |No
|-
  |OX Brand
  |Application Service Reference
  |1
  |No
|-
  |OX Profile Webmail
  |Application Service Reference
  |Unlimited
  |No
|-
  |OX Profile Basic
  |Application Service Reference
  |Unlimited
  |No
|-
  |OX Profile Advanced
  |Application Service Reference
  |Unlimited
  |No
|-
  |OX Profile Pro
  |Application Service Reference
  |Unlimited
  |No
|-
  |OX Shared Domain*
  |Application Service Reference
  |Unlimited
  |No
|-
  |OX Shared Subdomain*
  |Application Service Reference
  |Unlimited
  |No
|-
  |Odin Business Automation
  |Application Service Reference
  |1
  |No
|-
  |OX Tenant
  |Application Service
  |1
  |Yes
|-
  |OX User
  |Application Service
  |Unlimited
  |No
|-
  |OX Email Address
  |Application Service
  |Unlimited
  |No
|-
  |OX Domain
  |Application Service
  |Unlimited
  |No
|-
  |OX Purchase Request
  |Application Service
  |Unlimited
  |No
|-
  |OX Group
  |Application Service
  |Unlimited
  |No
|-
  |OX Subdomain
  |Application Service
  |Unlimited
  |No
|-
  |OX Resource
  |Application Service
  |Unlimited
  |No
|-
  |OX Storage Quota
  |Application Counter (KB)
  |Unlimited
  |No
|-
|}
* You can add as many as necessary.
== Integration Workflow ==
The integration workflow looks as follows:
=== Deployment  ===
Please refer to the Deployment Guide for more detailed information. This action is performed once and consists of:
# Deploying Open-Xchange application endpoint.
# Importing Open-Xchange application package.
# Creating service instance in the Provider Control Panel.
=== PA Integration  ===
# Creating the required resource types. For further details, please refer to the Resource Creation section of this guide.
# Creating the service template. For further details, please refer to the Service Template Creation section of this guide.
== Localization List ==
Open-Xchange has been localized in the following languages for each category:
* Customer Interface: English
* PA task manager error logging: English
* Open-Xchange API error messaging: English


== Technical Overview ==
== Technical Overview ==
Line 294: Line 109:


[[Image:Odin_Architecture.png]]
[[Image:Odin_Architecture.png]]
==== Components ====
The following table shows the main actions offered by the APS through the different panels of OSA.
{|border="2" rules="all" align="left">
  |'''Components'''
  |'''Actions'''
|-
  |Odin Admin
  |
* Import APS package.
* Create an APS instance.
* Manage application settings:
** CRUD tasks to automatize report creation.
** CRUD brands.
** Edit OX App Suite branding settings.
** Download reports.
** CRUD shared domains / subdomains.
** CRUD profiles.
|-
  |Odin Customer Manager
  |
* Buy subscriptions.
* View resource usage.
* Buy more profiles (in app purchase).
* Create service users.
* Enable / Disable OX App Suite for a service user.
* Add email aliases to an existing user of OX App Suite.
* Change profile of an existing OX App Suite user.
* View mailbox and storage usage per user.
* CRUD user groups.
* CRUD resources.
* CRUD domains / subdomains.
* Configure catch all for existing domains.
* View all users’ purchase requests.
|-
  |Odin Service User
  |
* View profile features.
* Go to OX App Suite.
|-
|}


== Download ==
== Download ==
Line 348: Line 120:
Please contact Open-Xchange for further download and configuration information via info@open-xchange.com.
Please contact Open-Xchange for further download and configuration information via info@open-xchange.com.


== OSA Integration ==
== Integration Prerequisites ==


=== Configuring Services for Selling - POA ===
Before you start integrating Open-Xchange into OSA, learn about the necessary preparations for the process.


Learn about how to configure the service templates that are necessary to create Open-Xchange APS subscriptions for sale.
=== Prerequisites for the OSA Platform ===


==== Instance Configuration ====
The APS Package requires POA v6.0.4 or higher and OX App Suite 7.8.0 or higher.


===== Minimum Instance Configuration=====
PBA upsell APS must be enabled (to install it, follow this link: https://doc.apsstandard.org/2.1/pa/upsell/deploy/)
In order to configure the instance, the following minimum steps need to be observed:
# Configure the settings (please refer to the '''APP Settings''' subsection, under the Detailed Configuration section).
# Configure the reseller’s brands (please refer to the '''Brands''' subsection, under the Detailed Configuration section).
# Configure the profiles (please refer to the '''Profiles''' subsection, under the Detailed Configuration section).


=====Detailed Instance Configuration=====
=== Prerequisites for the Endpoint ===
A description follows on how to configure all the specific settings of this particular instance.


;Accessing the Instance
{|border="2" rules="all" align="left">
  |'''Prerequisites'''
  |'''Notification code server'''
|-
  |Description
  |Specific node with Apache and PHP used to install the system script.
|-
  |Software
  |
* Apache >= 2.2.15 with mod_ssl
* PHP >= 5.3.3
* aps_php_runtime >= 2.1-292
|-
|}


# In the POA Provider Control Panel, navigate to '''Services>Applications'''.
=== Preparing the Endpoint Host Server ===
# Click on the latest version of the '''Open-Xchange''' APS package.
# Go to the '''Instances''' tab.
# Click '''Open-Xchange'''.


;App Settings
Open-Xchange APS Package requires an application host server to be set up before it can be successfully imported and used in OSA. This endpoint server can be provisioned as a VPS or a VM in the same infrastructure as OSA systems. Please make sure you have OSA (POA + PBA) infrastructure set up properly before continuing. The Provider’s guide for setting up OSA can be found at http://download.pa.parallels.com/pa/6.0/doc/.


On this tab the list of possible scripts that can be configured as background tasks for this Open-XChange APS2 is displayed. These scripts are used to create the reports.
You can either choose the automated endpoint deployment by using the endpoint.sh script file or use the manual installation process by continuing reading this chapter. For more information about automated endpoint deployment, please refer to https://doc.apsstandard.org/2.1/pa/deployment/#automated-setup-based-onendpoint-sh for instructions on how to download and use the script endpoint.sh.
[[Image:aps2_1.png]]


* You can see the script name, file, next execution, period as well as their status, which can be:
Please verify if the endpoint is compliant with the above-mentioned prerequisites.


[[Image:aps2_2.png]]: enabled<br>
These deployment instructions are based on the fresh installation of CentOS 6. All required packages are installed and managed by its yum package manager.
[[Image:aps2_3.png]]: pending


* In order to create a cron, click '''Create'''. As soon as it is ready the status will change to “Enabled”, then it can also be Disabled, Edited or Deleted.
Before carrying out the steps described below, you must have:
* This tab also shows the last 10 cron executions to check their current status.
* Server path
[[Image:aps2_4.png]]
* Credentials: ID and password


* The status of the executions can be:
# Install PHP interpreter via yum install PHP and Apache HTTP server via yum install httpd if your Linux distribution does not include them. Please check your installed version of PHP via:
[[Image:aps2_2.png]]: the execution was successful.<br>
#:[root@endpoint ~]# php -version
[[Image:aps2_5.png]]: the execution is in process.<br>
#:And ensure your Apache HTTP server is up and running:
[[Image:aps2_6.png]]: an error has occurred during the execution.
#:[root@endpoint ~]# service httpd status
 
#:The answer should be:
;Brands
#:httpd (pid 5749) is running...
 
#:The default document root directory for Apache HTTP Server is located at ''/var/www/html/''.
This tab is used to assign each Open-Xchange reseller with a brand. To do so:
# The application host server requires the APS PHP Runtime library. Check if you have installed the appropriate version by using the following command:
# Click on '''Add new brand'''.
#:[root@endpoint~]# rpm –qa | grep aps
# Fill in the required fields:
#:Otherwise, it can be downloaded from ''http://doc.apsstandard.org/tools/php_lib/''.
#* Name: name of the brand.
#:If you need to copy files from different servers, we recommend using an FTP client.
#* Username: username of the brand.
#:If you have an older version installed, execute the command below:
#* Password: password or the brand.
#:[root@endpoint~]# rpm -Uvh aps-php-runtime-{version}.noarch.rpm
#* API URL: URL where the API is located.
#:If you do not have PHP runtime installed on your server, do the following:
#* SSO URL: URL of the Single Sign On.
#:[root@endpoint~]# rpm -ivh aps-php-runtime-{version}.noarch.rpm
#* APP Suite Login Page: login page of the APP Suite.
#:Where ''aps-php-runtime-{version}.noarch.rpm'' is the name of the PHP runtime library, and {version} is the version number you download from the above link. After the installation, the ''/usr/share/aps/php'' directory will be added to the system ''php.ini'' file automatically.
#* Label of service name: name that will be displayed on all buttons and tabs and refers to the service. It could be “App Suite”, but if the provider has his own service name, which is used for his brand, it can also be defined here.
#Create a new folder under ''/root/''
#* Select “Purchase request enabled” and “Catch all enabled for customers”, if appropriate. If the first option is enabled users are allowed to request customers some extra resources or services. The second one is to enable or disable the use of a catch all email in customers’ domains.
#:[root@endpoint~]# mkdir /root/Open-Xchange-[x.x-x]
# Click on '''Create''' to add the brand.
#Upload the APS package zip file on your application endpoint. This guide assumes you place it under ''/root/Open-Xchange-[x.x-x]/Open-Xchange-[x.x-x].app.zip''. If you need to copy files from different servers, we recommend using an FTP client.
# Once the brand has been created, you can view or edit the settings, branding and list of domains and subdomains. <br><br>[[Image:aps2_7.png]]
#Move to folder /root/Open-Xchange-[x.x-x]
# By clicking on '''View''', you can:  
#:[root@endpoint~]# cd /root/Open-Xchange-[x.x-x]
#* See and edit the settings previously defined. You can also download the “Last contexts report” or the “Last users report” in CSV format. <br><br>[[Image:aps2_8.png]]
#Unzip the uploaded zip Open-Xchange-[x.x-x].app.zip
#* See the brand’s settings:
#:[root@endpoint~]# unzip Open-Xchange-[x.x-x].app.zip
#** Application URL.  
#Copy the “scripts” folder to the folder where Apache is set up as Virtual Host:
#** Global settings.
#:[root@endpoint~]# cp -R /root/Open-Xchange -[x.x-x]/scripts/
#** Global application settings.
#:/var/www/html/open-xchange
#** Various theme settings that can be defined per brand. <br><br>[[Image:aps2_8.png]]
#Access ''/var/www/html/open-xchange''.
#* Add, edit or delete the reseller’s shared domains and subdomains: <br><br>[[Image:aps2_9.png]]
#Ensure that the end-point is correctly deployed.
#** Click on '''Add new domain''' or '''Add new subdomain''' to specify the domain name and login (login of an existing user in the current Open-Xchange reseller), then click on '''Save''': <br><br>[[Image:aps2_10.png]]
#:*Verify that the directory root exists and contains all project scripts.
#** You can also edit an existing domain or subdomain by clicking on '''Edit'''. <br><br>[[Image:aps2_11.png]]
#:ll -aR /var/www/html/open-xchange
 
#:*Verify that the .htaccess contains rewrite rules for all the application services
;Profiles
#:cat /var/www/html/open-xchange/.htaccess
 
#The .htaccess file must be like:
On this tab you can add, edit and delete a profile.
#:Options +FollowSymLinks +ExecCGI
[[Image:aps2_12.png]]
#:<IfModule mod_rewrite.c>
 
#:RewriteEngine On
Click on '''Add new profile''' and specify the following features, then click on '''Save'''.
#:RewriteBase /openxchange
[[Image:aps2_13.png]]
#:RewriteCond %{REQUEST_FILENAME} !-f
 
#:RewriteCond %{REQUEST_URI} !=/favicon.ico
* Name: profile name.
#:RewriteRule ^brand(|/.*)$ brand.php?q=$1 [L,QSA]
* Feature level: select the level from the drop-down list.
#:RewriteRule ^domain(|/.*)$ domain.php?q=$1 [L,QSA]
* Mail quota: mail quota provided (defined in KB).  
#:RewriteRule ^emailaddress(|/.*)$ emailaddress.php?q=$1
* Disk quota: disk quota provided (defined in KB).
#:[L,QSA]
* Feature level defines a preset of add-ons, but two additional add-ons can be enabled apart from the predefined list. These are:
#:RewriteRule ^globals(|/.*)$ globals.php?q=$1 [L,QSA]
** Documents.
#:RewriteRule ^group(|/.*)$ group.php?q=$1 [L,QSA]
** Guard.
#:RewriteRule ^profile(|/.*)$ profile.php?q=$1 [L,QSA]
 
#:RewriteRule ^purchaserequest(|/.*)$ purchaserequest.php?q=$1
==== Resource Creation====
#:[L,QSA]
 
#:RewriteRule ^resource(|/.*)$ resource.php?q=$1 [L,QSA]
# In the POA Provider Control Panel, navigate '''Services>Applications'''.
#:RewriteRule ^subdomain(|/.*)$ subdomain.php?q=$1 [L,QSA]
# Click '''Open-Xchange''' in the APS Packages tab.
#:RewriteRule ^shareddomain(|/.*)$ shareddomain.php?q=$1
# Go to the '''Resource Types''' tab.
#:[L,QSA]
 
#:RewriteRule ^sharedsubdomain(|/.*)$ sharedsubdomain.php?q=$1
===== Application Service Reference=====
#:[L,QSA]
 
#:RewriteRule ^tenant(|/.*)$ tenant.php?q=$1 [L,QSA]
;Creating a Globals Resource
#:RewriteRule ^user(|/.*)$ user.php?q=$1 [L,QSA]
# Click on Create, then on Application Service Reference.
#:RewriteRule ^cron(|/.*)$ cron.php?q=$1 [L,QSA]
# Fill in the following fields:
#:RewriteRule ^crontask(|/.*)$ crontask.php?q=$1 [L,QSA]
#* Name: enter the name of the application and the type of resource. In this case, Open-Xchange Globals.
#:RewriteRule ^api/createrequest(|/.*)?$
#* Description: this field is used to describe the type of resource. You can leave it blank or enter the information you wish. <br><br>[[Image:aps2_14.png]]
#:api.php?call=createrequest [L,QSA]
# Click Next, then select Open-Xchange Application as the APS type. <br><br>[[Image:aps2_15.png]]
#:RewriteRule ^api/getupsellresources/([a-zA-Z0-9/@/.]+)?$
# Click on the instance. <br><br>[[Image:aps2_16.png]]
#:api.php?call=getupsellresources&login=$1 [L,QSA]
# Click '''Finish'''. The resource has been created.
#:</IfModule>
 
#Set the user to Apache:
;Creating a Brand Resource
#:chown -R apache:apache /var/www/html/open-xchange
# Click on '''Create''', then on '''Application Service Reference'''.
#Check that the end-point has been installed successfully by visiting the endpoint’s URL in your browser: #:https://endpoint-ip-or-dns/openxchange/globals.
# Fill in the following fields:
#:If you get the following error, the endpoint has been deployed successfully and the process finishes here.
#* Name: enter the name of the application and the type of resource. In this case, Open-Xchange Brand.
#:{ "code": 500, "type": "Exception", "message": "APS-Instance-Id header not set." }
#* Description: this field is used to describe the type of resource. You can leave it blank or enter the information you wish.
#:If you get the following one, please see the instructions below.
# Click '''Next''', select '''Open-Xchange Brand''' as the APS type and then click on the instance.  
#:{
# Click '''Finish'''. The resource has been created.
#:"code": 404,
 
#:"type": "RuntimeException",
;Creating a Profile Basic Resource
#:"message": "Not Found: No appropriate method found for url…"
# Click on '''Create''', then on '''Application Service Reference'''.
#:}
# Fill in the following fields:
#:Set the AllowOverride All option for the folder that will be the parent of application endpoints. It is usually var/www/html in Apache. For example, in the /etc/httpd/conf/httpd.conf file, find the <Directory “var/www/html”> section and edit the following line.
#* Name: enter the name of the application and the type of resource. In this case, Open-Xchange Profile Basic.
#:AllowOverride All
#* Description: this field is used to describe the type of resource. You can leave it blank or enter the information you wish.
#Restart the Apache service with the following command: service httpd restart.
# Click '''Next''', select '''Open-Xchange Profile''' as the APS type and click on the instance.  
# Click '''Finish'''. The resource has been created.
 
;Creating a Profile Webmail Resource
# Click on '''Create''', then on '''Application Service Reference'''.
# Fill in the following fields:
#* Name: enter the name of the application and the type of resource. In this case, Open-Xchange Profile Webmail.
#* Description: this field is used to describe the type of resource. You can leave it blank or enter the information you wish.
# Click '''Next''', select '''Open-Xchange Profile''' as the APS type and then click on the instance.
# Click '''Finish'''. The resource has been created.
 
;Creating a Profile Advanced Resource
# Click on '''Create''', then on '''Application Service Reference'''.
# Fill in the following fields:
#* Name: enter the name of the application and the type of resource. In this case, Open-Xchange Profile Advanced.
#* Description: this field is used to describe the type of resource. You can leave it blank or enter the information you wish.
# Click '''Next''', select '''Open-Xchange Profile''' as the APS type and then click on the instance.
# Click '''Finish'''. The resource has been created.
 
;Creating a Profile Pro Resource
# Click on '''Create''', then on '''Application Service Reference'''.
# Fill in the following fields:
#* Name: enter the name of the application and the type of resource. In this case, Open-Xchange Profile Pro.
#* Description: this field is used to describe the type of resource. You can leave it blank or enter the information you wish.
# Click '''Next''', select '''Open-Xchange Profile''' as the APS type and then click on the instance.
# Click '''Finish''' The resource has been created.
 
;Creating a Shared Domain Resource
# Click on '''Create''', then on '''Application Service Reference'''.
# Fill in the following fields:
#* Name: enter the name of the application and the type of resource. In this case, Open-Xchange Shared Domain.
#* Description: this field is used to describe the type of resource. You can leave it blank or enter the information you wish.
# Click '''Next''', select '''Open-Xchange Shared Domain''' as the APS type and then click on the instance.
# Click '''Finish'''. The resource has been created.
'''NOTE: Please remember that you can add as many Shared Domain resources as necessary.'''
 
;Creating a Shared Subdomain Resource
# Click on '''Create''', then on '''Application Service Reference'''.
# Fill in the following fields:
#* Name: enter the name of the application and the type of resource. In this case, Open-Xchange Shared Subdomain.
#* Description: this field is used to describe the type of resource. You can leave it blank or enter the information you wish.
# Click '''Next''', select '''Open-Xchange Shared Subdomain''' as the APS type and then click on the instance.  
# Click '''Finish'''. The resource has been created.
'''NOTE: Please remember that you can add as many Shared Subdomain resources as necessary.'''
 
===== Application Service =====
 
;Creating a Tenant Resource
 
# Click on '''Create''', then on '''Application Service'''.
# Fill in the following fields:
#*Name: enter the name of the application and the type of resource. In this case, Open-Xchange Tenant.
#*Description: this field is used to describe the type of resource. You can leave it blank or enter the information you wish. <br><br>[[Image:aps2_17.png]]
# Click '''Next''', then select '''Open-Xchange Tenant''' as the APS type. <br><br>[[Image:aps2_15.png]]
# Tick the “Automatically provision service” checkbox and leave the Priority field blank <br><br>[[Image:aps2_19.png]]
# Click '''Next''', then '''Finish'''. The resource has been added. 
 
;Creating a User Resource
# Click on '''Create''', then on '''Application Service'''.
# Fill in the following fields:
#* Name: enter the name of the application and the type of resource. In this case, Open-Xchange User.
# *Description: this field is used to describe the type of resource. You can leave it blank or enter the information you wish.  
# Click '''Next''', then select''' Open-Xchange User''' as the APS type.
# Leave the “Automatically provision service” box unchecked and the Priority field blank.
# Click '''Next''', then '''Finish'''. The resource has been added.


;Creating an Email Address Resource
=== Creating the crontab task in the Endpoint Host Server===
# Click on '''Create''', then on '''Application Service'''.
This APS needs that a crontab task in order to execute periodical tasks. This steps has to be done in automatic and manual deployment.
# Fill in the following fields:
#* Name: enter the name of the application and the type of resource. In this case, Open-Xchange Email Address.
#* Description: this field is used to describe the type of resource. You can leave it blank or enter the information you wish.
# Click '''Next''', then select '''Open-Xchange Email Address''' as the APS type.
# Leave the “Automatically provision service” box unchecked and the Priority field blank.
# Click '''Next''', then '''Finish'''. The resource has been added.


;Creating a Domain Resource
*Set the crontab in order to execute periodical tasks
# Click on '''Create''', then on '''Application Service'''.
*Open the crontab
# Fill in the following fields:
#* Name: enter the name of the application and the type of resource. In this case, Open-Xchange Domain.
#* Description: this field is used to describe the type of resource. You can leave it blank or enter the information you wish.
# Click '''Next''', then select '''Open-Xchange Domain''' as the APS type.
# Leave the “Automatically provision service” box unchecked and the Priority field blank.
# Click '''Next''', then '''Finish'''. The resource has been added.


;Creating a Purchase Request Resource
[root@endpoint~]# crontab -e
# Click on '''Create''', then on '''Application Service'''.
# Fill in the following fields:
#* Name: enter the name of the application and the type of resource. In this case, Open-Xchange Purchase Request.
#* Description: this field is used to describe the type of resource. You can leave it blank or enter the information you wish.
# Click '''Next''', then select '''Open-Xchange Purchase Request''' as the APS type.
# Leave the “Automatically provision service” box unchecked and the Priority field blank.
# Click '''Next''', then '''Finish'''. The resource has been added.


;Creating a Group Resource
*Set the crontab and save
# Click on '''Create''', then on '''Application Service'''.
# Fill in the following fields:
#* Name: enter the name of the application and the type of resource. In this case, Open-Xchange Group.
#* Description: this field is used to describe the type of resource. You can leave it blank or enter the information you wish.
# Click '''Next''', then select '''Open-Xchange Group''' as the APS type.
# Leave the “Automatically provision service” box unchecked and the Priority field blank.
# Click '''Next''', then '''Finish'''. The resource has been added.


;Creating a Subdomain Resource
*/30 * * * * cd /var/www/html/open-xchange; /usr/bin/php cronjob.php
# Click on '''Create''', then on '''Application Service'''.
# Fill in the following fields:
#* Name: enter the name of the application and the type of resource. In this case, Open-Xchange Subdomain.
#* Description: this field is used to describe the type of resource. You can leave it blank or enter the information you wish.
# Click '''Next''', then select '''Open-Xchange Subdomain''' as the APS type.
# Leave the “Automatically provision service” box unchecked and the Priority field blank.
# Click '''Next''', then '''Finish'''. The resource has been added.


;Creating a Resource Resource
== Deploying the Open-Xchange APS Package==
# Click on '''Create''', then on '''Application Service'''.
# Fill in the following fields:
#* Name: enter the name of the application and the type of resource. In this case, Resource Resource.
#* Description: this field is used to describe the type of resource. You can leave it blank or enter the information you wish.
# Click '''Next''', then select '''Open-Xchange Resource''' as the APS type.
# Leave the “Automatically provision service” box unchecked and the Priority field blank.
# Click '''Next''', then '''Finish'''. The resource has been added.


===== Application Counter =====
To deploy the Open-Xchange APS package on the provisioning host, you need to prepare the host and then import your Open-Xchange APS package in OSA. Find information about how to do it in this chapter.


;Creating a Storage Quota Resource
=== Importing Open-Xchange Application ===
# Click on '''Create''', then on '''Application Counter''' (KB).
# Fill in the following fields:
#* Name: enter the name of the application and the type of resource. In this case, Open-Xchange Storage Quota.
#* Description: this field is used to describe the type of resource. You can leave it blank or enter the information you wish.
# Click '''Next''', then select '''Tenant Storage Quota''' as the APS type.
# Click '''Finish'''. The resource has been added.


==== Template Creation====
To import the Open-Xchange application to POA:


# In the POA Provider Control Panel, navigate '''Products>Service Templates'''.
#Log in as a service provider administrator.
# Click on the '''Add New Service Template''' button. <br><br>[[Image:aps2_20.png]]
#In the POA Control Panel, navigate to Services>Applications.
# Configure the service template’s general parameters:
# Click Import Package, in the APS Packages tab. [[Image:aps_package_import.jpg]]
#* Name: enter the name, for example: Open-Xchange.
#Upload the package zip file from your local workstation to the POA environment. Select local file and browse for the correct application file. In this case Open-Xchange-[x.x-x].app.zip.
#* Description: this field is used to describe the template. Leave it blank or enter the information you wish.
#Click on Submit to upload the file.
#* Tick the “Autoprovisioning” checkbox.
#Click the Refresh icon, in the upper right corner, to check that the package has been uploaded.
#* Type: set the type as “Custom”.<br><br> [[Image:aps2_21.png]]
#The package will successfully uploaded once you see the icon next to the package name. [[Image:aps_ox_package_available.jpg]]
# Click '''Next'''. The template has been created.
#Click on Open-Xchange to create a new instance.
# Select all the resources created earlier as well as Odin Business Automation, then click '''Next'''.
#Go to the Instances tab.
# Set the limits for the resource types included in the service template.
#Click Install.
#* For Globals, Brand, Tenant and Odin Business Automation uncheck the Unlimited checkbox and set the limit as 1.
#Type the Application API end-point URI: ''https://endpoint-ip-or-dns/open-xchange''
#* For the rest of resources, leave the Unlimited checkbox marked.
#Click Finish, to confirm the creation of a new instance.
# Click '''Next''', then '''Finish'''
# To activate the service template:
# Open the newly created service template (Open-Xchange).
# In the '''General''' tab, click on '''Activate'''.<br><br> [[Image:aps2_22.png]]

Latest revision as of 11:35, 17 June 2016

Deployment Guide for the OX as a Service APSv2 package into Odin Service Automation

This APS 2.0 package is only for the Open-Xchange own OXaaS platform or similar respective compatible deployments or copies of this platform. The package is designed for syndication and on-premise customers with Odin Service Automation 6.0.4 and higher.

This guide describes the integration for the OX as a Service APSv2 package into Odin Service Automation. This guide is intended for providers that use Odin Service Automation and want to sell Open-Xchange services to customers.

Terms and Abbreviations

Below is the list of concepts and abbreviations you will find in this page.

Abbreviation Definition
API Application Programming Interface
APS Application Packaging Standard, an open standard that was designed to simplify the delivery of SaaS applications in the cloud-computing industry.
HTTP Hypertext Transfer Protocol
OSA Odin Service Automation (former Parallels Automation), which includes both POA and PBA
PBA Parallels Business Automation.
POA Parallels Operations Automation.
SaaS Software as a Service.
SSO Single Sign-On.
URI Uniform Resource Identifier
URL Uniform Resource Locator
VM Virtual Machine
VPS Virtual Private Server


Conventions

Below is the list of conventions you will find in this page.

Abbreviation Definition
Open-Xchange-xxxx.app.zip Package Open-Xchange is the name of the package and xx-xx is the placeholder for a specific version of the APS
Foldername Name of the folder where a specific file is located. In this case, “open-xchange”
https://endpoint-ip-or-dns IP or URL of the environment

Business Model Overview

About Open-Xchange

The standard business model of Open-Xchange consists of two major components: a platform fee and a revenue share. With the platform fee the customer pays the basic access to the hosted service or the software and it usually includes a certain amount of basic packages that are ideally distributed to a wide audience of users by bundling them into other products.

Technical Overview

This section contains an outline of how the integration of Open-Xchange and PA is performed and the list of Open-Xchange features that are supported within the integration package.

Supported Architecture and Requirements

The Principle of OSA & APS 2

The usual way that users use Odin, in order to get OX App Suite, is as follows:

  1. Open-Xchange published an APS 2 package into the Odin catalogue/ecosystem.
  2. Odin customers, and service resellers, see the package and want to resell OX App Suite.
  3. The service resellers downloads the APS 2 package and installs it into their OSA system
  4. The OSA system will ask for the location of a running and compliant OX App Suite System (This can be OXaaS or a compliant in-house OX App Suite System)
  5. The reseller can then sell OX App Suite accounts.

Compliant OX App Suite System

There are two options to connect an OX App Suite system:

  1. Use the OXaaS service that is provided by Open-Xchange
  2. Use an on-premise installation that includes a complete OX App Suite system, a Dovecot mail system and all the related services.

Use the standard recommend components together with provided configurations for:

  • Apache
  • Mysql
  • Openldap (with a dedicated Open-Xchange schema)
  • HAproxy
  • Postfix
  • S3 compatible Objectstore (as a file/email backend)

Please refer to following high level architecture diagram and if you have any questions please contact sales@open-xchange.com

Odin Architecture.png

Download

APS package

Download the APS package from the APS catalog: http://dev.apsstandard.org/apps/2.0/Open-Xchange/Open-Xchange/Mamasu/

Open-Xchange

Please contact Open-Xchange for further download and configuration information via info@open-xchange.com.

Integration Prerequisites

Before you start integrating Open-Xchange into OSA, learn about the necessary preparations for the process.

Prerequisites for the OSA Platform

The APS Package requires POA v6.0.4 or higher and OX App Suite 7.8.0 or higher.

PBA upsell APS must be enabled (to install it, follow this link: https://doc.apsstandard.org/2.1/pa/upsell/deploy/)

Prerequisites for the Endpoint

Prerequisites Notification code server
Description Specific node with Apache and PHP used to install the system script.
Software
  • Apache >= 2.2.15 with mod_ssl
  • PHP >= 5.3.3
  • aps_php_runtime >= 2.1-292

Preparing the Endpoint Host Server

Open-Xchange APS Package requires an application host server to be set up before it can be successfully imported and used in OSA. This endpoint server can be provisioned as a VPS or a VM in the same infrastructure as OSA systems. Please make sure you have OSA (POA + PBA) infrastructure set up properly before continuing. The Provider’s guide for setting up OSA can be found at http://download.pa.parallels.com/pa/6.0/doc/.

You can either choose the automated endpoint deployment by using the endpoint.sh script file or use the manual installation process by continuing reading this chapter. For more information about automated endpoint deployment, please refer to https://doc.apsstandard.org/2.1/pa/deployment/#automated-setup-based-onendpoint-sh for instructions on how to download and use the script endpoint.sh.

Please verify if the endpoint is compliant with the above-mentioned prerequisites.

These deployment instructions are based on the fresh installation of CentOS 6. All required packages are installed and managed by its yum package manager.

Before carrying out the steps described below, you must have:

  • Server path
  • Credentials: ID and password
  1. Install PHP interpreter via yum install PHP and Apache HTTP server via yum install httpd if your Linux distribution does not include them. Please check your installed version of PHP via:
    [root@endpoint ~]# php -version
    And ensure your Apache HTTP server is up and running:
    [root@endpoint ~]# service httpd status
    The answer should be:
    httpd (pid 5749) is running...
    The default document root directory for Apache HTTP Server is located at /var/www/html/.
  2. The application host server requires the APS PHP Runtime library. Check if you have installed the appropriate version by using the following command:
    [root@endpoint~]# rpm –qa | grep aps
    Otherwise, it can be downloaded from http://doc.apsstandard.org/tools/php_lib/.
    If you need to copy files from different servers, we recommend using an FTP client.
    If you have an older version installed, execute the command below:
    [root@endpoint~]# rpm -Uvh aps-php-runtime-{version}.noarch.rpm
    If you do not have PHP runtime installed on your server, do the following:
    [root@endpoint~]# rpm -ivh aps-php-runtime-{version}.noarch.rpm
    Where aps-php-runtime-{version}.noarch.rpm is the name of the PHP runtime library, and {version} is the version number you download from the above link. After the installation, the /usr/share/aps/php directory will be added to the system php.ini file automatically.
  3. Create a new folder under /root/
    [root@endpoint~]# mkdir /root/Open-Xchange-[x.x-x]
  4. Upload the APS package zip file on your application endpoint. This guide assumes you place it under /root/Open-Xchange-[x.x-x]/Open-Xchange-[x.x-x].app.zip. If you need to copy files from different servers, we recommend using an FTP client.
  5. Move to folder /root/Open-Xchange-[x.x-x]
    [root@endpoint~]# cd /root/Open-Xchange-[x.x-x]
  6. Unzip the uploaded zip Open-Xchange-[x.x-x].app.zip
    [root@endpoint~]# unzip Open-Xchange-[x.x-x].app.zip
  7. Copy the “scripts” folder to the folder where Apache is set up as Virtual Host:
    [root@endpoint~]# cp -R /root/Open-Xchange -[x.x-x]/scripts/
    /var/www/html/open-xchange
  8. Access /var/www/html/open-xchange.
  9. Ensure that the end-point is correctly deployed.
    • Verify that the directory root exists and contains all project scripts.
    ll -aR /var/www/html/open-xchange
    • Verify that the .htaccess contains rewrite rules for all the application services
    cat /var/www/html/open-xchange/.htaccess
  10. The .htaccess file must be like:
    Options +FollowSymLinks +ExecCGI
    <IfModule mod_rewrite.c>
    RewriteEngine On
    RewriteBase /openxchange
    RewriteCond %{REQUEST_FILENAME} !-f
    RewriteCond %{REQUEST_URI} !=/favicon.ico
    RewriteRule ^brand(|/.*)$ brand.php?q=$1 [L,QSA]
    RewriteRule ^domain(|/.*)$ domain.php?q=$1 [L,QSA]
    RewriteRule ^emailaddress(|/.*)$ emailaddress.php?q=$1
    [L,QSA]
    RewriteRule ^globals(|/.*)$ globals.php?q=$1 [L,QSA]
    RewriteRule ^group(|/.*)$ group.php?q=$1 [L,QSA]
    RewriteRule ^profile(|/.*)$ profile.php?q=$1 [L,QSA]
    RewriteRule ^purchaserequest(|/.*)$ purchaserequest.php?q=$1
    [L,QSA]
    RewriteRule ^resource(|/.*)$ resource.php?q=$1 [L,QSA]
    RewriteRule ^subdomain(|/.*)$ subdomain.php?q=$1 [L,QSA]
    RewriteRule ^shareddomain(|/.*)$ shareddomain.php?q=$1
    [L,QSA]
    RewriteRule ^sharedsubdomain(|/.*)$ sharedsubdomain.php?q=$1
    [L,QSA]
    RewriteRule ^tenant(|/.*)$ tenant.php?q=$1 [L,QSA]
    RewriteRule ^user(|/.*)$ user.php?q=$1 [L,QSA]
    RewriteRule ^cron(|/.*)$ cron.php?q=$1 [L,QSA]
    RewriteRule ^crontask(|/.*)$ crontask.php?q=$1 [L,QSA]
    RewriteRule ^api/createrequest(|/.*)?$
    api.php?call=createrequest [L,QSA]
    RewriteRule ^api/getupsellresources/([a-zA-Z0-9/@/.]+)?$
    api.php?call=getupsellresources&login=$1 [L,QSA]
    </IfModule>
  11. Set the user to Apache:
    chown -R apache:apache /var/www/html/open-xchange
  12. Check that the end-point has been installed successfully by visiting the endpoint’s URL in your browser: #:https://endpoint-ip-or-dns/openxchange/globals.
    If you get the following error, the endpoint has been deployed successfully and the process finishes here.
    { "code": 500, "type": "Exception", "message": "APS-Instance-Id header not set." }
    If you get the following one, please see the instructions below.
    {
    "code": 404,
    "type": "RuntimeException",
    "message": "Not Found: No appropriate method found for url…"
    }
    Set the AllowOverride All option for the folder that will be the parent of application endpoints. It is usually var/www/html in Apache. For example, in the /etc/httpd/conf/httpd.conf file, find the <Directory “var/www/html”> section and edit the following line.
    AllowOverride All
  13. Restart the Apache service with the following command: service httpd restart.

Creating the crontab task in the Endpoint Host Server

This APS needs that a crontab task in order to execute periodical tasks. This steps has to be done in automatic and manual deployment.

  • Set the crontab in order to execute periodical tasks
  • Open the crontab
[root@endpoint~]# crontab -e
  • Set the crontab and save
*/30 * * * * cd /var/www/html/open-xchange; /usr/bin/php cronjob.php

Deploying the Open-Xchange APS Package

To deploy the Open-Xchange APS package on the provisioning host, you need to prepare the host and then import your Open-Xchange APS package in OSA. Find information about how to do it in this chapter.

Importing Open-Xchange Application

To import the Open-Xchange application to POA:

  1. Log in as a service provider administrator.
  2. In the POA Control Panel, navigate to Services>Applications.
  3. Click Import Package, in the APS Packages tab. Aps package import.jpg
  4. Upload the package zip file from your local workstation to the POA environment. Select local file and browse for the correct application file. In this case Open-Xchange-[x.x-x].app.zip.
  5. Click on Submit to upload the file.
  6. Click the Refresh icon, in the upper right corner, to check that the package has been uploaded.
  7. The package will successfully uploaded once you see the icon next to the package name. Aps ox package available.jpg
  8. Click on Open-Xchange to create a new instance.
  9. Go to the Instances tab.
  10. Click Install.
  11. Type the Application API end-point URI: https://endpoint-ip-or-dns/open-xchange
  12. Click Finish, to confirm the creation of a new instance.
Retrieved from "https://wiki.open-xchange.com/wiki/index.php?title=PA_OXaaS_APSv2_Deployment_Guide&oldid=22031"