Installation introduction
Welcome to the installation instructions for ShareAspace. This section describes the installation procedure of the different ShareAspace components whether you want to install them on a single machine or multiple machines with or without redundancy (failover).
Product versioning
ShareAspace uses the following versioning numbering format:
Product.MajorVersion.MinorVersion.(Build)
- 1.3.x -> 1.4.y is considered a major update. There will be breaking changes and the data store must be migrated.
- 1.x.1 -> 1.x.2 is considered a minor update (service pack). The service packs will be compatible within one major release.
- It is possible to upgrade from any Major.Minor.x to a Major.Minor.y where y > x
- In some cases, for critical fixes a patch might be produced. A patch is a release between two service packs. All patches will be included in the next service pack.
- A patch will be versioned as x.y.z-patch# (e.g. 1.6.2-patch1).
- A patch can be used in an upgrade just like a service pack.
Architecture
The logical architecture of the deployment environment for ShareAspace consists of:
- An Application Server layer
- A Web Server layer
- A Client layer
ShareAspace can be deployed onto a single server, i.e. one physical machine, that hosts both the Application and the Web server layers Alternatively if better performance and resilience is required, the Application and Web server layers can be deployed to separate physical machines.
Where high levels of availability is required a failover architecture can be deployed.
In all cases the Client layer is the computer hosting the web browser.
Tip
In any of the installation situations, it is recommended to keep a log of :
- What component and their version are installed
- The environment (hardware, operating system, options and software) description on which each component is installed
To help with this work, an install log template is provided here.
Installation packages
All of the components are installed by using Windows Installer files i.e. files with the extension .msi.
The name of a Windows Installer is as follows. ComponentName-version.msi
Where version is the release version of the component in the form described in the Product versioning section.
If the Host component would have the release version: 1.2.3.456 then the Windows Installer name
for the Host component would be Host-1.2.3.456.msi.
The installation package contains the following elements :
Note
The version numbering of the MSI packages below use the example version 1.8.0.123.
ShareAspace component installers
Documentation-1.8.0.123.msi- Documentation Web Page.Host-1.8.0.123.msi- Service Host Installer (the main component of ShareAspace).NovaWeb-1.8.0.123.msi- Web Application Installation package.ReverseProxy-1.8.0.123.msi- Gateway exposing the ShareAspace REST APIs.DataExchange-1.8.0.123.msi- Binaries for the Out-Of-The-Box DataExchange Tasks.
ShareAspace external extensions installers
FilePreview-1.8.0.123.msi- File Preview extension.FullTextIndexing-elastic8-1.8.0.123.msi- Full Text Indexing and Search extension.SendGridMail-1.8.0.123.msi- Mail setup extension for SendGrid.SMTPMail-1.8.0.123.msi- Mail extension for SMTP.EventLogging-1.8.0.123.msi- Extension used for event based logging.EmailAuthentication-1.8.0.123.msi- A simple authentication method that will ask for a user's email address. Provided that the user is registered in ShareAspace an email with a login code will be sent to the user's email.DeveloperLogin-1.8.0.123.msi- An authentication component that is intended for testing only. The system will have only one password, once typed in a list of all registered users will be presented. Clicking on one of the users allows you to impersonate that user. This component also has a simplified mailbox per user. All emails sent by ShareAspace to users will be caught by this component.3DViewer-1.8.0.123.msi- Installer for the 3D-viewer web application extension. Requires the CadConverter and StreamingCacheService.CadConverter-1.8.0.123.msi- Installer for external extension that:- Converts 3D geometry files to geometry that can be presented by the 3D viewer.
- Creates isometric 2D preview files for 3D geometry files.
StreamingCacheService-1.8.0.123.msi- Installer for streaming service that provides converted 3D geometry to the 3D Viewer using WebSockets.
Note
The DeveloperLogin component should only be used for testing and development purposes. EmailAuthentication can be used as a simple authentication method but best practice is still to use a third party identity provider via OpenID Connect.
ShareAspace tool installers
ConfigTool-1.8.0.123.msi- Graphical user interface for ShareAspace platform configuration.Utilities-1.8.0.123.msi- Set of different tools and scripts.EventLogQueryToJson-1.8.0.123.msi- todosas-devtool_1.8.0.123.zip- ZIP package containing the ShareAspace development tool.
SDKs
Eurostep.ModelFramework.1.8.0.123.nupkg- NuGet package used for building data mappers based on the Eurostep mapping framework.Eurostep.SAS.Logging.ShareAspace.1.8.0.123.nupkg- todo
Various files
1.8.x.md- Release notes for the corresponding versionREADME.md- Specific instructions for the current installation package
Logical architecture
The Web server layer of a ShareAspace installation hosts the following components:
- Reverse Proxy (Gateway)
- ShareAspace Web (Web Application)
- Documentation
- File Preview (Extension)
- Full Text Indexing (Extension)
- SendGrid Mail (Extension)
- SMTP Mail (Extension)
- Event logging (Extension)
Optionally it could include:
- EmailAuthentication (Extension)
- or DeveloperLogin (Extension) for test and development environments
The Application server layer of a ShareAspace installation hosts the following components:
- Host
- DataExchange
- Utilities
The other components can be deployed on any machine:
- Tools
- ConfigTool
Logical deployment architecture
Technical architecture
The core of ShareAspace is a platform serving the different end user applications (DesignTOManufacturing, Export Control, etc.). When installing the platform you are able, depending on your licence, to run any of these applications. Each Space instantiated within a Collection is running one of these products (or a custom-built template/application).
Reverse proxy (gateway)
The gateway is responsible for routing Client Requests to the configured node(s).
The gateway is a web application hosted within the Microsoft Internet Information Services (IIS).
Web framework
The ShareAspace Web Framework is a web application providing a SPA (Single Page Application) user interface to the client browsers.
The Web Framework has a set of Modules installed, each of them providing End User functionalities. A set of Modules makes up the User Interface for a ShareAspace packaged product.
The Web Framework can be self hosted or hosted within the Microsoft Internet Information Services (IIS).
External identity
For production setup a third party identity provider is required. See the OpenID Connect setup.
ShareAspace web uses OAuth 2.0 Code flow for the OpenID Connect authentication. The third party component must support "Proof Key for Code Exchange" (PKCE).
For test and development environments the DeveloperLogin or the EmailAuthentication components can be used.
ShareAspace host
A ShareAspace Host node is the ShareAspace server (the core component of ShareAspace).
A ShareAspace Host node exposes all REST APIs and hosts all ShareAspace core components, such as the Data Exchange, Event Service, etc.
Each ShareAspace Host node has its own transient storage for persisting the Collection data, Space data, and System data. ShareAspace components installed on one node (APIs and Providers).
REST APIs
There is a wide range of REST APIs within the Cluster Node Host. The APIs operate on different scopes, such as Collection, Space, or System.
Storage
The Storage is accessed and modified by the different providers. The storage is the semi-transient persistence layer within each host node.
File vault
Files, such as word documents, CAD models etc., are referenced and accessed from the cluster node and stored in binary on the file vault.
DataExchange
The Data Exchange is a Platform feature for scheduling and coordination of long running tasks, like imports, exports, and reports. It enables the ability to schedule background jobs on defined queues for a specific collaboration space.
Complete deployed architecture
Products (end user applications)
The ShareAspace platform is the foundation for a set of configurable products aimed for different usage scenarios.
A Product consists of:
- a configuration file (also called a template),
- a set of Extension APIs,
- a set of configurable Extension UI Modules for the ShareAspace Web.
These are deployed via the administration user interface of a Space project.
Planning the deployment environment
Depending on the following requirements:
- availability,
- performance,
- number of concurrent users,
- volume of data,
- number of integration points,
- etc.
ShareAspace can be deployed on a single machine or multiple machines.
For high levels of availability and resilience, the ShareAspace host can also be setup for failover using a set of ShareAspace Host nodes (minimum 2 nodes, one "primary node" and one "secondary node").
If ShareAspace is deployed on a single machine, all ShareAspace components above will be installed on the same machine.
If ShareAspace is deployed on a multiple machine setup, all ShareAspace components above can each be hosted on a different machine.
If ShareAspace is deployed with failover, each ShareAspace Host node will have exactly the same installed components (DataExchange, Event Service).
High level installation process
- Provision servers.
- Setting up the hosting environment based on need, see:
- Hardware prerequisites.
- Deployment setups.
- Install components.
- Installing the required and optional components, see:
- Component installations
- Configuration components, see:
- Bootstrap host, see:
- Bootstrap collection, see:
- Apply license, see:
- Licence.
- Note that the licence could be applied already in the collection bootstrap or after the registration of extensions but must be applied before spaces can be instantiated.
- Bootstrap DataExchange, see:
- Register extensions, see:
- Further steps
- Uploading space templates to collection.
- Create space(s).
- Invite users.
- See Administration