Andreas.schluens: add arch images

2015-10-02T10:59:55Z

add arch images

← Older revision		Revision as of 10:59, 2 October 2015
Line 13:		Line 13:

	=== System Design ===		=== System Design ===
	~~<br/>~~
			[[File:AppSuite-Spreadsheet-Installation-Mode-Server-Combined-Physical-Architecture.jpg]]
			[[File:AppSuite-Spreadsheet-Installation-Mode-Server-Combined-Logical-Architecture.jpg]]

	The system is designed to provide basic functionality and availability with a minimum of necessary hardware. If the services on one OX server fail, this is NOT transparently handled by other machines.		The system is designed to provide basic functionality and availability with a minimum of necessary hardware. If the services on one OX server fail, this is NOT transparently handled by other machines.

Andreas.schluens: new doc for release 7.8.0

2015-10-02T07:37:54Z

new doc for release 7.8.0

New page

== Tutorial : OX Spreadsheet deployment - Mode 'Server Combined' ==

=== General Information ===

This article describes what you need for an OX Spreadsheet setup - the Server installation.

It contains everything you need to:
* Understand the design of the OX Spreadsheet setup including additional services
* Install the whole system based on the relevant articles
* Find pointers to the next steps of integration

=== System Design ===
 
The system is designed to provide basic functionality and availability with a minimum of necessary hardware. If the services on one OX server fail, this is NOT transparently handled by other machines.

=== Core Components ===

* Nx OX AppSuite (HW recommendation: 16GB RAM / 4 cores) running as OX Appsuite Backend & OX Spreadsheet Client (follow the instructions regarding Nature 'OX-Backend')
* 1x OX Spreadsheet Server (HW recommendation: 24GB RAM / 4 cores) (follow the instructions regarding Nature 'CE-Server')
* Optional: Nx OX Spreadsheet Worker (HW recommendation: 24GB RAM / 4 cores) (see [[AppSuite:Spreadsheet:Installation:Mode-Server-Distributed|OX Spreadsheet Server - Mode 'Server Distributed']] )

=== Overview Installation Steps ===

To deploy the described OX Spreadsheet setup, the following steps need to be done.

''Mandatory Installation Steps''

* Install OX Appsuite - Nature 'OX-Backend'
* Install OX Spreadsheet Server - Nature 'CE-Server'

''Configuration Steps''

* Configure OX Appsuite - Nature 'OX-Backend'
* Configure OX Spreadsheet Server - Nature 'CE-Server'

''Start & Stop''

* Start/Stop OX Appsuite - Nature 'OX-Backend'
* Start/Stop OX Spreadsheet Server - Nature 'CE-Server'

=== Mandatory Installation Steps - Instructions & Recommendations ===

=== Install OX Appsuite - Nature 'OX-Backend' ===

The following steps need to be done to get OX Spreadsheet Client up and running:

* [[AppSuite:Spreadsheet:Installation:Mode-Server-Combined:Nature-OX-Backend:Debian-6.0|Download and Installation Guide for Debian GNU/Linux 6.0 (Squeeze)]]
* [[AppSuite:Spreadsheet:Installation:Mode-Server-Combined:Nature-OX-Backend:Debian-7.0|Download and Installation Guide for Debian GNU/Linux 7.0 (Wheezy)]]
* [[AppSuite:Spreadsheet:Installation:Mode-Server-Combined:Nature-OX-Backend:Debian-8.0|Download and Installation Guide for Debian GNU/Linux 8.0 (Jessie)]]
* [[AppSuite:Spreadsheet:Installation:Mode-Server-Combined:Nature-OX-Backend:SLES-11|Download and Installation Guide for SUSE Linux Enterprise Server 11]]
* [[AppSuite:Spreadsheet:Installation:Mode-Server-Combined:Nature-OX-Backend:SLE_12|Download and Installation Guide for SUSE Linux Enterprise Server 12]]
* [[AppSuite:Spreadsheet:Installation:Mode-Server-Combined:Nature-OX-Backend:RedHat-6|Download and Installation Guide for RedHat Enterprise Linux 6]]
* [[AppSuite:Spreadsheet:Installation:Mode-Server-Combined:Nature-OX-Backend:RedHat-7|Download and Installation Guide for RedHat Enterprise Linux 7]]

=== Install OX Spreadsheet Server - Nature 'CE-Server' ===

The following steps need to be done to get OX Spreadsheet Server up and running:

* [[AppSuite:Spreadsheet:Installation:Mode-Server-Combined:Nature-CE-Server:Debian-6.0|Download and Installation Guide for Debian GNU/Linux 6.0 (Squeeze)]]
* [[AppSuite:Spreadsheet:Installation:Mode-Server-Combined:Nature-CE-Server:Debian-7.0|Download and Installation Guide for Debian GNU/Linux 7.0 (Wheezy)]]
* [[AppSuite:Spreadsheet:Installation:Mode-Server-Combined:Nature-CE-Server:Debian-8.0|Download and Installation Guide for Debian GNU/Linux 8.0 (Jessie)]]
* [[AppSuite:Spreadsheet:Installation:Mode-Server-Combined:Nature-CE-Server:SLES-11|Download and Installation Guide for SUSE Linux Enterprise Server 11]]
* [[AppSuite:Spreadsheet:Installation:Mode-Server-Combined:Nature-CE-Server:SLE_12|Download and Installation Guide for SUSE Linux Enterprise Server 12]]
* [[AppSuite:Spreadsheet:Installation:Mode-Server-Combined:Nature-CE-Server:RedHat-6|Download and Installation Guide for RedHat Enterprise Linux 6]]
* [[AppSuite:Spreadsheet:Installation:Mode-Server-Combined:Nature-CE-Server:RedHat-7|Download and Installation Guide for RedHat Enterprise Linux 7]]

=== Configuration Steps - Instructions & Recommendations ===

=== Configure OX Appsuite - Nature 'OX-Backend' ===

After installation the OX Spreadsheet functionality is disabled by default. To enable OX Spreadsheet Application the associated permission has to be set. The default setting for all users is changed in the file'''''/opt/open-xchange/etc/permissions.properties'''''.

<source lang="ini">

# Note:
# This list is a comma seperated list of different permissions.
# Add or remove the permission you want to change - leave other permissions unchanged.

permissions=..,spreadsheet,..

</source>

By enabling the OX Spreadsheet Application the corresponding OX Spreadsheet Portal was enabled also. If that is not intended you can disable the OX Spreadsheet Portal within the same configuration file'''''/opt/open-xchange/etc/permissions.properties''''':

<source lang="ini">

# Note:
# This list is a comma seperated list of different permissions.
# Add or remove the permission you want to change - leave other permissions unchanged.

permissions=..,spreadsheet,spreadsheetportaldisabled,..

</source>

Enable client mode at this node inside configuration file'''''/opt/open-xchange/etc/calcengine.properties''''':

<source lang="ini">

# -----------------------------------------------------------------------------
# define the mode the calc engine will use at runtime.
...
# - jms
# all involved processes will look for a JMS server to communicate together.
...
#

calcengine.mode=jms

</source>

The OX Spreadsheet Client needs to know where the OX Spreadsheet Server is running. But the client is not connected to the server directly. As communication channel between both nodes JMS is used.

The OX Spreadsheet Server acts as a JMS Server also. Use the template'''''/opt/open-xchange/etc-templates/documents/mode-server-combined/nature-ox-backend/jms-server.properties''''' to generate a suitable configuration at'''''/opt/open-xchange/etc/documents/jms-server.properties''''' and replace all place holder following the schema'''''%%[...]%%'''''.

Note: All place holder values must be in sync with all other configuration files within the same setup.

<source lang="ini">

# =============================================================================
# NOTE : DO NOT USE DEFAULT VALUES WITHIN THIS SCRIPT AS THEY COME FROM THE CODE.
# ACTIVATE AND CHANGE VALUES IF NEEDED ONLY.

# -----------------------------------------------------------------------------
# define the host (IP/DNS) where the jms server is running and we have to
# be connected with
#
# default=127.0.0.1
#
jms.server.host=%%[CE_SERVER_IP]%%

# -----------------------------------------------------------------------------
# define the port where the server should listen for incoming requests
# or a client can be connected with those server.
#
# default=61616
#
#jms.server.port=61616

</source>

The OX Spreadsheet Server acts as a Cache Server also. Use the template'''''/opt/open-xchange/etc-templates/documents/mode-server-combined/nature-ox-backend/cache-server.properties''''' to generate a suitable configuration at'''''/opt/open-xchange/etc/documents/cache-server.properties''''' and replace all place holder following the schema'''''%%[...]%%'''''.

