RealmJoin Docs

RJ ecosystem

The picture above provides a schematic overview over the RealmJoin package distribution ecosystem. The step of creating packages will be illuminiated in this chapter. It documents the basic steps in creating craft, chocolatey, chocolatey App-V and organic packages. While all types follow the same rough outline, there are some differences when handling the packages.

General Steps

This section describes the shared steps for craft and chocolatey packages. The packaging process will be demonstrated on the well known VLC player.

Create local repository folder

Run cmd.exe as administrator and navigate to the desired folder, in which the packages are to be created. Then create a new folder for the new repository: mkdir videolan-vlc-2.26

Use Jumpstarter to create repository

Gk provides a Jumpstarter script that can be used to automatically create the template for a new package. Run the following code in the cmd shell:

@"%SystemRoot%\System32\WindowsPowerShell\v1.0\powershell.exe" -NoProfile -ExecutionPolicy Bypass -Command "iex ((New-Object System.Net.WebClient).DownloadString('https://github.com/realmjoin/realmjoin-package-jumpstarter/raw/master/JumpstartRealmJoinPackage.ps1'))"

You confronted by the following prompt and asked to specify details:

Repository path (leave empty for current folder name, Format: {VENDOR}-{PRODUCTNAME}): videolan-vlc
Repository name (leave empty for repository path): Videolan VLC Player
Repository namespace (leave empty for 'generic-packages', Format: {CUSTOMER}-packages): (your namespace)
Personal Access Token:(your token)   
Cloning into....[installation messages]
[...]
Possible Packagetypes:
  [1] Chocolatey
  [2] Chocolatey and Usersettings
  [3] Chocolatey and multi Usersettings
  [4] Craft
Please enter the type of package. (all samples found in: '.realmjoin-gitlab-ci-helpers'): 1
Please enter the PackageVersion (Format: 1.0.0.0): w.x.y.z

RJ package-jump

After a short while, a new repository is created and the template files are copied into the local package folder. Files not necessary for the selected package type will be deleted. If the correct package version and type are selected, it is not necessary to edit the choco-package.nuspec and .gitlab-ci.yml files. Nevertheless it is highly recommended to check those files for consistency.
Before working on the files, please check the readme.md. Depending on the type of package that is to be created, the next steps will vary.

Jumpstarter Beta

RealmJoin and the automatization tools are constantly adapted and refined. Advanced features are implemented and tested in a beta branch. The beta version of the Jumpstarter script can be used by running the following code in a cmd shell:

@"%SystemRoot%\System32\WindowsPowerShell\v1.0\powershell.exe" -NoProfile -ExecutionPolicy Bypass -Command "iex ((New-Object System.Net.WebClient).DownloadString('https://github.com/realmjoin/realmjoin-package-jumpstarter/raw/beta/JumpstartRealmJoinPackage.ps1'))"

Chocolatey Package

Edit Package files

RJ package-sample

The .gitlab-ci.ymlfile contain the build and deploy information. In the build stage, the build-deploy.ps1 helper script is called, while the argument -build indicates the build stage and -ChocoMachine the chocolatey type package. In the deploy stage, the build-deploy.ps1 helper script is called, while the argument -deploy indicates the deploy stage, -ChocoMachine the chocolatey type package and depending on the deploy mode, the -flavourCollection:

Installers in zip-files

In some cases .msi or .exe installers require additional files in their execution folder. It is possible, to merge the installer and additional files in a zip container and execute the installer without unpacking forehand.
To do so, the zip container is put into the blobs folder and a hash value has to be created. In the chocolateyInstall.ps1, the install command may be used as described above, but the installer file has to be escaped with #, installation parameters can be provide similar to simpler cases :
´´´ Install-ChocolateyRealmjoinPackage “CONTAINER.zip#INSTALLER.msi” “HASH” -additionalArgs “/Additional Args” ´´´

Installation Pre-Actions

The Install-ChocolateyRealmjoinPackage command can be run with the execution of pre-actions:

Install-ChocolateyRealmjoinPackage "INSTALLER.msi" "HASH" -preActions {param($setupFolder) Copy-Item -force "$packageToolsFolder\Oracle CONFIG.ini" $setupFolder }

Installation Post-Actions

The Install-ChocolateyRealmjoinPackage command can be run with the execution of post-actions:

Install-ChocolateyRealmjoinPackage "INSTALLER.msi" "HASH" -postActions { Remove-Item "$env:PUBLIC\Desktop\SHORTCUT.lnk" -ErrorAction SilentlyContinue }

Craft Package

Edit Package files

Organic Package

Organic packages are created similar to Chocolatey packages, but instead of a software install, they unzip a specified file into a specified folder on the device. Therefore, the main differences are the provided blobs and the chocolateyInstall.ps1script.

App-V Package

APP-V packages are highly sophisticated and unique. Therefore, a general guide can at this point not be provided. If an APP-V package is required, please contact GK for examples and further information or package creation.

Conventions and RealmJoin helpers

The helper scripts are provided by GK. They can not be altered while choco/craft packages are created. If a change is necessary, e.g. add a new flavour, the helper scripts have to be recreated. Please contact GK.

realmjoin-gitlab-ci-helpers.ps1

The realmjoin-gitlab-ci-helpers.ps1 is a helper script called in all package types in the .gitlab-ci.yml, e.g. script: ./.realmjoin-gitlab-ci-helpers/realmjoin-gitlab-ci-helpers.ps1 -buildChocoMachine -flavors "generic","glueckkanja". The following switches are available:

build-deploy-flavor-definitions.ps1

The build-deploy-flavor-definitions.ps1 script contains the available flavours for all deploy modes. There are currently 3 different deploy modes:

Capitalization and Naming

Please use only small letters for all naming purposes and use vendor-program-version as folder names.

Version numbering

Software packages are assigned a individual version number. It is recommended to divide the version number into four parts W.X.Y.Z and use one of two different conventions:

Variables

The following variables may be used in the RealmJoin install scripts: