Creating and Using an Installation Manifest
This topic describes how to use the %Installer utility to create an installation manifest that describes a specific InterSystems IRIS® data platform configuration and use it to generate code to configure an InterSystems IRIS instance.
Overview of an Installation Manifest
The %Installer utility lets you define an installation manifest that describes and configures a specific InterSystems IRIS configuration, rather than a step-by-step installation process. To do so, you create a class that contains an XData block describing the configuration you want, using variables that contain the information usually provided during installation (superserver port, operating system, and so on). You also include in the class a method that uses the XData block to generate code to configure the instance. This appendix provides installation manifest examples that you can copy and paste to get started.
Once you have defined the manifest, you can call it during installation, from a Terminal session, or from code. The manifest must be run in the %SYS namespace.
Creating an Installation Manifest
This section contains the information needed to create an installation manifest, broken into the following subjects:
Manifest Class Definition
To create a class that defines an installation manifest, create a class that meets the following criteria (or start from the blank template in the Installation Manifest Examples section below):
-
The class must include the %occInclude include file.
-
The class must contain an XData block specifying the details of the installation. The name of the XData block will be used later as an argument. The root element in the XData block must be <Manifest>. For details, see “List of <Manifest> Tags”.
In Studio, if you include [XMLNamespace = INSTALLER] after the name of the XData block, Studio provides assistance as you type the XData block.
-
The class must define a setup() method that refers to the XData block by name, as seen in the Installation Manifest Examples section.
Common Manifest Options
This section describes some of the common tasks an installation manifest is used to perform. The following options are described:
Define Namespaces
To define namespaces, add any number of <Namespace> tags within the <Manifest> tag.
If you want to define databases or mappings for a namespace, put a <Configuration> tag inside the <Namespace> tag. For each database the namespace contains, add a <Database> tag within the <Configuration> tag. To define mappings, add <GlobalMapping>, <RoutineMapping>, and <ClassMapping> tags beneath the appropriate <Database> tag. The </Configuration> tag activates the defined mappings.
Also within a <Namespace> tag, you can load globals, routines, and classes using the <Import> tag. You can also invoke class methods, which in turn can execute routines and access globals that have been imported, with the <Invoke> tag.
You can define variables with the <Var> tag. To reference a variable within the manifest, use the ${var_name} syntax. For more information, see Variables Within <Manifest> Tags below.
Add Users and Passwords
There are multiple ways to add users (including their roles and passwords) to the installed instance:
-
Include a <User> tag in an installation manifest, as described in the List of <Manifest> Tags.
The PasswordVar parameter of the <User> tag specifies the variable containing the password for the user; for example, by defining PasswordVar="Pwd", you are specifying that the value of the variable Pwd is the password for a user. There are a variety of ways to populate this variable, but it is ultimately up to you to do this. You might consider using a remote method invocation to another instance of InterSystems IRIS or a web service; the problem with these approaches is that the server that is installing InterSystems IRIS may need internet access. Other possibilities include importing the method you are using to the instance you are installing, or adding a client-side form to the install that prompts for users and passwords, which can be passed to your manifest.
-
Edit users in the Management Portal after installation is complete, as described in Users.
-
Using the Security.UsersOpens in a new tab class on a staging instance of InterSystems IRIS, as follows:
-
Export the user information by using the Security.Users.Export()Opens in a new tab method.
-
Import the user information by adding the following at the beginning of your manifest class (in the %SYS namespace):
<Invoke Class="Security.Users" Method="Import" CheckStatus="true"> <Arg Value="PathToExportedUserInformation"/> </Invoke>
where PathToExportedUserInformation is the location of the output file specified in the Security.Users.Export()Opens in a new tab method.
-
Write to the Manifest Log
You can define messages to be added to the manifest log by incorporating <Log> tags in your class, in the following format:
<Log Level="<level>" Text="<text>"/>
The log level must be in the range of -1 to 3, where -1 is “none” and 3 is “verbose”; if the log level specified in the setup() method is equal to or greater than the Level property in the <Log> tag, the message is logged. The text is limited to 32,000 characters.
You set the log level via the second argument of the setup() method (for more information, see “Using the Manifest” later in this appendix). Since this cannot be passed to the manifest from the install, you must set it in the class as follows:
ClassMethod setup(ByRef pVars, pLogLevel As %Integer = 3,
pInstaller As %Installer.Installer,
pLogger As %Installer.AbstractLogger)
As %Status [ CodeMode = objectgenerator, Internal ]
You can direct where messages are displayed via the fourth argument (%Installer.AbstractLoggerOpens in a new tab) of the setup() method; for example, if you instantiate a %Installer.FileLoggerOpens in a new tab object referencing an operating system file, all %Installer and log messages are directed to that file. (Without this argument, all messages are written to the primary device if setup() is called directly, and are ignored if it is executed by the installer.)
Perform Post-Upgrade Tasks
When upgrading an instance of InterSystems IRIS, you can use an installation manifest to automatically perform any necessary post-upgrade tasks, such as recompiling code. You do this by using the <Invoke> tag to call the class methods described in the How to Compile Namespaces section of the “Upgrading InterSystems IRIS” chapter of this book.
See the Installation Manifest Examples section of this appendix for an example of a manifest that can be used during an upgrade.
Variables Within <Manifest> Tags
Some tags can contain expressions (strings) that are expanded when the manifest is executed. There are three types of expressions that can be expanded, as follows:
Expands to the value of the variable. In addition to the predefined variables described in this section, you can specify additional variables with the <Var> tag.
Expands to the value of the specified parameter for the manifest class.
Expands to the specified InterSystems IRIS Object Script expression (which must be properly quoted).
Parameter expressions are expanded at compile time, which means they can be nested within variable and ObjectScript expressions. Additionally, variable expressions are expanded before ObjectScript expressions and thus can be nested within the latter.
The following table lists the predefined variables that are available to use in the manifest:
Variable Name | Description |
---|---|
SourceDir | (Available only when the installer is run) Directory from which the installation (setup_irisdb.exe or irisinstall) is running. |
ISCUpgrade | (Available only when the installer is run) Indicates whether this is a new installation or an upgrade. This variable is either 0 (new installation) or 1 (upgrade). |
CFGDIR | See INSTALLDIR. |
CFGNAME | Instance name. |
CPUCOUNT | Number of operating system CPUs. |
CSPDIR | CSP directory. |
HOSTNAME | Name of the host server. |
INSTALLDIR | Directory into which InterSystems IRIS is installed. |
MGRDIR | Manager (mgr) directory. |
PLATFORM | Operating system. |
PORT | InterSystems IRIS superserver port. |
PROCESSOR | Processor chip. |
VERSION | InterSystems IRIS version number. |
Using the Manifest
You can run a manifest manually, or as part of an installation.
Manually
In the %SYS namespace, enter the following command in the Terminal:
%SYS>do ##class(MyPackage.MyInstaller).setup()
You can pass an array of variables to the setup() method by reference. Each subscript is used as a variable name, and the node as the value. For example:
%SYS>set vars("SourceDir")="c:\myinstaller"
%SYS>set vars("Updated")="Yes"
%SYS>do ##class(MyPackage.MyInstaller).setup(.vars,3)
The second argument in this example (3) is the log level.
During Installation
Export the manifest class as DefaultInstallerClass.xml to the same directory where the InterSystems IRIS install (either .msi, setup_irisdb.exe, or irisinstall) is run. It is imported into %SYS and compiled, and the setup() method is executed.
Make sure that the user running the installation has write permission to the manifest log file directory. The installation does not proceed if the log file cannot be written.
In addition, if you are installing with a single-file kit, you will need to extract the files from the .exe file into the installation directory to get the expected behavior.
Note that if you use the export technique, you cannot pass arguments directly to the setup() method. The following sections describe how to pass arguments on Windows or on UNIX®, Linux, and macOS:
On Windows
You can modify the .msi install package to pass variable name/value pairs to the setup() method.
You can also use command-line arguments with the installer to pass the location of the exported manifest class, variables, log file name, and log level, as shown in the following example:
setup.exe INSTALLERMANIFEST="c:\MyStuff\MyInstaller.xml"
INSTALLERMANIFESTPARAMS="SourceDir=c:\mysourcedir,Updated=Yes"
INSTALLERMANIFESTLOGFILE="installer_log" INSTALLERMANIFESTLOGLEVEL="2"
Variable names passed using the INSTALLERMANIFESTPARAMS argument may contain only alphabetic and numeric characters (A-Za-z0-9) and underscores (_), and may not start with an underscore.
For more information, see the Command Line Reference.
On UNIX®, Linux, and macOS
On UNIX®, Linux, and macOS systems, you can set environment variables to define the location of the exported manifest class, variables, log file name, and log level prior to running either irisinstall or irisinstall_silent, as shown in the following example:
ISC_INSTALLER_MANIFEST="/MyStuff/MyInstaller.xml"
ISC_INSTALLER_PARAMETERS="SourceDir=/mysourcedir,Updated=Yes"
ISC_INSTALLER_LOGFILE="installer_log"
ISC_INSTALLER_LOGLEVEL="2"
./irisinstall
For more information, see Unattended Installation Parameters.
Installation Manifest Examples
This section contains examples of installation manifests that do the following:
Blank Template
The following is a basic manifest template:
Include %occInclude
/// Simple example of installation instructions (Manifest)
Class MyInstallerPackage.SimpleManifest
{
XData SimpleManifest [ XMLNamespace = INSTALLER ]
{
<Manifest>
<Log Level="3" Text="Start manifest" />
<Namespace Name="">
<Import File="" />
<Invoke Class="" Method="" CheckStatus="" Return="">
<Arg Value=""/>
</Invoke>
</Namespace>
<CopyFile Src="" Target="" IgnoreErrors=""/>
<CopyDir Src="" Target="" IgnoreErrors=""/>
<Log Level="3" Text="End manifest" />
</Manifest>
}
/// This is a method generator whose code is generated by XGL.
ClassMethod setup(ByRef pVars, pLogLevel As %Integer = 3,
pInstaller As %Installer.Installer,
pLogger As %Installer.AbstractLogger)
As %Status [ CodeMode = objectgenerator, Internal ]
{
#; Let our XGL document generate code for this method.
Quit ##class(%Installer.Manifest).%Generate(%compiledclass, %code, "SimpleManifest")
}
}
Create a Namespace
The manifest in this example creates a namespace (MyNamespace) and three databases. The MyDataDB and MyRoutinesDB databases are the default databases for globals and routines, respectively, while the MyMappingDB database is another globals database. The <GlobalMapping> tag creates a mapping to MyMappingDB for t* globals in the MyNamespace namespace, which overrides the default mapping.
Include %occInclude
/// Simple example of installation instructions (Manifest)
Class MyInstallerPackage.SimpleManifest
{
XData SimpleManifest [ XMLNamespace = INSTALLER ]
{
<Manifest>
<Namespace Name="MyNamespace" Create="yes"
Code="MyRoutinesDB" Data="MyDataDB">
<Configuration>
<Database Name="MyRoutinesDB" Create="yes"
Dir="C:\MyInstallerDir\MyRoutinesDB"/>
<Database Name="MyDataDB" Create="yes"
Dir="C:\MyInstallerDir\MyDataDB"/>
<Database Name="MyMappingDB" Create="yes"
Dir="C:\MyInstallerDir\MyMappingDB"/>
<GlobalMapping Global="t*" From="MyMappingDB"/>
</Configuration>
</Namespace>
</Manifest>
}
/// This is a method generator whose code is generated by XGL.
ClassMethod setup(ByRef pVars, pLogLevel As %Integer = 3,
pInstaller As %Installer.Installer,
pLogger As %Installer.AbstractLogger)
As %Status [ CodeMode = objectgenerator, Internal ]
{
#; Let our XGL document generate code for this method.
Quit ##class(%Installer.Manifest).%Generate(%compiledclass,
%code, "SimpleManifest")
}
}
Compile After an Upgrade
The manifest in this example recompiles code in a namespace called APPTEST, and is intended to be run after an upgrade. It performs the following tasks:
-
Writes a message to the manifest log indicating the start of the manifest installation process.
-
Sets the current namespace to APPTEST, which contains the code that needs to be recompiled after the upgrade.
-
Invokes the method %SYSTEM.OBJ.CompileAll() to compile the classes in the namespace.
-
Invokes the method %Routine.CompileAll() to compile the custom routines in the namespace.
-
Writes a message to the manifest log indicating the end of the manifest installation process.
Include %occInclude
/// Simple example of installation instructions (Manifest)
Class MyInstallerPackage.SimpleManifest
{
XData SimpleManifest [ XMLNamespace = INSTALLER ]
{
<Manifest>
<Log Level="3" Text="The Installer Manifest is running."/>
<Namespace Name="APPTEST">
<Invoke Class="%SYSTEM.OBJ" Method="CompileAll" CheckStatus="1">
<Arg Value="u"/>
</Invoke>
<Invoke Class="%Routine" Method="CompileAll" CheckStatus="1"/>
</Namespace>
<Log Level="3" Text="The Installer Manifest has completed."/>
</Manifest>
}
/// This is a method generator whose code is generated by XGL.
ClassMethod setup(ByRef pVars, pLogLevel As %Integer = 3,
pInstaller As %Installer.Installer,
pLogger As %Installer.AbstractLogger)
As %Status [ CodeMode = objectgenerator, Internal ]
{
#; Let our XGL document generate code for this method.
Quit ##class(%Installer.Manifest).%Generate(%compiledclass, %code, "SimpleManifest")
}
}