Note: All place holder values must be in sync with all other configuration files within the same setup.

<source lang="ini">

# =============================================================================
# NOTE : DO NOT USE DEFAULT VALUES WITHIN THIS SCRIPT AS THEY COME FROM THE CODE.
# ACTIVATE AND CHANGE VALUES IF NEEDED ONLY.

# -----------------------------------------------------------------------------
# define the host (IP/DNS) where the jms server is running and we have to
# be connected with
#
# default=127.0.0.1
#
cache.server.host=%%[CE_SERVER_IP]%%

# -----------------------------------------------------------------------------
# define the port where the server should listen for incoming requests
# or a client can be connected with those server.
#
# default=7000
#
#cache.server.port=7000

# -----------------------------------------------------------------------------
# unique ID for this server instance.
# Can be used to separate multiple server instances on the same machine.
#
cache.server.id=%%[CE_SERVER_ID]%%

# -----------------------------------------------------------------------------
# password to join those cache server.
# Can be empty.
#
cache.server.password=%%[CE_SERVER_PASSWORD]%%

</source>

=== Configure OX Spreadsheet Server - Nature 'CE-Server' ===

The OX Spreadsheet Server host:
* 1x OX Spreadsheet Server
* Nx OX Spreadsheet Worker
* 1x JMS Server for communication
* 1x Cache Server for caching data

The OX Spreadsheet Server node host all worker processes where the real user documents are handled. So e.g. the persistence of such documents (usable for an automatic document recovery in case a worker was restarted) has to be configured at this node. Inside the configuration file'''''/opt/open-xchange/etc/calcengine.properties'''''define the following:

<source lang="ini">

# -----------------------------------------------------------------------------
# define the mode the calc engine will use at runtime
#
# - jms
# calc engine is a central JMS server to communicate with
# all configured worker processes even clustered on different machines.
#
calcengine.mode=jms

# -----------------------------------------------------------------------------
# path where worker can cache there documents to support auto-restore in case
# a worker crashed and will be reactivated.
#
# If this path is empty - auto-restore will be disabled.
#
# This value can use special variable $(TEMP) to place the cache
# within the temporary directory. Other variables are not supported.
#
# Note: This feature can be disabled by define an empty path only !
#
calcengine.restore-documents.path=${sys:java.io.tmpdir}/ox-ce-doc-cache

</source>

The JMS Server is running besides the OX Spreadsheet server. Use the template'''''/opt/open-xchange/etc-templates/documents/mode-server-combined/nature-ce-server/jms-server.properties''''' to generate a suitable configuration at'''''/opt/open-xchange/etc/documents/jms-server.properties''''' and replace all place holder following the schema'''''%%[...]%%'''''.

<source lang="ini">

# =============================================================================
# NOTE : DO NOT USE DEFAULT VALUES WITHIN THIS SCRIPT AS THEY COME FROM THE CODE.
# ACTIVATE AND CHANGE VALUES IF NEEDED ONLY.

# -----------------------------------------------------------------------------
# define the network interface where the server should listen for incoming requests.
#
# Possible values are:
# - 0.0.0.0 to allow all (internal and external) connections
# - 127.0.0.1 to allow local connections only
#
# default=127.0.0.1
#
jms.server.interface=0.0.0.0

# -----------------------------------------------------------------------------
# define the port where the server should listen for incoming requests
# or a client can be connected with those server.
#
# default=61616
#
#jms.server.port=61616

# -----------------------------------------------------------------------------
# define directory for storing persistent data
#
# Will be created automatically if it does not exists.
# If it's not defined persistence will be disabled.
#
# Note: Thise feature can be disabled by setting an empty path only !
#
#jms.server.persistence.dir=${sys:java.io.tmpdir}/ox-jms-embedded-server/persistence

# -----------------------------------------------------------------------------
# frequency where the JMS Garbage Collector (GC) should run
#
# unit=[ms]
# default=300000 (5min)
#
#jms.server.gc.frequency=300000

# -----------------------------------------------------------------------------
# the time a JMS resource (queue/topic) has to be inactive before it can
# will be removed by the GC
#
# unit=[ms]
# default=60000 (1min)
#
#jms.server.gc.inactive-timeout-before-gc=60000

</source>

The Cache Server is running besides the OX Spreadsheet server. Use the template'''''/opt/open-xchange/etc-templates/documents/mode-server-combined/nature-ce-server/cache-server.properties''''' to generate a suitable configuration at'''''/opt/open-xchange/etc/documents/cache-server.properties''''' and replace all place holder following the schema'''''%%[...]%%'''''.

<source lang="ini">

# =============================================================================
# NOTE : DO NOT USE DEFAULT VALUES WITHIN THIS SCRIPT AS THEY COME FROM THE CODE.
# ACTIVATE AND CHANGE VALUES IF NEEDED ONLY.

# -----------------------------------------------------------------------------
# define the network interface where the server should listen for incoming requests.
#
# Possible values are:
# - <IP_RANGE> to allow all (internal and external) connections
# - 127.0.0.1 to allow local connections only
#
# <IP_RANGE> example:
# IP of local machine is "192.168.0.1".
# A might suitable IP range can be "192.168.0.*"
#
# default=127.0.0.1
#
cache.server.interface=%%[CE_CLIENTS_IP_RANGE]%%

# -----------------------------------------------------------------------------
# define the port where the server should listen for incoming requests
# or a client can be connected with those server.
#
# default=7000
#
#cache.server.port=7000

# -----------------------------------------------------------------------------
# unique ID for this server instance.
# Can be used to separate multiple server instances on the same machine.
#
# default = 'default'
#
cache.server.id=%%[CE_SERVER_ID]%%

# -----------------------------------------------------------------------------
# password to join those cache server.
# Can be empty.
#
# default = 'xxx'
#
cache.server.password=%%[CE_SERVER_PASSWORD]%%

# -----------------------------------------------------------------------------
# define directory for storing persistent data
#
# Will be created automatically if it does not exists.
# If it's not defined persistence will be disabled.
#
# Note: To disable this feature define an empty path.
#
# default = '${sys:java.io.tmpdir}/ox-cache-server/${cache.server.id}/persistence'
#
#cache.server.persistence.dir=${sys:java.io.tmpdir}/ox-cache-server/${cache.server.id}/persistence

</source>

As a principle of this architecture all OX Spreadsheet Worker run in parallel to the OX Spreadsheet Server at the same machine. The min/max count of processes and further settings related to OX Spreadsheet Worker can be configured within the file '''''/opt/open-xchange/etc/documents/cluster-node.xml'''''.: Use the template'''''/opt/open-xchange/etc-templates/documents/mode-server-combined/nature-ce-server/cluster-node.xml'''''to create those file.

<source lang="xml">



<cluster>

<node>

<cache>


</cache>

<watchdog>





</watchdog>

<apps merge-operation="explicit">


<app id="jms-server">


</app>


<app id="cache-server">


</app>


<app id="calcengine-server">


</app>


<app id="calcengine-worker">


<start-mode>auto</start-mode>


<min-instances>10</min-instances>


<max-instances>10</max-instances>




</app>

</apps>
</node>
</cluster>

</source>

=== Start & Stop - Instructions & Recommendations ===

Note: In general the order of starting both nodes (OX Appsuite and OX Spreadsheet Server) is not important. An automatic reconnect feature guarantee a stable environment at runtime. On the other side it's more ease to analyze and locate errors inside the deployment if both nodes are started in a special order : OX Spreadsheet Server firstOX Appsuite then

=== Start/Stop OX Spreadsheet Server - Nature 'CE-Server' ===

The OX Spreadsheet Server can be controlled by the script'''''/etc/init.d/open-xchange-cluster-management'''''. The OX Backend is not installed and has not to be started on this node.

<source lang="bash">

# start OX Spreadsheet Server
/etc/init.d/open-xchange-cluster-management start

...

# check status of OX Spreadsheet Server
/etc/init.d/open-xchange-cluster-management status

...

# stop OX Spreadsheet Server
/etc/init.d/open-xchange-cluster-management stop

</source>

=== Start/Stop OX Appsuite - Nature 'OX-Backend' ===

The OX Spreadsheet Client is running within the OX Backend process. So it's enough to control those backend service by calling the script'''''/etc/init.d/open-xchange'''''.

<source lang="bash">

# start OX Backend
/etc/init.d/open-xchange start

...

# check status of OX Backend
/etc/init.d/open-xchange status

...

# stop OX Backend
/etc/init.d/open-xchange stop

</source>

AppSuite:Spreadsheet:Installation:Mode-Server-Combined - Revision history

Andreas.schluens: add arch images

Andreas.schluens: new doc for release 7.8.0