diff --git a/README.md b/README.md index e3987f0..f7963cd 100644 --- a/README.md +++ b/README.md @@ -92,1275 +92,5 @@ docker run -it --rm clio help docker run -it --rm clio reg-web-app -help ``` -# Content table - -- [Introduction](#introduction) -- [Installation and features](#installation-and-features) - - [Windows](#windows) - - [Context menu](#context-menu) - - [MacOS](#macos) - - [Help and examples](#help-and-examples) - - [Run with docker](#run-with-docker) - - [Build](#build) - - [Run](#run) -- [Content table](#content-table) -- [Arguments](#arguments) -- [Packages](#packages) - - [Creating new package](#creating-new-package) - - [Adding new package to workspace](#add-package) - - [Installing package](#installing-package) - - [Compile package](#compile-package) - - [Pull package from remote application](#pull-package-from-remote-application) - - [Delete package](#delete-package) - - [Uninstall application](#uninstall-application) - - [Compress package](#compress-package) - - [Extract package](#extract-package) - - [Restore configuration](#restore-configuration) - - [Get package list](#get-package-list) - - [Set package version](#set-package-version) -- [NuGet Packages](#nuget-packages) - - [Pack NuGet package](#pack-nuget-package) - - [Push NuGet package](#push-nuget-package) - - [Restore NuGet package](#restore-nuget-package) - - [Install NuGet package](#install-nuget-package) - - [Check packages updates in NuGet](#check-packages-updates-in-nuget) -- [Application](#application) - - [Upload Licenses](#upload-licenses) - - [Restart application](#restart-application) - - [Clear redis database](#clear-redis-database) - - [Compile configuration](#compile-configuration) - - [System settings](#system-settings) - - [Features](#features) - - [Set Base WebService Url](#set-base-webservice-url) -- [Environment settings](#environment-settings) - - [Create/Update an environment](#createupdate-an-environment) - - [Delete the existing environment](#delete-the-existing-environment) - - [Check environment](#check-environment) - - [View application options](#view-application-options) - - [Open application](#open-application) - - [Ping application](#ping-application) - - [Healthcheck](#healthcheck) -- [Development](#development) - - [Workspaces](#workspaces) - - [Convert package](#convert-package) - - [Execute assembly](#execute-assembly) - - [References](#references) - - [Execute custom SQL script](#execute-custom-sql-script) - - [Execute dataservice request](#dataservice) - - [Help and examples](#help-and-examples) - - [Add item](#add-item) - - [Add-Schema](#add-schema) - - [Link Workspace to File Design Mode](#link-workspace-to-file-design-mode) - - [Mock data for Unit Tests](#mock-data-for-unit-tests) -- [Packages](#packages) - - [Creating new package](#creating-new-package) - - [Installing package](#installing-package) - - [Pull package from remote application](#pull-package-from-remote-application) - - [Delete package](#delete-package) - - [Compress package](#compress-package) - - [Extract package](#extract-package) - - [Restore configuration](#restore-configuration) - - [Get package list](#get-package-list) - - [Set package version](#set-package-version) - - [Set application version](#set-application-version) - - [Set application icon](#set-application-icon) -- [NuGet Packages](#nuget-packages) - - [Pack NuGet package](#pack-nuget-package) - - [Push NuGet package](#push-nuget-package) - - [Restore NuGet package](#restore-nuget-package) - - [Install NuGet package](#install-nuget-package) - - [Check packages updates in NuGet](#check-packages-updates-in-nuget) -- [Environment settings](#environment-settings) - - [Create/Update an environment](#createupdate-an-environment) - - [Delete the existing environment](#delete-the-existing-environment) - - [Check environment](#check-environment) - - [View application options](#view-application-options) - - [Open application](#open-application) - - [Ping application](#ping-application) - - [Clone environment](#clone-environment) -- [Using for CI/CD systems](#using-for-cicd-systems) -- [GitOps](#gitops) -- [Installation of Creatio](#installation-of-creatio-using-clio) - - [Manage required Windows features](#manage-required-windows-features) - - [Uninstall Creatio](#uninstall-creatio) - -# Arguments - -- `` - package name -- `` - environment name -- `` - clio command name - - -# Packages - -## Creating new package - -To create a new package project, use the next command: - -``` - clio new-pkg -``` - -you can set reference on local core assembly by using Creatio file design mode with command in Pkg directory - -``` - clio new-pkg -r bin -``` - -## Add package -When creating package with option -a True then an `app-descriptor.json` will be created. -All subsequent packages will be added to `app-descriptor.json`. -```bash -#To add package with app descriptor -clio add-package -a True - -#To add package without app descriptor -clio add-package -a False -``` - - -## Installing package - -To install package from directory, you can use the next command: -for non-compressed package in current folder - -``` -clio push-pkg -``` - -or for .gz packages you can use command: - -``` -clio push-pkg package.gz -``` - -or with full path - -``` -clio push-pkg C:\Packages\package.gz -``` - -for get installation log file specify report path parameter - -``` -clio push-pkg -r log.txt -``` - -install one or more applications from marketplace.creatio.com - -``` -clio push-pkg --id 22966 10096 -``` - -> [!IMPORTANT] -> When you work with packages from Application Hub, you need use command push-app with same parameters like push-pkg. For example - -``` -clio push-app C:\Packages\package.gz -``` - -## Compile package - -For compile package - -``` -clio compile-package - -//or - -clio compile-package -e -``` - -## Pull package from remote application - -To download package to a local file system from application, use command: - -``` -clio pull-pkg -``` - -for pull package from non default application - -``` -clio pull-pkg -e -``` - -Applies to Creatio 7.14.0 and up - -## Delete package - -To delete a package, use the next command: - -``` -clio delete-pkg-remote -``` - -for delete for non default application - -``` -clio delete-pkg-remote -e -``` - -## Download application - -```bash -clio download-app -e -#or -clio download-app -e --FilePath -``` - -## Deploy application - -```bash -clio deploy-application -e -d - -#or omit -e argument to take application from default environment - -clio deploy-app -d -```` - - - -## Uninstall application - -To uninstall application, use the next command: - -``` -clio uninstall-app-remote -``` - -x - - -## Compress package - -To compress package into *.gz archive for directory which contains package folder - -``` -clio generate-pkg-zip -``` - -or you can specify full path for package and .gz file - -``` -clio generate-pkg-zip C:\Packages\package -d C:\Store\package.gz -``` - -## List Installed Applications - -The `get-app-list` command, also short alias as `apps`, -is used to list all the installed applications in the selected environment. -This command is useful when you want to check which applications are currently -installed in your Creatio environment. - -```bash -clio get-app-list - -#or - -clio apps -``` - - -## Extract package - -For package from *.gz archive - -``` -clio extract-pkg-zip .gz -d c:\Pkg\ -``` - -## Restore configuration - -Restore configuration - -``` -clio restore-configuration -``` -Restore configuration without rollback data - -``` -clio restore-configuration -d -``` - -Restore configuration without sql backward compatibility check - -``` -clio restore-configuration -f -``` - -## Get package list - -To get packages list in selected environment, use the next command: - -``` -clio get-pkg-list -``` - -for filter results, use -f option - -``` -clio get-pkg-list -f clio -``` - -## Set package version - -Set a specified package version into descriptor.json by specified package path. - -``` -clio set-pkg-version -v -``` - -## Set application version - -Set a specified composable application version into application-descriptor.json by specified workspace or package path. - -``` -clio set-app-version -v - -// or - -clio set-app-versin -f -v - -``` - - -## Set Application Icon - -The `set-app-icon` command is used to set the icon for a specified application -by updating the `app-descriptor.json` file. - -### Usage - -```bash -clio set-app-icon [options] -``` --p, --app-name (required): The name or code of the application. --i, --app-icon (required): The path to the SVG icon file to be set. --f, --app-path (required): Path to application package folder or archive. - -Examples -Set the icon for an application with a specified name: - -```bash -clio set-app-icon -p MyAppName -i /path/to/icon.svg -f /path/to/app -``` - - -## Enable/Disable pkg hotfix mode - -To see full description about Hot Fix mode visit [Creatio Academy](https://academy.creatio.com/docs/8.x/dev/development-on-creatio-platform/development-tools/delivery/hotfix-mode -) - -```bash - -# To enable hot-fix mode for a package -clio pkg-hotfix true -e - -# To disable hot-fix mode for a package -clio pkg-hotfix false -e - - -``` - -## Marketplace Catalog - -List marketplace applications -``` -clio catalog -``` - -List marketplace applications and highlight search words -``` -clio catalog -n Data -``` - -# NuGet Packages - -## Pack NuGet package - -To pack creatio package to a NuGet package (*.nupkg), use the next command: - -``` -pack-nuget-pkg [--Dependencies [:][,[:],...]>] [--NupkgDirectory ] -``` - -Default value of 'PACKAGE_VERSION' argument it's last package version. - -Default value of 'NupkgDirectory' argument it's current directory. - -## Push NuGet package - -To push NuGet package (*.nupkg) to a NuGet repository, use the next command: - -``` -push-nuget-pkg --ApiKey --Source -``` - -## Restore NuGet package - -To restore NuGet package (*.nupkg) to destination restoring package directory , use the next command: - -``` -restore-nuget-pkg [:] [--DestinationDirectory ] [--Source ] -``` - -Default value of 'PACKAGE_VERSION' argument it's last package version. - -Default value of 'DestinationDirectory' argument it's current directory. - -Default value of 'Source' argument: https://www.nuget.org/api/v2 - -## Install NuGet package - -To install NuGet package to a web application Creatio, use the next command: - -``` -clio install-nuget-pkg [:] [--Source ] -``` - -you can install NuGet package of last version: - -``` -clio install-nuget-pkg [--Source ] -``` - -for install several NuGet packages: - -``` -clio install-nuget-pkg [:][,[:],...]> [--Source ] -``` - -or you can install several NuGet packages of last versions: - -``` -clio install-nuget-pkg [,,...]> [--Source ] -``` - -Default value of 'PACKAGE_VERSION' argument it's last package version. - -Default value of 'Source' argument: https://www.nuget.org/api/v2 - -## Check packages updates in NuGet - -To check Creatio packages updates in a NuGet repository, use the next command: - -```bash -clio check-nuget-update [--Source ] -``` - -Default value of 'Source' argument: https://www.nuget.org/api/v2 - -# Application - -## Upload licenses - -To upload licenses to Creatio application, use the next command for default environment: - -```bash -clio lic -``` - -```bash -clio lic -e -``` - -## Restart application - -To restart Creatio application, use the next command for default environment: - -```bash -clio restart-web-app -``` - -or for register application - -```bash -clio restart-web-app -``` - -## Clear redis database - -For default application - -```bash -clio clear-redis-db -``` - -or non default application - -```bash -clio clear-redis-db -``` - -## Compile configuration - -For compile configuration - -```bash -clio compile-configuration -``` -or -```bash -clio compile-configuration -``` - -for compile all - -```bash -clio compile-configuration --all -``` - -## Get last compilation log - -Requires CanManageSolution operation permission - -```bash -# Display last compilation log, in format similar to IDE -clio last-compilation-log -e -``` - -```bash -# Display raw output (json) -clio last-compilation-log -e --raw -``` - -```bash -# Save creatio compilation log to file, -# --log option can be used jointly with --raw -clio last-compilation-log -e --log "C:\log.txt" -``` - -## System settings - -To set system settings value - -```bash -clio set-syssetting -``` - -To read system settings value - -```bash -get-syssetting --GET -e -``` - -## Features - -To enable feature - -```bash -clio set-feature 1 -``` - -To disable feature - -```bash -clio set-feature 0 -``` - -To specify User or Role, use SysAdminUnitName options - -```bash -clio set-feature 1 --SysAdminUnitName Supervisor -``` - -## Set Base WebService Url - -To configure a base url of a web service, in an environment use the following command. -It may be useful when you need to change the base url of a web service in a development or -testing environment. - -```bash -clio set-webservice-url -e - -``` - - -## Version - -Get versions of all known components -```bash -clio ver -``` - -Get current clio version -```bash -clio ver --clio -``` - -Get current cliogate version -```bash -clio ver --gate -``` - -Get dotnet runtime that executes clio -```bash -clio ver --runtime -``` - - -# Environment settings - -Environment is the set of configuration options. It consist of name, Creatio application URL, login, and password. - -## Create/Update an environment - -Register new application settings - -```powershell -clio reg-web-app -u https://mysite.creatio.com -l administrator -p password -``` - -or update existing settings - -```bash -clio reg-web-app -u administrator -p password -``` - -## Set the active environment -``` -clio reg-web-app -a -``` - -## Delete the existing environment - -```bash -clio unreg-web-app -``` - -## Check environment - -For validation existing environment setting you can use ping command - -```bash -clio ping -``` - -## View application options - -For view list of all applications - -```bash -clio show-web-app-list -``` - -or for concrete application - -```bash -clio show-web-app -``` - -## Open application - -For open selected environment in default browser use (Windows only command) - -```bash -clio open -``` - -## Ping application - -For check options fort selected environment use next command - -```bash -clio ping -``` - -## Clone environment - -For clone environment use next command. - -```bash -clio clone-env --source Dev --target QA --working-directory [OPTIONAL PATH TO STORE] -``` - -The command creates a manifest from the source and target, calculates the difference between them, downloads the changed package from the source environment to the working directory (optional parameter), and installs it in the source environment. - - -## Healthcheck - -Check application health - - -```bash -clio hc -``` - -```bash -clio healthcheck -a true -h true -``` - -```bash -clio healthcheck --WebApp true --WebHost true -``` - -## Get Creatio Platform Info - -This command is designed to retrieve information about the Creatio instance, version, -underlying runtime and database type and product name. - -```bash -clio get-info -e - -//OR - -clio get-info -```` - - - -# Development - -## Workspaces - -For connect professional developer tools and Creatio no-code designers, you can organize development flow in you local file system in **workspace.** - -https://user-images.githubusercontent.com/26967647/166842902-566af234-f9ad-48fb-82c1-0a0302bc5b3c.mp4 - -Create workspace in local directory, execute create-workspace command - -```bash -C:\Demo> clio create-workspace -``` - -In directory **.clio** specify you packages - -Create workspace in local directory with all editable packages from environment, execute create-workspace command with argument -e - -```bash -C:\Demo> clio create-workspace -e demo -``` - -Create workspace in local directory with packages in app, execute create-workspace command -To get list of app codes execute `clio lia -e ` - -```bash -C:\Demo> clio create-workspace --AppCode -``` - -Restore packages in you file system via command from selected environment - -```powershell -clio restore-workspace -e demo -``` - -Workspace supports Package assembly. Clio creates, ready to go solution that you can work on -in a professional IDE of your choice. To open solution execute command - -```powershell -OpenSolution.cmd -``` - -Push code to an environment via command, then work with it from Creatio - -```bash -clio push-workspace -e demo -``` - -**IMPORTANT**: Workspaces available from clio 3.0.1.2 and above, and for full support developer flow you must install additional system package **cliogate** to you environment. - -```bash -C:\Demo> clio install-gate -e demo -``` - -## Convert package - -```bash -clio convert -``` - -## Execute assembly - -Execute code from assembly - -```bash -clio execute-assembly-code -f myassembly.dll -t MyNamespace.CodeExecutor -``` - -## References - -Set references for project on src - -```bash -clio ref-to src -``` - -Set references for project on application distributive binary files - -```bash -clio ref-to bin -``` - -## Execute custom SQL script - -Execute custom SQL script on a web application - -```bash -execute-sql-script "SELECT Id FROM SysSettings WHERE Code = 'CustomPackageId'" -``` - -Executes custom SQL script from specified file - -```bash -execute-sql-script -f c:\Path to file\file.sql -``` - -## DataService - -Execute dataservice requests on a web application. - -| Key | Value | Description | -|:---:|:------------------------|:-------------------------------------------------------| -| -t | Operation Type | One of [select, insert, update, delete] | -| -f | Input filename | File in json format that contains request payload | -| -d | Output filename | File where result of the operation will be saved | -| -v | Variables to substitute | List of key-value pairs to substitute in an input file | - -Execute dataservice request with variable substitution. -```json -{ - "rootSchemaName": "{{rootSchemaName}}", - "operationType": 0, - "includeProcessExecutionData": true, - "columns": { - "items": { - "Id": { - "caption": "", - "orderDirection": 0, - "orderPosition": -1, - "isVisible": true, - "expression": { - "expressionType": 0, - "columnPath": "{{IdVar}}" - } - } - } - } -} -``` - -``` -clio ds -t select -f SelectAllContacts.json -d SelectAllContacts_Result.json -v rootSchemaName=Contact;IdVar=Id -``` - -## Add item -Create item in project -``` -clio -``` - -Add web service template to project -``` -clio add-item service test -``` - -Add entity-listener template to project -```bash -clio add-item entity-listener test -``` - -Generate AFT model for `Contact` entity with `Name` and `Email` fields, set namespace to `MyNameSpace` and save to `current directory` -```bash -clio add-item model Contact -f Name,Email -n MyNameSpace -d . -``` - -Generate ATF models for `All` entities, with comments pulled from description in en-US `Culture` and set `ATF.Repository.Models` namespace and save them to `C:\MyModels` -```bash -add-item model -n "" -d -``` - -To generate all models in current directory -```bash -add-item model -n "" -``` - -OPTIONS - -| Short name | Long name | Description | -|:-------------|:----------------|:-----------------------------------------------| -| d | DestinationPath | Path to source directory | -| n | Namespace | Name space for service classes and ATF models | -| f | Fields | Required fields for ATF model class | -| a | All | Create ATF models for all Entities | -| x | Culture | Description culture | - -## Add Schema -Adds cs schema to a project - -```bash -clio add-schema -t source-code -p -```` - -## Switch Nuget To Dll Reference - -The `switch-nuget-to-dll-reference` command is a vital tool for managing NuGet package references, -especially in scenarios where internet access is limited or unavailable. -This command is specifically designed to convert NuGet package references into direct dll -(Dynamic Link Library) references. - -### Use Case - -`switch-nuget-to-dll-reference` command, is beneficial when developing a package on for installation on Creatio -instance that lacks internet connectivity. Command converts `[PackageReference]` into local DLLs, -This facilitates seamless package installation and operation in offline environments. - -Lear more about [PackageReference] and [Reference] in Microsoft documentation. - -[PackageReference]: https://learn.microsoft.com/en-us/nuget/consume-packages/package-references-in-project-files -[Reference]: https://learn.microsoft.com/en-us/visualstudio/msbuild/common-msbuild-project-items?view=vs-2022#reference - -### How to Use -```bash -clio switch-nuget-to-dll-reference - -#or - -clio nuget2dll -``` - -## Link Workspace to File Design Mode - -To connect your package from workspace to local system in file design mode use command -``` -clio link-from-repository --repoPath {Path to workspace packages folder} --envPkgPath {Path to environment package folder ({LOCAL_CREATIO_PATH}Terrasoft.WebApp\\Terrasoft.Configuration\\Pkg)} -``` -
-Link all packages from repository - -```ps -clio l4r -e ({LOCAL_CREATIO_PATH}Terrasoft.WebApp\\Terrasoft.Configuration\\Pkg) -p * -r .\ -``` - -
- - - -To connect your local system in file design mode use command to workspace -``` -clio link-to-repository --repoPath {Path to workspace packages folder} --envPkgPath {Path to environment package folder ({LOCAL_CREATIO_PATH}Terrasoft.WebApp\\Terrasoft.Configuration\\Pkg)} -``` - -## Mock data for unit tests - -To mock data for unit tests with using [ATF].[Repository] use the following command - -``` - -clio mock-data --models D:\Projects\MyProject --data D:\Projects\MyProject\Tests\TestsData -e MyDevCreatio - -`` - -# Using for CI/CD systems - -In CI/CD systems, you can specify configuration options when calling commands: - -``` -clio restart -u https://mysite.creatio.com -l administrator -p password -``` - -# GitOps - -To support GitOps approach clio provides yaml manifest file. This file has following structure to describes desired state of Creatio instance. -Example of manifest: - -```yaml -environment: - url: https://production.creatio.com - username: admin # or use OAuth token - password: password # or use OAuth token - clientid: "{client-id}" - clientsecret: "{client-secret}" - authappurl: https://production.creatio.com/0/ServiceModel/AuthService.svc/Login - platformversion: "8.1.1" - platformtype: "NET6" # "NET6" or "NETFramework" - -apps: - - name: CrtCustomer360 - version: "1.0.1" - apphub: MyAppHub - - name: CrtCaseManagment - version: "1.0.2" - apphub: CreatioMarketplace - -syssettings: - - name: SysSettings1 - value: Value1 - - name: SysSettings2 - value: Value2 - -features: - - name: Feature1 - enabled: "true" - - name: Feature2 - enabled: "false" - -webservices: - - name: WebService1 - url: "https://preprod.creatio.com/0/ServiceModel/EntityDataService.svc" - - name: WebService2 - url: "https://preprod.creatio.com/0/ServiceModel/EntityDataService.svc" - -app_hubs: - - name: MyAppHub - path: "//tscrm.com/dfs-ts/MyAppHub" - - name: CreatioMarketplace - url: "https://marketplace.creatio.com/apps" - -``` - -## Apply manifest to Creatio instance - -To apply manifest to your Creatio instance use the following command - -``` - -clio apply-manifest "D:\manifest\myinstance-creatio-manifest.yaml" -e MyInstance - -``` - -## Create manifest from Creatio instance - -To control changes of an instance download state to manifest file and store it in Git. To download state use the following command - -``` -clio save-state "D:\manifest\myinstance-creatio-manifest.yaml" -e MyInstance -``` - -## Show difference in settings for two Creatio intances - -To compare two Creatio instances and show it use the following command - -``` -clio show-diff --source production --target qa -``` - -To save diff manifest to file, specify arguments file - -``` -clio show-diff --source production --target qa --file diff-production-qa.yaml -``` - - -## Automation scenarios -You can combine multiple commands into one scenario and execute it with -``` -clio run-scenario --file-name scenario.yaml -``` -Scenario consists of and steps and optional settings and/or secrets. -```yaml -secrets: - Login: real-login - Password: real-password - -settings: - uri: http://localhost:80 - -steps: - - action: restart - description: restart application - options: - uri: {{settings.uri}} - Login: {{secrets.Login}} - Password: {{secrets.Password}} -``` - -See more examples in [samples](https://github.com/Advance-Technologies-Foundation/clio-docs/tree/main/clio/Samples/Scenarios) - -# Installation of Creatio using Clio - -Clio provides functionality to install Creatio on a local machine using a zip file or an unzipped folder. - -> Supported Net6 and NetFramework platforms with MsSql or PostgreSQL databases - -Here's how you can do it: - -# Prepare Infrastructure -To simply installation of dependencies, clio provides deployment files for -Microsoft SQL, Postgres, and Redis server in your local Kubernetes cluster. -To create an empty cluster, we recommend using [Rancher Desktop](https://rancherdesktop.io), however there are other alternatives. - -> If you already have running MSSQL/PostgresSQL/Redis servers on you local machine you have to configure kubernetes services ports to avoid collisions. Reffer to services.yaml in related directories - -## Manage required Windows features - -To manage required windows features execute command - -```bash - -# check -clio manage-windows-features -c - -# install -clio manage-windows-features -i - -# uninstall -clio manage-windows-features -u - -``` - -## Install [Rancher Desktop](https://rancherdesktop.io) and configure resources -On Windows configure resources with [.wlsconfig](https://learn.microsoft.com/en-us/windows/wsl/wsl-config) file. -Sample config: -``` -[wsl2] -memory=8GB # Limits VM memory in WSL 2 to 16 GB -processors=4 # Makes the WSL VM use 8 virtual processors -``` - -## Generate deployment scrips -```bash -clio create-k8-files -``` -Review files in `C:\Users\YOUR_USER\AppData\Local\creatio\clio\infrastructure` folder. -Things to review: -- `mssql-stateful-set.yaml` - make sure that `resources` section has correct values. Values will depend on your PC's hardware. -- `mssql-stateful-set.yaml` - make sure you agree with terms and conditions of Microsoft SQL Server Developer Edition. -- `mssql-stateful-set.yaml` - will try to allocate 20Gb of disk space for database files. Make sure you have enough space on your disk. -- `postgres-stateful-set.yaml` - make sure that `resources` section has correct values. Values will depend on your PC's hardware. -- `postgres-stateful-set.yaml` - will try to allocate 40Gb of disk space for database files and 5Gb for backup files. Make sure you have enough space on your disk. - -Deploy necessary components by executing a series of commands from `C:\Users\YOUR_USER\AppData\Local\creatio\clio\` -or execute command to open directory -``` -clio open-k8-files -``` -```ps -# common -kubectl apply -f clio-namespace.yaml -kubectl apply -f clio-storage-class.yaml - -# redis -kubectl apply -f redis - -# mssql -kubectl apply -f mssql\mssql-volumes.yaml -kubectl apply -f mssql - -# postgresql -kubectl apply -f postgres\postgres-volumes.yaml -kubectl apply -f postgres -kubectl apply -f pgadmin -``` - - -## Prepare IIS Configuration and Launch -Clio will set up an IIS site, configure the relevant app pool, -and then launch Creatio in your default browser. -You can override default location in of an IIS folder in `appsetting.json` `iis-clio-root-path` property. - - -- Enable required [Windows components for NET Framework](https://academy.creatio.com/docs/user/on_site_deployment/application_server_on_windows/check_required_components/enable_required_windows_components) -- Enable required [Windows components for .NET 6](https://academy.creatio.com/docs/user/on_site_deployment/application_server_on_windows/check_required_components/enable_required_windows_components#title-252-3) - -For automated check you can execute command -```bash -clio check-windows-features -``` - -## Run Creatio Installation - -To get a Windows (only) context menu for `.zip` file execute -```ps - clio register -``` - -You may need to close all Explorer windows and open them again. Find Creatio installation `zip` file and right-click on it. -You should see `clio: deploy Creatio` menu item. Click on the menu item and follow the prompts. -You may need _**Administrator**_ privileges. -> Other OS use command to install Creatio -```bash - clio deploy-creatio --ZipFile -``` - -## Technical details - -Clio will automatically determine if the zip file is stored remotely. -If the file isn't on your local machine, Clio will copy it to a predefined local working folder location, -You can change the default location in `appsetting.json` file `creatio-products` property. -To see your `appsetting.json` file execute -```bash -clio cfg open -``` -If the zip file already exists in your working directory, Clio will skip this step. - -### For IIS deployment -Make sure that iis working directory defined in `appsettings.json` file `iis-clio-root-path` has allow `Full Control` for IIS_IUSRS - -![](https://academy.creatio.com/sites/en/files/documentation/sdk/en/BPMonlineWebSDK/Screenshots/WorkingWithIDE/permissions.png) - -### Extracting the Zip File -Clio will extract the zip file to the same directory where the original zip file is located. -If the folder already exists, Clio will skip this step. - - -### Constructing the Connection String -The connection string will be generated based on your existing cluster configuration. - - -### Database Restoration -Initially, the backup file will be copied to a folder that is accessible by the database server. -Scripts suitable for both Microsoft SQL and Postgres deployment within a Kubernetes cluster are provided. -Clio will then search for a fitting server within the `clio-infrastructure` namespace in Kubernetes and -copy files as needed. -Once files are copied, Clio will proceed to restore the database. -By default, database will be available on default port - -- Postgres: localhost:5432 (root/root) -- PG Admin: localhost:1080 (root@creatio.com/root) -- MSSQL: localhost:5432 (sa/$Zarelon01$Zarelon01) - -> Postgres - clio will create a template database, and then a real database from the template. If Database or template already exists, Clio will skip this step. - -> You can change port and secrets in configuration files `C:\Users\YOUR_USER\AppData\Local\creatio\clio\infrastructure` - - -## Restore database for Creatio environments - -To restore database for Creatio environments, you can use the next command: - -```bash -clio restore-db --db-name mydb10 --db-working-folder --backup-file --db-server-uri mssql://USERNAME:PASSWORD@127.0.0.1:1433 -#use --force to overwrite existing database without prompt -``` - -You can register db-servers in clio config file (`appsetting.json`) see example below - -```json - "dbConnectionStringKeys" : { - "k8-mssql": { - "uri": "mssql://username:password@127.0.0.1:1433", - "workingFolder" : "\\\\wsl.localhost\\rancher-desktop\\mnt\\clio-infrastructure\\mssql\\data" - } - } -``` -To link environment with a db server use `DbServerKey` property in environment settings. -You can also specify `DbName` and `BackupFilePath` properties to simplify command. -```json - "Environments": { - "apollo-bundle-framework": { - ... OTHER PROPERTIES ... - "DbServerKey": "k8-mssql", - "DbName": "mydb10", - "BackupFilePath": "D:\\Projects\\CreatioProductBuild\\8.1.2.2482_Studio_Softkey_MSSQL_ENU\\db\\BPMonline812Studio.bak" - } - }, - "dbConnectionStringKeys" : { - "k8-mssql": { - "uri": "mssql://username:password@127.0.0.1:1433", - "workingFolder" : "\\\\wsl.localhost\\rancher-desktop\\mnt\\clio-infrastructure\\mssql\\data" - } - } -``` - -```bash -clio resrore-db -e -``` - -## Uninstall Creatio - -Uninstall Creatio from your local machine by executing the following command: - -```bash -clio uninstall-creatio -e -``` +## Commands Reference +[Explore clio commands](clio/Commands.md) diff --git a/clio.tests/Command/ReadmeChecker.cs b/clio.tests/Command/ReadmeChecker.cs index f8def4b..729621c 100644 --- a/clio.tests/Command/ReadmeChecker.cs +++ b/clio.tests/Command/ReadmeChecker.cs @@ -12,7 +12,7 @@ public class ReadmeChecker private readonly string _readmeContent = File.ReadAllText(ReadmeFilePath); private readonly IEnumerable _wikiAnchorsContent = File.ReadAllLines(WikiAnchorsFilePath); - private const string ReadmeFilePath = @"..\..\..\..\README.md"; + private const string ReadmeFilePath = @"..\..\..\..\clio\Commands.md"; private const string WikiAnchorsFilePath = @"..\..\..\..\clio\Wiki\WikiAnchors.txt"; private readonly Func _convertCommandNameToSection = (commandName) => { diff --git a/clio/Command/MockDataCommand.cs b/clio/Command/MockDataCommand.cs index 4f93e73..160fd4b 100644 --- a/clio/Command/MockDataCommand.cs +++ b/clio/Command/MockDataCommand.cs @@ -10,7 +10,7 @@ namespace Clio.Command; -[Verb("mock-dataFolderPath", Aliases = new[] {"dataFolderPath-mock"}, HelpText = "Build package command")] +[Verb("mock-dataFolderPath", Aliases = new[] {"dataFolderPath-mock"}, HelpText = "Setup mock data path")] public class MockDataCommandOptions : RemoteCommandOptions { diff --git a/clio/Commands.md b/clio/Commands.md new file mode 100644 index 0000000..7454e13 --- /dev/null +++ b/clio/Commands.md @@ -0,0 +1,1328 @@ +Clio Command Reference +====================== +## In this article + +- [Arguments](#command-arguments) +- [Help and examples](#help-and-examples) +- [Package Management](#package-management) +- [NuGet Packages](#nuget-packages) +- [Application Management](#application) +- [Environment settings](#environment-settings) +- [Development](#development) +- [Using for CI/CD systems](#using-for-cicd-systems) +- [GitOps](#gitops) +- [Installation of Creatio](#installation-of-creatio-using-clio) + +# Running Clio +The general syntax for running clio: +```bash +clio [arguments] [command_options] +``` +Where `` is clio command name, use [help](#help) to get list of available commands. `[arguments]` are values relevant to running the command, `[command_options]` behavior modifiers starting with `-` minus symbol. + +## Command arguments +- `` - package name +- `` - environment name +- `` - item name + +## Environment options + +- `-u`, `--uri` (optional): Application URI. +- `-p`, `--Password` (optional): User password. +- `-l`, `--Login` (optional): User login (administrator permission required). +- `-i`, `--IsNetCore` (optional, default: `null`): Use NetCore application. +- `-e`, `--Environment` (optional): Environment name. +- `-m`, `--Maintainer` (optional): Maintainer name. +- `-c`, `--dev` (optional): Developer mode state for environment. +- `--WorkspacePathes` (optional): Workspace path. +- `-s`, `--Safe` (optional): Safe action in this environment. +- `--clientId` (optional): OAuth client ID. +- `--clientSecret` (optional): OAuth client secret. +- `--authAppUri` (optional): OAuth app URI. +- `--silent` (optional): Use default behavior without user interaction. +- `--restartEnvironment` (optional): Restart environment after executing the command. +- `--db-server-uri` (optional): DB server URI. +- `--db-user` (optional): Database user. +- `--db-password` (optional): Database password. +- `--backup-file` (optional): Full path to backup file. +- `--db-working-folder` (optional): Folder visible to DB server. +- `--db-name` (optional): Desired database name. +- `--force` (optional): Force restore. + +## Item options + +- `-d`, `--DestinationPath` (optional): Path to the source directory. Default is `null`. +- `-n`, `--Namespace` (optional): Namespace for service classes. Default is `null`. +- `-f`, `--Fields` (optional): Required fields for the model class. Default is `null`. +- `-a`, `--All` (optional, default: `true`): Create all models. +- `-x`, `--Culture` (optional, default: `en-US`): Description culture. + +# Help and examples + - [Help](#help) + - [Version](#ver) + +## help + +To display available commands use: + +``` +clio help +``` + +To display command help use: + +``` +clio --help +``` + +# + +Get versions of all known components +```bash +clio ver +``` + +Get current clio version +```bash +clio ver --clio +``` + +Get current cliogate version +```bash +clio ver --gate +``` + +Get dotnet runtime that executes clio +```bash +clio ver --runtime +``` + +# Package Management + - [Create a new package](#new-pkg) + - [Add a new package to workspace](#add-package) + - [Install package](#push-pkg) + - [Compile package](#compile-package) + - [Pull package from remote application](#pull-pkg) + - [Delete package](#delete-pkg-remote) + - [Compress package](#generate-pkg-zip) + - [Extract package](#extract-package) + - [Restore configuration](#restore-configuration) + - [Get package list](#get-pkg-list) + - [Set package version](#set-pkg-version) + - [Set application version](#set-app-version) + - [Set application icon](#set-app-icon) + +## new-pkg + +To create a new package project, use the next command: + +``` + clio new-pkg +``` + +you can set reference on local core assembly by using Creatio file design mode with command in Pkg directory + +``` + clio new-pkg -r bin +``` + +## add-package +When creating package with option -a True then an `app-descriptor.json` will be created. +All subsequent packages will be added to `app-descriptor.json`. +```bash +#To add package with app descriptor +clio add-package -a True + +#To add package without app descriptor +clio add-package -a False +``` + + +## push-pkg + +To install package from directory, you can use the next command: +for non-compressed package in current folder + +``` +clio push-pkg +``` + +or for .gz packages you can use command: + +``` +clio push-pkg package.gz +``` + +or with full path + +``` +clio push-pkg C:\Packages\package.gz +``` + +for get installation log file specify report path parameter + +``` +clio push-pkg -r log.txt +``` + +install one or more applications from marketplace.creatio.com + +``` +clio push-pkg --id 22966 10096 +``` + +> [!IMPORTANT] +> When you work with packages from Application Hub, you need use command push-app with same parameters like push-pkg. For example + +``` +clio push-app C:\Packages\package.gz +``` + +## compile-package + +To compile package + +``` +clio compile-package + +//or + +clio compile-package -e +``` + +## pull-pkg + +To download package to a local file system from application, use command: + +``` +clio pull-pkg +``` + +for pull package from non default application + +``` +clio pull-pkg -e +``` + +Applies to Creatio 7.14.0 and up + +## delete-pkg-remote + +To delete a package, use the next command: + +``` +clio delete-pkg-remote +``` + +for delete for non default application + +``` +clio delete-pkg-remote -e +``` + +## generate-pkg-zip + +To compress package into *.gz archive for directory which contains package folder + +``` +clio generate-pkg-zip +``` + +or you can specify full path for package and .gz file + +``` +clio generate-pkg-zip C:\Packages\package -d C:\Store\package.gz +``` + +## extract-pkg-zip + +For package from *.gz archive + +``` +clio extract-pkg-zip .gz -d c:\Pkg\ +``` + +## restore-configuration + +Restore configuration + +``` +clio restore-configuration +``` +Restore configuration without rollback data + +``` +clio restore-configuration -d +``` + +Restore configuration without sql backward compatibility check + +``` +clio restore-configuration -f +``` + +## get-pkg-list + +To get packages list in selected environment, use the next command: + +``` +clio get-pkg-list +``` + +for filter results, use -f option + +``` +clio get-pkg-list -f clio +``` + +## set-pkg-version + +Set a specified package version into descriptor.json by specified package path. + +``` +clio set-pkg-version -v +``` + +## set-app-version + +Set a specified composable application version into application-descriptor.json by specified workspace or package path. + +``` +clio set-app-version -v + +// or + +clio set-app-versin -f -v + +``` + + +## set-app-icon + +The `set-app-icon` command is used to set the icon for a specified application +by updating the `app-descriptor.json` file. + +### Usage + +```bash +clio set-app-icon [options] +``` +-p, --app-name (required): The name or code of the application. +-i, --app-icon (required): The path to the SVG icon file to be set. +-f, --app-path (required): Path to application package folder or archive. + +Examples +Set the icon for an application with a specified name: + +```bash +clio set-app-icon -p MyAppName -i /path/to/icon.svg -f /path/to/app +``` + + +## pkg-hotfix + +Enable/Disable pkg hotfix mode. To see full description about Hot Fix mode visit [Creatio Academy](https://academy.creatio.com/docs/8.x/dev/development-on-creatio-platform/development-tools/delivery/hotfix-mode +) + +```bash + +# To enable hot-fix mode for a package +clio pkg-hotfix true -e + +# To disable hot-fix mode for a package +clio pkg-hotfix false -e + + +``` + +## Marketplace Catalog + +List marketplace applications +``` +clio catalog +``` + +List marketplace applications and highlight search words +``` +clio catalog -n Data +``` + +# NuGet Packages + - [Pack NuGet package](#pack-nuget-pkg) + - [Push NuGet package](#push-nuget-pkg) + - [Restore NuGet package](#restore-nuget-pkg) + - [Install NuGet package](#install-nuget-pkg) + - [Check packages updates in NuGet](#check-nuget-update) + +## pack-nuget-pkg + +To pack creatio package to a NuGet package (*.nupkg), use the next command: + +``` +pack-nuget-pkg [--Dependencies [:][,[:],...]>] [--NupkgDirectory ] +``` + +Default value of 'PACKAGE_VERSION' argument it's last package version. + +Default value of 'NupkgDirectory' argument it's current directory. + +## push-nuget-pkg + +To push NuGet package (*.nupkg) to a NuGet repository, use the next command: + +``` +push-nuget-pkg --ApiKey --Source +``` + +## restore-nuget-pkg + +To restore NuGet package (*.nupkg) to destination restoring package directory , use the next command: + +``` +restore-nuget-pkg [:] [--DestinationDirectory ] [--Source ] +``` + +Default value of 'PACKAGE_VERSION' argument it's last package version. + +Default value of 'DestinationDirectory' argument it's current directory. + +Default value of 'Source' argument: https://www.nuget.org/api/v2 + +## install-nuget-pkg + +To install NuGet package to a web application Creatio, use the next command: + +``` +clio install-nuget-pkg [:] [--Source ] +``` + +you can install NuGet package of last version: + +``` +clio install-nuget-pkg [--Source ] +``` + +for install several NuGet packages: + +``` +clio install-nuget-pkg [:][,[:],...]> [--Source ] +``` + +or you can install several NuGet packages of last versions: + +``` +clio install-nuget-pkg [,,...]> [--Source ] +``` + +Default value of 'PACKAGE_VERSION' argument it's last package version. + +Default value of 'Source' argument: https://www.nuget.org/api/v2 + +## check-nuget-update + +To check Creatio packages updates in a NuGet repository, use the next command: + +```bash +clio check-nuget-update [--Source ] +``` + +Default value of 'Source' argument: https://www.nuget.org/api/v2 + +# Application + - [Deploy application](#deploy-application) + - [Uninstall application](#uninstall-app-remote) + - [List installed applications](#get-app-list) + - [Upload Licenses](#lic) + - [Restart application](#restart-web-app) + - [Clear Redis database](#clear-redis-db) + - [Compile configuration](#compile-configuration) + - [Get compilation log](#last-compilation-log) + - [Set system setting](#set-syssetting) + - [Get system setting](#get-syssetting) + - [Features](#set-feature) + - [Set base web wervice url](#set-webservice-url) + +## download-app + +```bash +clio download-app -e +#or +clio download-app -e --FilePath +``` + +## deploy-application + +Deploy application from one environment to another + +```bash +clio deploy-application -e -d + +#or omit -e argument to take application from default environment + +clio deploy-app -d +```` + + + +## uninstall-app-remote + +To uninstall application, use the next command: + +``` +clio uninstall-app-remote +``` + + +## get-app-list + +The `get-app-list` command, also short alias as `apps`, +is used to list all the installed applications in the selected environment. +This command is useful when you want to check which applications are currently +installed in your Creatio environment. + +```bash +clio get-app-list + +#or + +clio apps +``` + +## Upload licenses + +To upload licenses to Creatio application, use the next command for default environment: + +```bash +clio lic +``` + +```bash +clio lic -e +``` + +## restart-web-app + +To restart Creatio application, use the next command for default environment: + +```bash +clio restart-web-app +``` + +or for register application + +```bash +clio restart-web-app +``` + +## clear-redis-db + +To clear Redis database for default application + +```bash +clio clear-redis-db +``` + +or non default application + +```bash +clio clear-redis-db +``` + +## compile-configuration + +For compile configuration + +```bash +clio compile-configuration +``` +or +```bash +clio compile-configuration +``` + +for compile all + +```bash +clio compile-configuration --all +``` + +## last-compilation-log + +Get last compilation log. Requires CanManageSolution operation permission + +```bash +# Display last compilation log, in format similar to IDE +clio last-compilation-log -e +``` + +```bash +# Display raw output (json) +clio last-compilation-log -e --raw +``` + +```bash +# Save creatio compilation log to file, +# --log option can be used jointly with --raw +clio last-compilation-log -e --log "C:\log.txt" +``` + +## set-syssetting + +To set system settings value + +```bash +clio set-syssetting +``` + +## get-syssetting + +To read system settings value + +```bash +get-syssetting --GET -e +``` + +## set-feature + +To enable feature + +```bash +clio set-feature 1 +``` + +To disable feature + +```bash +clio set-feature 0 +``` + +To specify User or Role, use SysAdminUnitName options + +```bash +clio set-feature 1 --SysAdminUnitName Supervisor +``` + +## set-webservice-url + +To configure a base url of a web service, in an environment use the following command. +It may be useful when you need to change the base url of a web service in a development or +testing environment. + +```bash +clio set-webservice-url -e + +``` + + +# Environment settings + - [Create/Update an environment](#createupdate-an-environment) + - [Delete the existing environment](#delete-the-existing-environment) + - [Check environment](#check-environment) + - [View application options](#view-application-options) + - [Open application](#open-application) + - [Ping application](#ping-application) + - [Clone environment](#clone-environment) + - [Healthcheck](#healthcheck) + +Environment is the set of configuration options. It consist of name, Creatio application URL, login, and password. See [Environment options](#environment-options) for list of all options. + +## Create/Update an environment + +Register new application settings + +```powershell +clio reg-web-app -u https://mysite.creatio.com -l administrator -p password +``` + +or update existing settings + +```bash +clio reg-web-app -u administrator -p password +``` + +## Set the active environment +``` +clio reg-web-app -a +``` + +## Delete the existing environment + +```bash +clio unreg-web-app +``` + +## Check environment + +For validation existing environment setting you can use ping command + +```bash +clio ping +``` + +## View application options + +For view list of all applications + +```bash +clio show-web-app-list +``` + +or for concrete application + +```bash +clio show-web-app +``` + +## Open application + +For open selected environment in default browser use (Windows only command) + +```bash +clio open +``` + +## Ping application + +For check options fort selected environment use next command + +```bash +clio ping +``` + +## Clone environment + +For clone environment use next command. + +```bash +clio clone-env --source Dev --target QA --working-directory [OPTIONAL PATH TO STORE] +``` + +The command creates a manifest from the source and target, calculates the difference between them, downloads the changed package from the source environment to the working directory (optional parameter), and installs it in the source environment. + + +## Healthcheck + +Check application health + + +```bash +clio hc +``` + +```bash +clio healthcheck -a true -h true +``` + +```bash +clio healthcheck --WebApp true --WebHost true +``` + +## Get Creatio Platform Info + +This command is designed to retrieve information about the Creatio instance, version, +underlying runtime and database type and product name. + +```bash +clio get-info -e + +//OR + +clio get-info +```` + +# Development + - [Create workspace](#create-workspace) + - [Restore workspace](restore-workspace) + - [Convert package](#convert) + - [Execute assembly](#execute-assembly-code) + - [References](#ref-to) + - [Execute custom SQL script](#execute-custom-sql-script) + - [Execute dataservice request](#dataservice) + - [Add item](#add-item) + - [Add schema](#add-schema) + - [Link Workspace to File Design Mode](#link-workspace-to-file-design-mode) + - [Mock data for Unit Tests](#mock-data-for-unit-tests) +## Workspaces + +For connect professional developer tools and Creatio no-code designers, you can organize development flow in you local file system in **workspace.** + +https://user-images.githubusercontent.com/26967647/166842902-566af234-f9ad-48fb-82c1-0a0302bc5b3c.mp4 + +## create-workspace + +Create workspace in local directory, execute create-workspace command + +```bash +C:\Demo> clio create-workspace +``` + +In directory **.clio** specify you packages + +Create workspace in local directory with all editable packages from environment, execute create-workspace command with argument -e + +```bash +C:\Demo> clio create-workspace -e demo +``` + +Create workspace in local directory with packages in app, execute create-workspace command +To get list of app codes execute `clio lia -e ` + +```bash +C:\Demo> clio create-workspace --AppCode +``` + +## restore-workspace + +Restore packages in you file system via command from selected environment + +```powershell +clio restore-workspace -e demo +``` + +Workspace supports Package assembly. Clio creates, ready to go solution that you can work on +in a professional IDE of your choice. To open solution execute command + +```powershell +OpenSolution.cmd +``` + +## push-workspace + +Push code to an environment via command, then work with it from Creatio + +```bash +clio push-workspace -e demo +``` + +**IMPORTANT**: Workspaces available from clio 3.0.1.2 and above, and for full support developer flow you must install additional system package **cliogate** to you environment. + +```bash +C:\Demo> clio install-gate -e demo +``` + +## convert + +```bash +clio convert +``` + +## execute-assembly-code + +Execute code from assembly + +```bash +clio execute-assembly-code -f myassembly.dll -t MyNamespace.CodeExecutor +``` + +## ref-to + +Set references for project on src + +```bash +clio ref-to src +``` + +Set references for project on application distributive binary files + +```bash +clio ref-to bin +``` + +## Execute custom SQL script + +Execute custom SQL script on a web application + +```bash +execute-sql-script "SELECT Id FROM SysSettings WHERE Code = 'CustomPackageId'" +``` + +Executes custom SQL script from specified file + +```bash +execute-sql-script -f c:\Path to file\file.sql +``` + +## DataService + +Execute dataservice requests on a web application. + +| Key | Value | Description | +|:---:|:------------------------|:-------------------------------------------------------| +| -t | Operation Type | One of [select, insert, update, delete] | +| -f | Input filename | File in json format that contains request payload | +| -d | Output filename | File where result of the operation will be saved | +| -v | Variables to substitute | List of key-value pairs to substitute in an input file | + +Execute dataservice request with variable substitution. +```json +{ + "rootSchemaName": "{{rootSchemaName}}", + "operationType": 0, + "includeProcessExecutionData": true, + "columns": { + "items": { + "Id": { + "caption": "", + "orderDirection": 0, + "orderPosition": -1, + "isVisible": true, + "expression": { + "expressionType": 0, + "columnPath": "{{IdVar}}" + } + } + } + } +} +``` + +``` +clio ds -t select -f SelectAllContacts.json -d SelectAllContacts_Result.json -v rootSchemaName=Contact;IdVar=Id +``` + +## Add item +Create item in project +``` +clio +``` + +Add web service template to project +``` +clio add-item service test +``` + +Add entity-listener template to project +```bash +clio add-item entity-listener test +``` + +Generate AFT model for `Contact` entity with `Name` and `Email` fields, set namespace to `MyNameSpace` and save to `current directory` +```bash +clio add-item model Contact -f Name,Email -n MyNameSpace -d . +``` + +Generate ATF models for `All` entities, with comments pulled from description in en-US `Culture` and set `ATF.Repository.Models` namespace and save them to `C:\MyModels` +```bash +add-item model -n "" -d +``` + +To generate all models in current directory +```bash +add-item model -n "" +``` + +OPTIONS + +| Short name | Long name | Description | +|:-------------|:----------------|:-----------------------------------------------| +| d | DestinationPath | Path to source directory | +| n | Namespace | Name space for service classes and ATF models | +| f | Fields | Required fields for ATF model class | +| a | All | Create ATF models for all Entities | +| x | Culture | Description culture | + +## Add Schema +Adds cs schema to a project + +```bash +clio add-schema -t source-code -p +```` + +## Switch Nuget To Dll Reference + +The `switch-nuget-to-dll-reference` command is a vital tool for managing NuGet package references, +especially in scenarios where internet access is limited or unavailable. +This command is specifically designed to convert NuGet package references into direct dll +(Dynamic Link Library) references. + +### Use Case + +`switch-nuget-to-dll-reference` command, is beneficial when developing a package on for installation on Creatio +instance that lacks internet connectivity. Command converts `[PackageReference]` into local DLLs, +This facilitates seamless package installation and operation in offline environments. + +Lear more about [PackageReference] and [Reference] in Microsoft documentation. + +[PackageReference]: https://learn.microsoft.com/en-us/nuget/consume-packages/package-references-in-project-files +[Reference]: https://learn.microsoft.com/en-us/visualstudio/msbuild/common-msbuild-project-items?view=vs-2022#reference + +### How to Use +```bash +clio switch-nuget-to-dll-reference + +#or + +clio nuget2dll +``` + +## Link Workspace to File Design Mode + +To connect your package from workspace to local system in file design mode use command +``` +clio link-from-repository --repoPath {Path to workspace packages folder} --envPkgPath {Path to environment package folder ({LOCAL_CREATIO_PATH}Terrasoft.WebApp\\Terrasoft.Configuration\\Pkg)} +``` +
+Link all packages from repository + +```ps +clio l4r -e ({LOCAL_CREATIO_PATH}Terrasoft.WebApp\\Terrasoft.Configuration\\Pkg) -p * -r .\ +``` + +
+ + + +To connect your local system in file design mode use command to workspace +``` +clio link-to-repository --repoPath {Path to workspace packages folder} --envPkgPath {Path to environment package folder ({LOCAL_CREATIO_PATH}Terrasoft.WebApp\\Terrasoft.Configuration\\Pkg)} +``` + +## Mock data for unit tests + +To mock data for unit tests with using [ATF].[Repository] use the following command + +``` + +clio mock-data --models D:\Projects\MyProject --data D:\Projects\MyProject\Tests\TestsData -e MyDevCreatio + +``` + +# Using for CI/CD systems + +In CI/CD systems, you can specify configuration options when calling commands: + +``` +clio restart -u https://mysite.creatio.com -l administrator -p password +``` + +# GitOps + +- [Apply manifest to Creatio instance](#apply-manifest) +- [Create manifest from Creatio instance](#create-manifest) +- [Show difference in settings for two Creatio intances](#show-diff) +- [Automation scenarios](#run-scenario) + +To support GitOps approach clio provides yaml manifest file. This file has following structure to describes desired state of Creatio instance. +Example of manifest: + +```yaml +environment: + url: https://production.creatio.com + username: admin # or use OAuth token + password: password # or use OAuth token + clientid: "{client-id}" + clientsecret: "{client-secret}" + authappurl: https://production.creatio.com/0/ServiceModel/AuthService.svc/Login + platformversion: "8.1.1" + platformtype: "NET6" # "NET6" or "NETFramework" + +apps: + - name: CrtCustomer360 + version: "1.0.1" + apphub: MyAppHub + - name: CrtCaseManagment + version: "1.0.2" + apphub: CreatioMarketplace + +syssettings: + - name: SysSettings1 + value: Value1 + - name: SysSettings2 + value: Value2 + +features: + - name: Feature1 + enabled: "true" + - name: Feature2 + enabled: "false" + +webservices: + - name: WebService1 + url: "https://preprod.creatio.com/0/ServiceModel/EntityDataService.svc" + - name: WebService2 + url: "https://preprod.creatio.com/0/ServiceModel/EntityDataService.svc" + +app_hubs: + - name: MyAppHub + path: "//tscrm.com/dfs-ts/MyAppHub" + - name: CreatioMarketplace + url: "https://marketplace.creatio.com/apps" + +``` + +## apply-manifest + +To apply manifest to your Creatio instance use the following command + +``` + +clio apply-manifest "D:\manifest\myinstance-creatio-manifest.yaml" -e MyInstance + +``` + +## save-state + +To control changes of an instance download state to manifest file and store it in Git. To download state use the following command + +``` +clio save-state "D:\manifest\myinstance-creatio-manifest.yaml" -e MyInstance +``` + +## show-diff + +To compare two Creatio instances and show it use the following command + +``` +clio show-diff --source production --target qa +``` + +To save diff manifest to file, specify arguments file + +``` +clio show-diff --source production --target qa --file diff-production-qa.yaml +``` + +## run-scenario +You can combine multiple commands into one scenario and execute it with +``` +clio run-scenario --file-name scenario.yaml +``` +Scenario consists of and steps and optional settings and/or secrets. +```yaml +secrets: + Login: real-login + Password: real-password + +settings: + uri: http://localhost:80 + +steps: + - action: restart + description: restart application + options: + uri: {{settings.uri}} + Login: {{secrets.Login}} + Password: {{secrets.Password}} +``` + +See more examples in [samples](https://github.com/Advance-Technologies-Foundation/clio-docs/tree/main/clio/Samples/Scenarios) + +# Installation of Creatio using Clio + - [Check Windows features](#check-windows-features) + - [Manage Windows features](#manage-windows-features) + - [Generate deployment scripts](#create-k8-files) + - [Install Creatio](#deploy-creatio) + - [Uninstall Creatio](#uninstall-creatio) + +## check-windows-features + +For automated check of Windows features required for Creatio installation execute command +```bash +clio check-windows-features +``` +## manage-windows-features + +To manage Windows features required for Creatio installation execute command + +```bash + +# check +clio manage-windows-features -c + +# install +clio manage-windows-features -i + +# uninstall +clio manage-windows-features -u + +``` +## Installing Creatio using Clio + +Clio provides functionality to install Creatio on a local machine using a zip file or an unzipped folder. + +> Supported Net6 and NetFramework platforms with MsSql or PostgreSQL databases + +Here's how you can do it: + +### Prepare Infrastructure +To simply installation of dependencies, clio provides deployment files for +Microsoft SQL, Postgres, and Redis server in your local Kubernetes cluster. +To create an empty cluster, we recommend using [Rancher Desktop](https://rancherdesktop.io), however there are other alternatives. + +> If you already have running MSSQL/PostgresSQL/Redis servers on you local machine you have to configure kubernetes services ports to avoid collisions. Reffer to services.yaml in related directories + +### Install [Rancher Desktop](https://rancherdesktop.io) and configure resources +On Windows configure resources with [.wlsconfig](https://learn.microsoft.com/en-us/windows/wsl/wsl-config) file. +Sample config: +``` +[wsl2] +memory=8GB # Limits VM memory in WSL 2 to 16 GB +processors=4 # Makes the WSL VM use 8 virtual processors +``` + +## create-k8-files + +Generates deployment scripts +```bash +clio create-k8-files +``` +Review files in `C:\Users\YOUR_USER\AppData\Local\creatio\clio\infrastructure` folder. +Things to review: +- `mssql-stateful-set.yaml` - make sure that `resources` section has correct values. Values will depend on your PC's hardware. +- `mssql-stateful-set.yaml` - make sure you agree with terms and conditions of Microsoft SQL Server Developer Edition. +- `mssql-stateful-set.yaml` - will try to allocate 20Gb of disk space for database files. Make sure you have enough space on your disk. +- `postgres-stateful-set.yaml` - make sure that `resources` section has correct values. Values will depend on your PC's hardware. +- `postgres-stateful-set.yaml` - will try to allocate 40Gb of disk space for database files and 5Gb for backup files. Make sure you have enough space on your disk. + +Deploy necessary components by executing a series of commands from `C:\Users\YOUR_USER\AppData\Local\creatio\clio\` +or execute command to open directory + +## open-k8-files + +Opens folder with deployment scripts + +``` +clio open-k8-files +``` +```ps +# common +kubectl apply -f clio-namespace.yaml +kubectl apply -f clio-storage-class.yaml + +# redis +kubectl apply -f redis + +# mssql +kubectl apply -f mssql\mssql-volumes.yaml +kubectl apply -f mssql + +# postgresql +kubectl apply -f postgres\postgres-volumes.yaml +kubectl apply -f postgres +kubectl apply -f pgadmin +``` + + +### Prepare IIS Configuration and Launch +Prepare IIS Configuration and Launch. Clio will set up an IIS site, configure the relevant app pool, +and then launch Creatio in your default browser. +You can override default location in of an IIS folder in `appsetting.json` `iis-clio-root-path` property. + + +- Enable required [Windows components for NET Framework](https://academy.creatio.com/docs/user/on_site_deployment/application_server_on_windows/check_required_components/enable_required_windows_components) +- Enable required [Windows components for .NET 6](https://academy.creatio.com/docs/user/on_site_deployment/application_server_on_windows/check_required_components/enable_required_windows_components#title-252-3) + +For automated check you can execute command +```bash +clio check-windows-features +``` + +### Run Creatio Installation + +To get a Windows (only) context menu for `.zip` file execute +```ps + clio register +``` + +You may need to close all Explorer windows and open them again. Find Creatio installation `zip` file and right-click on it. +You should see `clio: deploy Creatio` menu item. Click on the menu item and follow the prompts. +You may need _**Administrator**_ privileges. +> Other OS use command to install Creatio + +## deploy-creatio + +```bash + clio deploy-creatio --ZipFile +``` + +## Technical details + +Clio will automatically determine if the zip file is stored remotely. +If the file isn't on your local machine, Clio will copy it to a predefined local working folder location, +You can change the default location in `appsetting.json` file `creatio-products` property. +To see your `appsetting.json` file execute +```bash +clio cfg open +``` +If the zip file already exists in your working directory, Clio will skip this step. + +### For IIS deployment +Make sure that iis working directory defined in `appsettings.json` file `iis-clio-root-path` has allow `Full Control` for IIS_IUSRS + +![](https://academy.creatio.com/sites/en/files/documentation/sdk/en/BPMonlineWebSDK/Screenshots/WorkingWithIDE/permissions.png) + +### Extracting the Zip File +Clio will extract the zip file to the same directory where the original zip file is located. +If the folder already exists, Clio will skip this step. + + +### Constructing the Connection String +The connection string will be generated based on your existing cluster configuration. + + +### Database Restoration +Initially, the backup file will be copied to a folder that is accessible by the database server. +Scripts suitable for both Microsoft SQL and Postgres deployment within a Kubernetes cluster are provided. +Clio will then search for a fitting server within the `clio-infrastructure` namespace in Kubernetes and +copy files as needed. +Once files are copied, Clio will proceed to restore the database. +By default, database will be available on default port + +- Postgres: localhost:5432 (root/root) +- PG Admin: localhost:1080 (root@creatio.com/root) +- MSSQL: localhost:5432 (sa/$Zarelon01$Zarelon01) + +> Postgres - clio will create a template database, and then a real database from the template. If Database or template already exists, Clio will skip this step. + +> You can change port and secrets in configuration files `C:\Users\YOUR_USER\AppData\Local\creatio\clio\infrastructure` + + +## Restore database for Creatio environments + +To restore database for Creatio environments, you can use the next command: + +```bash +clio restore-db --db-name mydb10 --db-working-folder --backup-file --db-server-uri mssql://USERNAME:PASSWORD@127.0.0.1:1433 +#use --force to overwrite existing database without prompt +``` + +You can register db-servers in clio config file (`appsetting.json`) see example below + +```json + "dbConnectionStringKeys" : { + "k8-mssql": { + "uri": "mssql://username:password@127.0.0.1:1433", + "workingFolder" : "\\\\wsl.localhost\\rancher-desktop\\mnt\\clio-infrastructure\\mssql\\data" + } + } +``` +To link environment with a db server use `DbServerKey` property in environment settings. +You can also specify `DbName` and `BackupFilePath` properties to simplify command. +```json + "Environments": { + "apollo-bundle-framework": { + ... OTHER PROPERTIES ... + "DbServerKey": "k8-mssql", + "DbName": "mydb10", + "BackupFilePath": "D:\\Projects\\CreatioProductBuild\\8.1.2.2482_Studio_Softkey_MSSQL_ENU\\db\\BPMonline812Studio.bak" + } + }, + "dbConnectionStringKeys" : { + "k8-mssql": { + "uri": "mssql://username:password@127.0.0.1:1433", + "workingFolder" : "\\\\wsl.localhost\\rancher-desktop\\mnt\\clio-infrastructure\\mssql\\data" + } + } +``` + +```bash +clio resrore-db -e +``` + +## Uninstall Creatio + +Uninstall Creatio from your local machine by executing the following command: + +```bash +clio uninstall-creatio -e +``` diff --git a/clio/Program.cs b/clio/Program.cs index d1e5a10..af60058 100644 --- a/clio/Program.cs +++ b/clio/Program.cs @@ -537,30 +537,33 @@ private static int ConvertPackage(ConvertOptions opts) { return Resolve().Convert(opts); } - - private static Type[] CommandOption = new[]{ + // Note: order of types in this array affets how the commands are listed in the 'clio help' output. + // Group commands by their purpose. + private static Type[] CommandOption = new[]{ + // Application management + typeof(RegAppOptions), + typeof(UnregAppOptions), + typeof(AppListOptions), typeof(ExecuteAssemblyOptions), typeof(RestartOptions), typeof(ClearRedisOptions), - typeof(RegAppOptions), - typeof(AppListOptions), - typeof(UnregAppOptions), + // Package management typeof(GeneratePkgZipOptions), + typeof(UnzipPkgOptions), typeof(PushPkgOptions), + typeof(PullPkgOptions), typeof(DeletePkgOptions), - typeof(ReferenceOptions), typeof(NewPkgOptions), + typeof(ReferenceOptions), typeof(ConvertOptions), typeof(RegisterOptions), typeof(UnregisterOptions), - typeof(PullPkgOptions), typeof(ExecuteSqlScriptOptions), typeof(InstallGateOptions), typeof(ItemOptions), typeof(DeveloperModeOptions), typeof(SysSettingsOptions), typeof(FeatureOptions), - typeof(UnzipPkgOptions), typeof(PingAppOptions), typeof(OpenAppOptions), typeof(PkgListOptions), @@ -582,6 +585,9 @@ private static int ConvertPackage(ConvertOptions opts) { typeof(AddPackageOptions), typeof(UnlockPackageOptions), typeof(LockPackageOptions), + typeof(DeactivatePkgOptions), + typeof(CompilePackageOptions), + // Development typeof(DataServiceQuerryOptions), typeof(RestoreFromPackageBackupOptions), typeof(CreateUiProjectOptions), @@ -607,11 +613,9 @@ private static int ConvertPackage(ConvertOptions opts) { typeof(CheckWindowsFeaturesOptions), typeof(ManageWindowsFeaturesOptions), typeof(CreateTestProjectOptions), - typeof(DeactivatePkgOptions), typeof(ListenOptions), typeof(ShowPackageFileContentOptions), typeof(SwitchNugetToDllOptions), - typeof(CompilePackageOptions), typeof(UninstallAppOptions), typeof(DownloadAppOptions), typeof(DeployAppOptions), @@ -622,17 +626,18 @@ private static int ConvertPackage(ConvertOptions opts) { typeof(PackageHotFixCommandOptions), typeof(PublishWorkspaceCommandOptions), typeof(GetCreatioInfoCommandOptions), - typeof(SetApplicationVersionOption), - typeof(ApplyEnvironmentManifestOptions), typeof(GetWebServiceUrlOptions), + typeof(ApplyEnvironmentManifestOptions), typeof(SaveSettingsToManifestOptions), typeof(CloneEnvironmentOptions), typeof(ShowDiffEnvironmentsOptions), typeof(MockDataCommandOptions), typeof(UninstallCreatioCommandOptions), typeof(AddSchemaOptions), + typeof(SetApplicationVersionOption), typeof(SetApplicationIconOption), typeof(LastCompilationLogOptions), + // General operations typeof(InstallTideCommandOptions) }; diff --git a/clio/WikiHelpViewer.cs b/clio/WikiHelpViewer.cs index d2fb515..0b504f6 100644 --- a/clio/WikiHelpViewer.cs +++ b/clio/WikiHelpViewer.cs @@ -41,7 +41,7 @@ private string GetWikiAnchor(string commandName) { return commandName; } - string baseUrl = "https://github.com/Advance-Technologies-Foundation/clio/blob/master/README.md"; + string baseUrl = "https://github.com/Advance-Technologies-Foundation/clio/blob/master/clio/Commands.md"; private string GetCommandHelpUrl(string commandName) { var wikiAnchor = GetWikiAnchor(commandName);