JS7 - PowerShell Installation Script - Install-JS7YADE.ps1

Name

Install-JS7YADE.ps1

SYNOPSIS

Installs, updates, patches or uninstalls YADE on Windows and Unix platforms supporting PowerShell 5.1, 6, 7.

SYNTAX

Install-JS7YADE.ps1 [-HomeDir] <String> [[-Data] <String>] [[-Logs] <String>] [[-Release] <String>] [[-Tarball] <String>] [[-Patch]
    <String>] [[-PatchJar] <String>] [[-BackupDir] <String>] [[-LogDir] <String>] [[-ReturnValues] <String>] [-Uninstall] [-UninstallHome] [-UninstallData]
    [-Show

Logs] [-MakeDirs] [-MoveLibs] [-WhatIf] [-Confirm] [<CommonParameters>]

DESCRIPTION

The YADE Installation Script can be used to automate installing, updating, patching and uninstalling YADE.

The script offers the installation options available from the YADE's graphical installer.

For download see https://kb.sos-berlin.com/display/JS7/JS7+-+Download 

PARAMETERS

HomeDir

-HomeDir <String>
Specifies the directory in which the YADE should be installed.

Data

-Data <String>
Specifies the directory in which YADE data such as configuration files should be stored.
By default the <home>/var_<http-port> directory is used, see -HomeDir and -HttpPort parameters.

Logs

-Logs <String>
Specifies the directory to which the YADE stores log files.
By default the <data>/logs directory is used, see -Data parameter.

Release

-Release <String>
Specifies a release number of the JS7 YADE such as 2.8.0 to be used.

The release will be downloaded from the SOS web site if the -Tarball parameter is not used.

Tarball

-Tarball <String>
Optionally specifies the path to a .zip or .tar.gz file that holds the YADE installation files.
If this parameter is not used the installer tarball will be downloaded from the SOS web site for the release indicated with the -Release parameter.

Users can check if the connection to a specific URL is bypassed or is using a proxy with a command such as:
([System.Net.WebRequest]::GetSystemWebproxy()).IsBypassed("https://download.sos-berlin.com")

For use with PowerShell 7 users can specify environment variables to perform download using a proxy:

* HTTP_PROXY - proxy for HTTP requests
* HTTPS_PROXY - proxy for HTTPS requests
* ALL_PROXY - proxy for both HTTP and HTTPS
* NO_PROXY - proxy exclusion address list

Patch

-Patch <String>
A patch is identified by an issue key and a specific release in the SOS Change Management System.

For example the -Patch JS-1984 -Release 2.2.3 parameters will download an (empty) sample patch from the SOS web site:

For Unix and Windows the download file is https://download.sos-berlin.com/patches/2.2.3-patch/js7_yade.2.8.0-PATCH.YADE-1984.tar.gz

Patches can be individually downloaded and can be made available from the -Tarball parameter.

For example the -Patch JS-1984 -Tarball /tmp/js7_yade.2.8.0-PATCH.YADE-1984.tar.gz parameters will apply the patch from the downloaded file.

Patches are added to the YADE's <home>/lib/patches directory.
Note that patches will be removed when updating the YADE installation later on.

To apply patches the YADE has to be restarted. The -Restart or -ExecStart, -ExecStop parameters can be used for automated restart.

PatchJar

-PatchJar <String>
Opetionally specifies the path to a .jar file that holds a patch.

The patch .jar file has to be downloaded individually and will be copied to the YADE's <home>/lib/patches directory.

BackupDir

-BackupDir <String>
If a backup directory is specified then an YADE's existing home and data directories will be added to backup files in this directory.
The backup file type is .tar.gz for Unix and Windows.

File names are created according to the pattern:

* backup_js7_yade.<hostname>.<release>.home.<yyyy>-<MM>-<dd>T<hh>-<mm>-<ss>.tar.gz|.tar.gz
* backup_js7_yade.<hostname>.<release>.data.<yyyy>-<MM>-<dd>T<hh>-<mm>-<ss>.tar.gz|.tar.gz

For example: backup_js7_yade.centostest_primary.2.8.0.home.2025-05-19T20-50-45.tar.gz

LogDir

-LogDir <String>
If a log directory is specified then the Installation Script will log information about processing steps to a log file in this directory.
File names are created according to the pattern: install_js7_yade.<hostname>.<yyyy>-<MM>-<dd>T<hh>-<mm>-<ss>.log
For example: install_js7_yade.centostest_primary.2024-05-19T20-50-45.log

ReturnValues

-ReturnValues <String>
Optionally specifies the path to a file to which return values will be added in the format <name>=<key>. For example:

log_file=install_js7_yade.centostest_primary.2025-05-20T04-54-31.log
backup_file=backup_js7_yade.centostest_primary.2.8.0.2025-05-20T04-54-31.tar.gz

An existing file will be overwritten. It is recommended to use a unique file name such as /tmp/return.$PID.properties.
A value from the file can be retrieved like this:

* Unix
** backup=$(cat /tmp/return.$$.properties | grep "backup_file" | cut -d'=' -f2)
* Windows
** $backup = ( Get-Content /tmp/return.$PID.properties | Select-String "^backup_file[ ]*=[ ]*(.*)" ).Matches.Groups[1].value

Uninstall

-Uninstall <SwitchParameter>
Uninstalls the YADE including the steps to stop and remove a running YADE service and to remove the <home> and <data> directories.

UninstallHome

-UninstallHome <SwitchParameter>
Uninstalls the YADE but preservers the YADE's <data> directory.

UninstallData

-UninstallData <SwitchParameter>
Uninstalls the YADE but preservers the YADE's <home> directory.

ShowLogs

-ShowLogs <SwitchParameter>
Displays the log output created by the Installation Script if the -LogDir parameter is used.

MakeDirs

-MakeDirs <SwitchParameter>
If directories are missing that are indicated with the -HomeDir, -BackupDir or -LogDir parameters then they will be created.

MoveLibs

-MoveLibs <SwitchParameter>
For an existing YADE installation the lib sub-directory includes .jar files that carry the release number in their file names.
If replaced by a newer version the lib directory has to be moved or removed.
This switch tries to move the directory to a previous version number as indicated from the .version file in the YADE's home directory,
for example to rename lib to lib.2.3.1.

Files in the lib/user_lib sub-directory are preserved.

WhatIf

-WhatIf <SwitchParameter>

Confirm

-Confirm <SwitchParameter>

EXAMPLES

-------------------------- BEISPIEL 1 --------------------------

PS C:\> Install-JS7YADE.ps1 -HomeDir "C:\Program Files\sos-berlin.com\js7\yade" -Data "C:\ProgramData\sos-berlin.com\js7\yade" -Release 2.8.0 4445 -MakeDirs

Downloads and installs the YADE release to the indicated location.

-------------------------- BEISPIEL 2 --------------------------

PS C:\> Install-JS7YADE.ps1 -HomeDir "C:\Program Files\sos-berlin.com\js7\yade" -Data "C:\ProgramData\sos-berlin.com\js7\yade" -Tarball
    /tmp/js7_yade_windows.2.8.0.zip -BackupDir /tmp/backups -LogDir /tmp/logs -MakeDirs

Applies the YADE release from a tarball and installs to the indicated locations. A backup is taken and log files are created.