Package Layout

Package Metadata

At a minimum, a Romp package must contain a upack.json file.

See the Universal Package Metadata Specification for a list of upack.json properties.

A Romp package may also include an additional metadata file, rompPackage.json, that defines package behavior.

Romp Package Metadata Specification

Just like upack.json, a rompPackage.json file is a JSON object with the following optional properties:

However, unlike upack.json, the rompPackage.json file may not contain any additional properties.

Installing Romp

Romp doesn't require any external dependencies and has a very small footprint, making it very easy to install and maintain.

Romp is just an executable file with some libraries and doesn't require any special installation steps. By default, Romp is installed as a machine-level tool, but it can also be installed and used as a user-level tool.

Simple Romp Installer

Just download the installer and run it; the installer will do two things:

1. Extract Romp execution files to %ProgramFiles%\Inedo\Romp
2. Add Romp to the PATH environment variable, so that you can use it in any directory

If you specify user-level installation, the files will instead be extracted to %UserProfile%\.romp folder, and the userLevel configuration value will be set to true in the configuration file.

Note that Romp does not have an uninstaller; to uninstall, just remove it from your path and delete files.

Chocolatey Package

You can also just run choco install romp to install the romp chocolatey package. This effectively runs the simple romp installer.

Manual Installation

You can download the zip file containing Romp, and install it in any manner you'd like.

Uninstallation Script

A Romp package may contain an uninstall.otter file. If this file is not present, then the package does not support uninstallation.

The uninstall.otter file in the package root contains the OtterScript of the plan that will be executed when the uninstall command is invoked.

Basic Package File Uninstallation

If your package contains only content files, then only a trivially simple uninstall.otter script is needed.

Romp::Delete-Contents

This will invoke the Delete-Contents operation, which deletes all content files which were installed using the install command.

Built-In Variables

The following variables are available to the uninstall.otter script:

• $TargetDirectory - specifies the file system path where the package content was deployed, and the $WorkingDirectory variable will also be set to this path initially.
• $PackageGroup - specifies the group name of the package being uninstalled.
• $PackageName - specifies the name of the package being uninstalled.
• $PackageVersion - specifies the version of the package being uninstalled.

Variables

Package variables typically contain configuration values that are required for installing a package in a specific environment, or to allow installation to be customized.

Variables are defined in a packageVariables.json file located in the package root with upack.json. It is simply an object with variable names and values as properties. The value can be either a string, null, or an object with the following optional properties:

When an object is not specified for a variable value, a string indicates a required text variable, while a null represents a required text variable without a value. If you wish to allow an empty string, you will need to use the object syntax.

Example: packageVariables.json file

{
  "myStringValue": "Steve Dennis",
  "myArray": \[1, 2, 3, 4, 5\],
  "myMapValue": {
    "p1": "hdars",
    "p2": "test"
  },
  "requiredButNotSpecifiedValue": null
}

The example above defines 3 variables with values. Each property on the JSON object corresponds to a runtime OtterScript variable of scalar, vector, and map types respectively. The final variable, requiredButNotSpecifiedValue, is required but not specified. This will cause Romp to prompt for this value when the package is installed.

Package variables specified as command line arguments are returned first, followed by variables in packageVariables.json, followed by raft variables, in the event of variables of the same name.

You should not store sensitive passwords or other secrets in variables. They are not secure, at all. Instead, consider resource credentials.

Prompting for Required Variables

If a variable is required for package installation, it may be passed in as an argument to Romp. If you don't pass in a required variable, then you will be prompted for it (when running interactively), or Romp will issue an error and not proceed with installation.

Best Practices: Variable Descriptions

Think of variable descriptions like comments. If it's not obvious from the name how to use a variable, or how it might work, you should briefly describe that in the field. You can always include additional instructions on how to use the package in the package's description metadata field.

Variable descriptions are primarily used by {cmd line} to show a user how to install a package, and should be brief.

Passwords and Other Secret Credentials

Romp supports Resource Credentials, which are named credentials used to access a protected resource. Usually, credentials include secrets such as a username and password combination, and are stored securely using encryption, both in memory (during runtime), and on disk.

Like variables, the required credentials are defined in a packageCredentials.json file in the package root. It is an array of objects that describe credentials. Each object has the following properties.

An "R" denotes a required property. When an object is not specified for a variable, a string indicates a required text variable, while a null represents a required text variable without a value.

Example:

[
  {
    "type": "UsernamePassword",
    "name": "MyServerLogin",
    "description": "Use sdennis",
    "defaults": { // JSON representation of credentials object (plaintext)
      "UserName": "sdennis",
      "Password": null // cannot define because it’s secure
    }
 ]

In the above example, three username/password credentials are specified. In the first definition, the credentials are specified as pure JSON with any secrets clearly exposed. In the second definition, the JSON for the credentials object has been base64 encoded to help prevent revealing a secret through casual observation. In the third definition, the object is completely unspecified, and Romp will prompt for it when installing the package.

Embedding credentials in a package is a convenience, and the limited obfuscation provided should not be mistaken for any kind of cryptographically secure storage. The only secure way to store credentials in a package is to not store them at all, or to encrypt the entire package by some other means.

Locally Stored Credentials

Romp can store named credentials in an encrypted manner in its local configuration database, meaning you won't have to enter it at installation time or pass it in as an argument. See the romp store credentials command for more details.

Prompting for Credentials

Credentials may be passed in as an argument to Romp. Like variables, if you don't pass in a required variable, and one isn't defined as a locally-stored credential, then you will be prompted for it (when running interactively). Otherwise Romp will issue an error and not proceed with installation.

Credentials as Variable Values

You can use the $CredentialProperty variable function to extract a property from a credential, unless that credential is marked as "restricted". When restricted, only operations that can access secure storage will be able to read these properties.

Rafts

A raft is used to store plans, templates, variables, and asset files. If a Romp Package has any dependency on raft data, the entire raft can be included in the package. Further information about rafts can be found in the Otter documentation.