Cireson Portal

How To: Cireson Platform Automation via Powershell

Synopsis

The Cireson Platform provides a runtime that can be executed in a number of ways, including as a Standard Windows Service, or from a Windows command prompt.  When applications running on Cireson Platform are installed, the installer will typically install an instance of the Cireson Platform behind the scenes.  Once installed, the application may expose additional management UIs in the form of Web based forms, or OData, or Webapi based api endpoints.  Out of the box, a number of OData apis are available so a user can install and run a platform instance, and manually add additional CPEX based application

Installation

Installation of the Cireson Platform is typically done by the use of either a GUI based setup application, or the CpexLets Powershell module.  

In this article, we will be going over some basics of Platform installation, and demonstrating how to install the platform into your environment using the previously mentioned PowerShell module.

Installation of the Platform itself is a rather simple operation, one simply needs to copy the appropriate binaries into a directory on the local server, and execute Cireson.Platform.Host.exe with appropriate command line arguments. A list of available arguments can be found by executing Cireson.Platform.Host.exe /? from a command line.

The CpexLets powershell module provides a number of handy commands that allow you to download and install the platform, create and save specific configurations, install applications to your running platform and uninstall the platform.

In order to follow along with this guide, you should have a computer that meets the minimum requirements for running the Cireson Platform, including SQLServer.

You should also ensure you have the latest version of Powershell installed, and that you have appropriate administrative permissions to execute scripts, and modify the database.

Installing Cireson Cpexlets Powershell Module

The first step to be able to install the Cireson Platform is to retrieve the CpexLets module. To do this we need to first register the Cireson Package feed, then we can import the CpexLets module, and start running commands.

  1. Open a Powershell command window as administrator
  2. Execute the following PowerShell command
    Register-PackageSource "https://cireson.myget.org/F/public/api/v2" -Name CiresonPublicFeed -Trusted -ProviderName PowerShellGet
  3. This will add the Cireson Development Package Feed to your list of trusted package feeds. If you later wish to unregister the feed, you can do so by executing the following command
    Unregister-PackageSource -Name CiresonPublicFeed
  4. Next we need to import the CpexLets module. Execute the following command
    Install-Module -Name CpexLets
  5. Now we are ready to start using the CpexLets to manage our Platform.

Setting the correct feed source

  1. From the powershell prompt, execute the following command to connect to the Development feed
    Connect-CPEXFeed -feedName public
  2. This will ensure that commands are routed to the appropriate nuget feed.

Finding Applications to install

By itself, the Cireson Platform represents an extensible runtime that provides OData services, Scheduled Task, and Worker management. In order to do anything usefull, you typically need to install one or more Cpex Applications. A Cpex Application is simply a regular Cpex with an additional CiresonCPEXApp tag.  A CPEX Application should reference everything needed to run the application on the Cireson Platform. Most applications will reference one or more additional Cpex extensions as well.

  1. You can list the applications that are available on the connected feed using the following command Get-CPEXApplications
  2. You should see a list of Applications that are available for the current feed.

Note: If you do not see the expected application listed, it means that either the application is not on the selected feed, or the CPEX does not have a CiresonCpexApp tag.  If the Cpex exists on the feed, then it can still be installed, it will just not be listed in the Get-CPEXApplications list. 

Creating a PlatformConfig for installation

A Platform Config allows you to define various parameters that you can use to install the platform, you can also save the configuration to use later, or to create automated installation procedures. During installation depending on the context of the installation, you can alter discreet properties specific to the current installation.

  1. From your elevated Powershell window, execute the following command replacing values for sqlServerName, databaseName, productKey, and configFilePath to match your environment
    • Get-CPEXPlatformConnectionString -sqlServerName localhost -databaseName CiresonPlatformTutorial | New-CPEXPlatformConfig -ServiceName CiresonTutorial -installPath c:\CiresonPlatformTutorial\platform -productKey ***ProductKey or CustomerKey Assigned to you by Cireson*** -defaultApplicationName Cireson.PasswordReset -configFilePath c:\CiresonPlatformTutorial\PlatformTutorial.config
  2. Look at the file that was generated in configFilePath so you can see what the configuration values look like.
  3. Notice the property for defaultApplicationName this tells the CPEXLets to install the Cireson.PasswordReset application when the platform first runs.  By default it will select the latest available version, use defaultApplicationVersion to specify the desired version if not latest. 
  4. There are additional options available when creating a new PlatformConfig file. You can use New-CPEXPlatformConfig -? to get more information on the specific parameters and their usage.

Installing a Cireson Platform Application from Powershell

In order to install a platform application, we simply need to get the PlatformConfig that we created in the previous step, and pipe it into the Install-CpexPlatform cmdlet.

  1. From Powershell execute the following command, replacing the file path with the path you chose in the previous step, and adding a local or domain service user
    Get-CPEXPlatformConfig -path C:\CiresonPlatformTutorial\PlatformTutorial.config | Install-CPEXPlatform -serviceUser .\test -servicePassword P@ssW0rd
  2. In a moment, you will see the results of the command in the console.
  3. Open a web browser (I like Chrome as it allows you to view Json in the page, and has some nice extensions to prettify it)
  4. Navigate to http://localhost/api you should see the default oData endpoint
  5. In the background, the platform may be installing the chosen extension. Once installed the platform will restart, and you will see a Platform Starting message if you refresh the page
  6. When the platform comes back up, navigate to http://localhost and you will be presented with the default UI for the installed application.

Uninstalling the platform service

Uninstalling the platform service will remove the service from the Service Control Manager, but will not remove the database, or the local files.

  1. To uninstall the platform that we just installed, run the following command  Get-CPEXPlatformConfig -path C:\CiresonPlatformTutorial\PlatformTutorial.config | Uninstall-CPEXPlatform

If you have an existing Cireson Platform installation that was created using a Setup GUI or some other way, you can create a CPEXPlatformConfig referencing installed service name, and uninstall the existing service using the same steps.