RealmJoin Docs

Upload through customer

The package management team of a customer uses the option RealmJoin Request Package within the portal to upload a * .zip file containing the .msi or .exe file as well as the instructions on the desired installation mode.

Get involved

The customers upload triggers an automatic ticket in the Packaging as a Service ticketing system.

Check the requierments

Before building your package, there are different checks to be performed:

  1. Did the customer provide all information that is needed to create the package: EXE / MSI? Readme with installation requirements? …?
    • If not, get in touch with the customer to clarify the required information.
  2. Is this package neccessary:
    • Check if the package already exists. If so: Same software version and parameters?
    • If the requested software exists in a different version: Might an update be more reasonable? Are different version required due to features or similar?
    • Get in touch with the customer to discuss and clarify the need for a additional version of this package.
  3. Is this package generic:
    • ALWAYS TRY TO GO GENERIC This will make maintaining and updating a lot easier, plus you may reuse the package for different users later on.
    • Does the customer request parameter or arguments that prevent the package to be used as a generic package?
    • If so, check if those are really neccessary: How is the software installed? Instead of reg keys, is it possible to use installation parameters in the package assigning step to configure the software? Why do the customer need this configuration and not the generic package?
    • Get in touch with the customer, if neccessay and try to make the package generic.
  4. Check provided setup files
    • If a setup or ini file is added in the upload, check the file for installation command. It is common, that those files contain specific installation instructions or even registry keys or license information.
    • If an *.mst file is provided, use a tool like DDIF to compare it to the *.msi and decide, if any of the changes are to be kept. Do not keep uninstall blocker or similar. Create a new *.mst file if necessary (use Orca). Do not start creating the package before you have a reasonable assumption of what to pack

Create the package

Creating packages

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:

* Please enter the RealmJoin GitLab repository path: test-vlc   
* Please enter the RealmJoin GitLab repository name: test-vlc   
* Please enter the RealmJoin GitLab repository namespace: (your namespace)   
* Please enter the RealmJoin GitLab Access Token: (your token)   
Cloning into....[installation messages]

RJ package-jump

After a short while, a new repository is created and the template files are copied into the local package folder. 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.

Chocolatey 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.

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:

Testing of the package

The testing of a package is indispensable. Before a package is deployed in the final version and dispatched, check the install and reinstall functionality as well as the program start up.

Virtual Machine

After building and deploying the generic flavour of the package (if possible, for customer packages use the single deploy channel), enter your own or the contoso test RealmJoin admin console and assign the package to your test account. Start up your testing VM (your test user should be local admin) and try install and reinstall of the package. Check the detail message and, if necessary, the log files for any errors. Test dependencies as well, if they are apparent.

Chocolatey packages

If you encounter any problems, it might be a good idea to check choco install and choco uninstall in an admin powershell. There are some extension helpers, that might be useful. To use them, enter the following commands in your admin powershell:

function Write-FunctionCallLogMessage(){}
import-module C:\ProgramData\chocolatey\lib\realmjoin-core.extension\extensions\Get-ChocolateyRealmjoinLogFilePath.ps1
import-module C:\ProgramData\chocolatey\lib\realmjoin-core.extension\extensions\Get-ChocolateyRealmjoinRegistryUninstallInfo.ps1
Import-Module C:\ProgramData\chocolatey\helpers\chocolateyProfile.psm1
import-module C:\ProgramData\chocolatey\lib\realmjoin-core.extension\extensions\Uninstall-ChocolateyRealmjoinPackage.ps1
import-Module C:\ProgramData\chocolatey\helpers\chocolateyInstaller.psm1

It might be required the repeat the last command if you encounter an error message. Now you are able to use the RealmJoin specific chocolatey commands individually.

Craft packages

Check if you are able to use the install commands in a powershell without RealmJoin. Make sure, your package is assigned in the correct scope (user or system).

Dispatching

TBD

Tools

The following tools are somewhere between useful and necessary: