Installation introduction
Welcome to the installation instructions for ShareAspace. This section describes how to install the different ShareAspace components, whether you are deploying on a single machine or across multiple machines, with or without redundancy (failover).
This guide is intended for system administrators and deployment engineers responsible for installing and configuring ShareAspace.
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 architecture of the deployment environment for ShareAspace consists of:
- An Application server layer
- A Web server layer
- A Client layer
ShareAspace can be deployed on a single server hosting both the Application and Web server layers.
Alternatively, if improved performance or resilience is required, the Application and Web server layers can be deployed on separate 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:
- Which components and their versions are installed
- The environment (hardware, operating system, options, and installed software) on which each component is deployed
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 naming convention for Windows Installer files is: ComponentName.msi.
ShareAspace component installers
Documentation.msi- Documentation Web Page.Host.msi- Service Host installer (the main component of ShareAspace).NovaWeb.msi- Classic Web Application installation package.ReverseProxy.msi- Gateway exposing the ShareAspace REST APIs.WebUI.msi- New Web Application installation package (introduced in 1.9).OpenTelemetryCollector.msi- Component used to dump ShareAspace open telemetry streams to file blobs.
ShareAspace external extensions installers
FilePreview.msi- File Preview extension.FullTextIndexing.msi- Full Text Indexing and Search extension.SendGridMail.msi- Mail setup extension for SendGrid.SMTPMail.msi- Mail extension for SMTP.EventLogging.msi- Extension used for event based logging.EmailAuthentication.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.msi- For classic web - 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.DeveloperAuthentication.msi- For new web - 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.msi- Installer for the 3D-viewer web application extension. Requires the CadConverter and StreamingCacheService.CadConverter.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.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.msi- Graphical user interface for ShareAspace platform configuration.sas-devtool.zip- ZIP package containing the ShareAspace development tool.
SDKs
The SDKs are using the naming scheme {package-namespace}.{version}.nupkg.
| Dev kit | Description |
|---|---|
Eurostep.ModelFramework.DevKit.Mapping.1.9.0.201.nupkg |
Development kit for the ShareAspace mapping framework (see Mapping framework) |
Eurostep.ModelFramework.DevKit.Mapping.Testing.1.9.0.201.nupkg |
Development kit for building unit tests against mapping implemented using the ShareAspace mapping framework. |
Eurostep.ModelFramework.DevKit.Toolbox.1.9.0.201.nupkg |
Development kit for the ShareAspace SoftType toolbox. |
Eurostep.SAS.DevKit.External.Extension.1.9.0.201.nupkg |
Development kit with convenience libraries for using the ShareAspace REST APIs. |
Eurostep.SAS.DevKit.External.Extension.ExternalEvent.1.9.0.201.nupkg |
Development kit for implementing external event handlers (see External extensions) |
Eurostep.SAS.DevKit.External.Extension.ExternalTask.1.9.0.201.nupkg |
Development kit for implementing external tasks (see External extensions) |
Eurostep.SAS.DevKit.External.Extension.ExternalValidation.1.9.0.201.nupkg |
Development kit for implementing external event validators (see External extensions) |
Eurostep.SAS.DevKit.External.Extension.FileConverter.1.9.0.201.nupkg |
Development kit for implementing CAD conversion. |
Eurostep.SAS.DevKit.External.Extension.FilePreview.1.9.0.201.nupkg |
Development kit for implementing custom file preview generators (see External extensions) |
Eurostep.SAS.DevKit.External.Extension.FullTextIndexing.1.9.0.201.nupkg |
Development kit for implementing custom full text indexing (see External extensions) |
Eurostep.SAS.DevKit.External.Extension.FullTextSearch.1.9.0.201.nupkg |
Development kit for implementing custom full text search (see External extensions) |
Eurostep.SAS.DevKit.External.Extension.Mail.1.9.0.201.nupkg |
Development kit for implementing custom email handling (see External extensions) |
Eurostep.SAS.DevKit.External.Logging.ShareAspace.1.9.0.201.nupkg |
Development kit for for reporting extension log information back to ShareAspace. (see External extensions) |
Deployment architecture
The Web server layer of a ShareAspace installation hosts the following components:
- Reverse Proxy (Gateway)
- ShareAspace Web, new and classic (Web Application)
- Documentation (internal use only)
- File Preview (optional extension)
- Full Text Indexing (optional extension)
- SendGrid Mail (optional extension)
- SMTP Mail (optional extension)
- Event logging (optional 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
- Open telemetry collector (optional)
Note
Extension components with a end user facing frontends must be deployed on the Web server.
Tip
Extensions can be hosted on separate servers.
Deployment architecture
Technical architecture
The core of ShareAspace is a platform serving the different end user applications (Design to manufacturing, 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 application - classic
ShareAspace Web classic is a web application providing a SPA (Single Page Application) user interface to the client browsers.
ShareAspace Web classic 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.
ShareAspace Web classic can be self hosted or hosted within the Microsoft Internet Information Services (IIS).
Web application - new
The new ShareAspace web application is a server side rendered end user application that streams views to clients.
The new ShareAspace web application is hosted in 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.
REST APIs
There is a wide range of REST APIs within the 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.
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 (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 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.
- Register extensions, see:
- Further steps
- Uploading space templates to collection.
- Create space(s).
- Invite users.
- See Administration