Management of the installed application

---

VSoft archITekt enables the mechanism of changing the configuration of an existing application. It is possible to change most parameters. Changes to the following parameters are not supported:

Parameter	Description
technicalName	The technical name of the environment.
pathProjectFolder	Project installation directory. Attention! Manual change possible - you need to manually move the project directory to a new location.
runtimeFolder	The directory where the application components are installed. Attention! Manual change possible - uninstall application components and change the value in the "default.runtime.json" file.
versionProvider	The type of version server..
applicationDbAuthentication	The method of authentication when connecting to databases.
dbServer	Database server address. Attention! Manual change is possible. To do this, move the databases and database users to the new server and change the entries in the files "project.json" (ProjectVersionServerServerInstance) and "default.runtime.json" (DatabaseServerInstance).
failoverCluster, failoverClusterGroup	The name of the failover cluster and the group (role) in which the application services are added. Note that it is possible to change this manually. To do this, uninstall the environment components (InstallOnPremises.ps1 script with the ClusterUninstall option), change the entries in the project.json file (FailoverCluster, FailoverClusterGroup) and restart the installation of the environment components.

Depending on the scope of changes in the environment, the environment components must be updated or reinstalled after running the update procedure. Reinstallation is required if the change made requires running system commands that change the configuration.

VSoft archITekt image update

Updating an already installed application to a new version of the platform is performed in the following steps:

1. A new version of VSoft archITekt image should be installed on all servers where application components (WWW, APP) are installed, as well as on the administrator's computer (in case the installation was performed remotely).
2. Run the component update script, which will automatically update the application:

cd "C:\Program Files\VSoft\archITekt\Images\[image name]"
.\InstallOnPremises.ps1 `
    -PathProjectFolder [environment directory] `
    -SetupCommand [command: ClusterInstallOrUpdate / or ClusterForceReinstall]

Updating the license file for the application

In the case of using a license delivered in the form of an XML file, it is stored in the [project directory]\License directory, from where it is copied into the directories of individual components during the installation/update of system components.

In order to update the license file you must:

1. Place the current license file in the [project directory]\License directory.
2. Run the procedure of updating the environment components.

Running the environment reconfiguration script

cd "C:\Program Files\VSoft\archITekt\Images\[image name]"
    .\Reconfigure.ps1 `
    -pathProjectFolder "[project directory]" `
    -envName "[(option) new environment name]" `
    -securityMode "[(option) a new type of security]" `
    -reservedPortsBlockBegin "[(option) start of a new reserved port area] "`
    -licenseFilePath "[(option) path to the file with the new environment license]" `
    -appServerFQDNAddress "[(option) new public name of the web server]" `
    -webServerFQDNAddress "[ (option) new public name of the application server]" `
    -targetAppServers "[(option) a new list of application servers on which the application is to be installed]" `
    -targetWebServers "[(option) a new list of web servers on which the application is to be installed]"
    -appServer_HttpsCertificate "[(option) new fingerprint of the application server certificate] "`
    -webServer_HttpsCertificate "[(option) new fingerprint of the web server certificate]" `
    -applicationCredentialPassword "[(option) new password for the domain user]"
    -configKeys "[(option) Hashtable containing changed or deleted parameters to be saved in the technical configuration]"
    -sensitiveConfigKeys "[(option) list of keys to be treated as sensitive from now on]"
    -notSensitiveConfigKeys "[(option) list of keys to stop being treated as sensitive]"
    -FeatureSSO "[(optional) enable/disable SSO (Single Sign On)]"
    -SecurityPassword "[(option) Environment security password]"
    -ResetDbPasswords [optional switch that performs database user password reset]
    -SetVipPasswords [(option) setting new passwords for users of the VIP provider]
    -ClusterServerCredential “[(option) provide credentials (PSCredential) for installation on the cluster - if the user running the script does not have administrator rights on the cluster machines]”
    -ServiceStartupType [(option) archITect service startup mode(“Automatic”, “AutomaticDelayedStart”, “Disabled”, “Manual”). Default value = “Automatic”]
    -UsePluginMySql [(option) whether to enable a plugin to connect to MySQL databases(“On”, “Off”). Default value = “Off”]
    -SecurityPassword “[(option) Environment security password]” `
    -NewSecurityPassword “[(option) New environment security password]” `
    -RemoveSecurityPassword “[(option) Remove environment configuration encryption]” `
    -LockedImageVersion [(option) block image version substitution (“On”, “Off”). Default value = “Off”]
    -WhatIf [(option) validates parameters, does not run environment creation operation]

When running the reconfiguration script, the only parameter that must be specified is the project (environment) directory. We provide the other parameters only when we want to change a given option.

Below is a list of optional parameters with a description. The "Reinstallation" column shows whether the environment components have to be reinstalled.

Reinstallation:

1. it is not required when the change concerns only the application configuration,
2. is required when the change requires running a series of system commands to reconfigure the component.

Parameter	Description	Reinstallation
envName	The name of the environment presented on the application login page. It can contain any set of characters.	No
securityMode	Type of protection for the application being installed. Acceptable values are: • SSL, • NONE. If the value of SSL is specified, communication with the WWW application and WebServices will be secured with SSL certificates (you will be required to provide the fingerprints of the certificates).	Yes
reservedPortsBlockBegin	First of the range of ports used for internal application needs: • The application uses 2 ports (reservedPortsBlockBegin, reservedPortsBlockBegin+1) for communication between components. Traffic between servers on these ports must be open. • The application uses consecutive ports (reservedPortsBlockBegin+2 and next) to run LibreOffice in the server mode (communication with these ports takes place only within the server). The number of ports used is equal to the number of running LibreOffice converters.	Yes
licenseFilePath	The path to the license file for this environment. The operation copies the file to the [project directory]\Licenses directory (it does not remove old license files from the directory).	No
appServerFQDNAddress	The name under which the environment application servers will be available on the network. The name must match the name given in the certificate indicated in the appServer_HttpsCertificate variable.	Yes
targetWebServers	The name under which the environment's web servers will be available on the network. The name must match the name given in the certificate indicated in the variable webServer_HttpsCertificate	Yes
applicationCredentialPassword	New user password in case of domain login.	Yes
configKeys	Hash table containing variable names with values that will be completed in the application configuration (the application configuration mechanism is described in the next chapter of this documentation). The parameter should be as follows: @{"variable 1 name" = "variable 1 value";"variable 2 name" = "variable 2 value";e.t.c.} Example of a call: -configKeys @{"common.connection.provider_ad" = "LDAP: //my.server.local: 389"; "custom.myvariable" = "specific value"} For the needs of complicated implementation cases, the possibility of setting other parameter values has been made available only for selected NODEs. For this purpose, the value variable name@node name should be entered as the variable name. Values of sensitive keys are stored encrypted and are not written to the script log. See: Sensitive keys.	Yes
sensitiveConfigKeys	List of names of configuration keys to be treated as sensitive from now on: their values in the project files are encrypted, and on the next update of the components they are written to the CONFIG_KEYS table with the CK_SENSITIVE flag = 1. The key may already have a value in the project or get one in the same call in the configKeys parameter. Give key names only, without a node. Example of a call: sensitiveConfigKeys "custom.api.token" Details: Sensitive keys.	No
notSensitiveConfigKeys	List of names of configuration keys to stop being treated as sensitive: their values in the project files are decrypted (for all nodes), and on the next update of the components the CK_SENSITIVE flag is cleared. A key that is sensitive by definition, or a key also given in sensitiveConfigKeys, is not allowed.	No
FeatureSSO	The parameter determines whether the SSO (Single Sign On) login functionality should be enabled in the application. Valid values: "On", "Off".	Yes
ResetDbPasswords	Using this parameter causes resetting (generating new) user and application administrator passwords.	No
SetVipPasswords	Enables emergency change of passwords for VIP users. We provide user data and new passwords in the form of Hash Table: @{"user1" = "newPassword1"; "user2" = "newPassword2"} The password change operation sets the password validity to 30 days from the date of change, resets the count of allowable invalid logins to 4, and resets the count of allowable logins after password expiration to 4.	No
SecurityPassword	The current security password with which the technical configuration of a given environment is encrypted.	No
ClusterServerCredential	Cluster administrator credentials - in case the installation/reconfiguration is performed by a user who does not have administrative rights on the cluster. This is an object of type System.Management.Automation.PSCredential	Yes
ServiceStartupType	The way to start archITekt services. Possible values: “Automatic”, ‘AutomaticDelayedStart’, ‘Disabled’, ‘Manual’. Failure to specify the parameter value will install services with the value “Automatic”. Attention: In case of installation on a failover cluster, selecting the value “Automatic”, “AutomaticDelayedStart” will be changed to the value “Manual” during installation.	Yes
NewSecurityPassword	New, changed security password to encrypt technical configuration on the environment. The values of sensitive keys are re-encrypted with the new password in both project files (project.json, custom.project.json) and in the CONFIG_KEYS table; if the environment had no security password so far, the values of sensitive keys get encrypted.	Yes
RemoveSecurityPassword	Using this switch decrypts the technical configuration of the environment, including the values of sensitive keys (the keys stay marked as sensitive).	Yes
UsePluginMySql	Enable the plugin to connect to MySQL databases. Selecting the value “On”, requires the installation of the MySQL plugin to be selected during the installation of the archITect image. Possible values: “On”, ‘Off’. Not specifying the value of the parameter will install services with the value “Off”.	No
LockedImageVersion	Blocks/unblocks the ability to update the image for this environment. Possible values: “On”, ‘Off’.	No
WhatIf	By adding this switch to the script parameters we change the way the script works - the script execution will be aborted immediately after the parameter verification phase independently of its result. Use of this parameter allows to verify the correctness of the parameters used to reconfigure the environment without running the actual reconfiguration.

Example of a script with parameters:

cd "C:\Program Files\VSoft\archITekt\Images\dev"
.\Reconfigure.ps1 `
        -pathProjectFolder " C:\VSoft\Projects\SAMPLE1" `
        -envName "My new name" `
        -reservedPortsBlockBegin "49000" `
        -securityMode NONE `
        -licenseFilePath "C:\My.new.license.xml" `
        -configKeys "{ `"custom.myvariable`": `"specyfic value`" }" `
        -sensitiveConfigKeys "custom.api.token" `
        -FeatureSSO "On" `
        -ResetDbPasswords `
        -SetVipPasswords @{ "admin": "newpassword" }

After running the reconfiguration script, run the environment update script. You can use ClusterInstallOrUpdate or ClusterForceReinstall command for this purpose.

The script verifies the integrity of the project configuration, and in case of detecting changes that require reinstallation - it does it automatically.

cd "C:\Program Files\VSoft\archITekt\Images\[nazwa obrazu]"
.\InstallOnPremises.ps1 `
    -PathProjectFolder [katalog środowiska] `
    -SetupCommand [komenda: ClusterInstallOrUpdate / lub ClusterForceReinstall]

warning

If, as part of the configuration changes, any server has been removed from both app and web server groups, you must manually uninstall the application components on it by running the script uninstalling the application components. :cd "C:\VSoft\[technicalName]\" .\UninstallOnPremisesComponents.ps1

PackageImport – Implementation of a new version of the application

In order to deploy the new version of the application to the environment, the PackageImport.ps1 script is called.

The way of calling the script:

cd "C:\Program Files\VSoft\archITekt\Images\[ image name]"
    .\PackageImport.ps1 `
    -PathProjectFolder - [path to the application folder]
    -PackagePath - [path to the package with the new version of the application]
    -SecurityPassword [(option)security password]
    -Override [(option)overwrite with a completely new version]

Parameters:

1. PathProjectFolder – project (environment) directory.
2. PackagePath – path to the package - archive with the new application version.
3. SecurityPassword - environment security password (required if the environment uses an encrypted technical configuration).
4. Override - this option overwrites the application version by deleting all existing definitions before performing the import. The behavior is similar to selecting the Replace current version option when importing files from VSoft arhcITekt Launcher. See: Importing files into a project.

warning

After executing the procedure of uploading a new version of the application to the project, update the application components (using the InstallOnPremise.ps1 script with the Upgrade/ClusterUpgrade parameter).

Example of a script with parameters:

cd "C:\Program Files\VSoft\archITekt\Images\dev"
    .\PackageImport.ps1 `
    -PathProjectFolder "C:\VSoft\Projects\SAMPLE1" `
    -PackagePath – "C:\MyApplication\_v1.0.1.arch.zip"

Removal of the project

Running the DestroyProject.ps1 script removes the project databases from the database server and project components from the cluster.

The way of calling the script:

cd "C:\Program Files\VSoft\archITekt\Images\[ image name]"
    .\ DestroyProject.ps1 `
    -PathProjectFolder [path to the application folder]
    -dbUser [(option) database server user]
    -dbPassword [(option) database server user]
    -clusterServerCredential "[(option) providing credentials (PSCredential) for installation on the cluster - if the user running the script does not have administrator rights on the cluster machines]"
    -force [optional switch]

Parameters:

1. PathProjectFolder – project (environment) directory.
2. dbUser, dbPassword – database server username and password. In the case of domain login, these parameters should not be specified.
3. ClusterServerCredential - cluster administrator credentials - given when the installation is performed by a user who does not have administrative rights on the cluster. This is an object of type System.Management.Automation.PSCredential.
4. Force – using this switch causes the deletion procedure of the project to continue even if there is no connection to some of its components (e.g. any of the servers, or the database server). In such a case, you may be required to later manually remove the components that failed to be removed automatically.

tip

Good to know:

The script that removes the project triggers the uninstallation of components on the servers where the application is installed. In case of problems in connecting to a particular server, you can remove components from the server by running the UninstallOnPremisesComponents.ps1 script located in the application directory on the servers.

Running the UninstallOnPremisesComponents.ps1 script is possible both before and after calling the project removal operation.

If there are problems with the removal of the project's database objects, you can remove them manually. These are: databases with the project prefix "technicalName_" and logins with the prefix "technicalName_" (or logins for the application's domain users, if this mode was used)

Example of a script with parameters:

cd " C:\Program Files\VSoft\archITekt\Images\dev"
    .\ DestroyProject.ps1 `
    -PathProjectFolder "C:\VSoft\Projects\SAMPLE1" `
    -dbUser "superadmin" `
    -dbPassword "superadmin_password"

Project repair

Running the Repair.ps1 script restores the missing project databases. The script is mainly applicable on development/testing environments, where for any reason we want to remove a database and replace it with a new one. The script analyzes which environment databases are missing and restores them. The script does not interfere with existing databases.

The way to call the script:

cd “C:Program Files\VSoft\ITekt\Images[image name]”.
    .-Repair.ps1 `.
    -PathProjectFolder [path to application folder].
    -dbUser [(option) database server user].
    -dbPassword [(option) database server user].
    -elasticPoolName “[(option) pool name if installed on Azure SQL]” 
    -initialAdminUser “[environment administrator name]”
    -initialAdminPassword “[environment administrator password]”
    -SecurityPassword “[(option) Environment security password]”
    -WhatIf [(option) validates parameters, does not start environment creation operation].

Parameters:

1. PathProjectFolder – project (environment) directory.
2. dbUser, dbPassword – user and password of the database server. In case of domain login, do not specify these parameters.
3. elasticPoolName – the name of the pool if installed on Azure SQL.
4. initialAdminUser, initialAdminPassword – required if you are recreating a VIP database on a non-developer environment.
5. Security password - Security password.
6. WhatIf - by adding this switch to the parameters of the script, we change the way the script works - the execution of the script will be terminated immediately after the parameter verification phase regardless of its result. Using this parameter allows you to verify that the environment is ready for installation before running the actual installation.

An example of a script with parameters:

cd " C:\Program Files\VSoft\archITekt\Images\dev"
    .\Repair.ps1 `
    -PathProjectFolder "C:\VSoft\Projects\SAMPLE1" `
    -dbUser "superadmin" `
    -dbPassword "superadmin_password"

Description of the script for administrative relocation of the user script execution indicator

During application deployment, it may be necessary to administratively force a restart of a series of application scripts or skip several application scripts

In order to administratively change the number of the application script from which the scripts should be executed, use the RewindApplicationSqlScript.ps1 PowerShell script

When running the script, specify the name of the application script before which you want to move the pointer (in other words, the name of the script from which you want to continue executing the application update procedure).

In fact, the script NUMBER is of key importance here (the user name used in the script name can be arbitrary), because each application SQL script must have a unique number controlling the order of its execution.

The command is executed by passing the following parameters:

.\RewindApplicationSqlScript.ps1 `
     -pathProjectFolder [path to the project directory] `
    -runtimeFileName [(option) runtime name when using a non-standard one] `
     -nameOfScriptToRewind [name of the script before which we want to move the execution pointer] `-SecurityPassword [(option) security password for an encrypted environment]

Example of use:

.\RewindApplicationSqlScript.ps1 -pathProjectFolder ‘C:\vsoft\Projects\T01\’ -nameOfScriptToRewind ‘U.0004.sample\_script.sql’

The above command will move the execution of the application's SQL scripts for project “T01” before script number “U.0004” (the name is for informational purposes only). The next time the project update procedure is run in VSoft archITekt Launcher, it will execute all existing scripts starting with number “U.0004”.

From a technical point of view, executing the command results in an entry in the _DATABASE_JOURNAL table, which indicates from which script subsequent application scripts are to be run.

Automatic execution of scripts updating the data structure

In standard use cases, the archITekt platform automatically updates the application data structure after each package import.

Technically:

During the package export procedure, the archITekt platform automatically generates SQL scripts that update the database structure and dictionary tables. During package import, it stores these files in the project directory (in theInit_Sql!FINISH subdirectory), and during the application component update procedure, it automatically runs these scripts to update the database structure.

Executing your own scripts that extend the data structure

If you want to run your own scripts on the database, you can add your own scripts to the data structure definition directly in archITekt Studio. See: User SQL scripts.

In this case, the archITekt platform will treat the additional user scripts as an integral part of the configuration and ensure that they are automatically run after each package import.

Technically:

The archITekt platform treats user scripts as an integral part of the automatically generated scripts that update the data structure; they are run during a standard database update operation.

Executing any scripts on application databases

warning

The following functionality is experimental and may change in the future

If, when installing a new version of the application, there is a need to execute your own dedicated SQL scripts (e.g., updating data in the database or performing other specific operations on any of the application databases), they must be placed in the appropriate folder so that they can be executed on the database.

1. Executing dedicated SQL scripts at the beginning of the update procedure. If you want to execute your own scripts at the beginning of the database structure update procedure, you should place them in the !BEGIN directory.
2. Executing dedicated SQL scripts at the end of the update procedure. If you want to execute your own scripts at the end of the database structure update procedure, you should place them in the !FINISH directory.

Scripts placed in directories are executed in natural order (as sorted in Windows Explorer). It is good practice to prefix script names with the numbers “001_”, “002_” to ensure the correct order of execution.

The !FINISH directory also contains scripts automatically generated by the VSoft archITekt platform, containing operations to update the database structure and dictionary tables. It should be assumed that archITekt scripts will be delivered with file names between 100_ and 200_.

For example:

1. Scripts 001_ and 050_ will be executed before the scripts automatically generated by the platform.
2. Scripts 110_ and 120_, automatically generated by the platform, will be executed next.
3. Scripts 250_ and 300_ will be executed after the scripts automatically generated by the platform.

Attention!

In specific cases, the user may provide scripts with names identical to those automatically generated by the platform. In such cases, the platform will not overwrite these files but will use them as its own scripts.

At this point, the following files are automatically generated:

1. 110_EDMX.sql – contains scripts that update the data structure with content identical to that from the archITekt Studio tool – see: Data structure update.
2. 120_DICT.sql – contains scripts that update dictionaries (with content identical to that from the Studio tool – see: Dictionary update.)

Protection against multiple execution of user scripts

The fact that a user script has been run on the database is recorded in the _DATABASE_UPDATE_JOURNAL table in each platform database. We can use this information to control the number of times our script is executed. For example, if we want to limit the execution of our script located in the !FINISH directory to a single execution, we should place the following SQL command at the beginning of the script:

IF EXIST (SELECT ID FROM _DATABASE_UPDATE_JOURNAL WHERE 
DJ_DB_UPDATE_PHASE = ‘FINISHING’
AND DJ_SCRIPT_NAME = ‘[nazwa naszego skryptu]’ 
AND DJ_SCRIPT_EXECUTION_STATUS=’OK’)
        RETURN

Advanced users can also modify the archITekt installation package by adding scripts to the Init_Sql!BEGIN or Init_Sql!FINISH directories – these will be executed once during the next replacement.

More information on how to build scripts can be found in the DBUpgrader documentation.

Removing existing user scripts from previous versions of the application

During the application update, new files from the import package replace the existing files from the SQL and Files directories.

If you want your SQL script to no longer be executed during subsequent application updates, you must remove it from the next application update package.

See also

Prepare for OnPremises installation

Preparation of infrastructure on the OnPremises environment

Installing the application on the OnPremises environment