Installation Guide
This installation guide applies to Obsidian versions 4.0 and newer. See the Installation Guide for prior versions.
This installation guide is a companion to the Obsidian Installer UI. Its purpose is to provide additional detail as to the meaning of various inputs and to provide guidance on advanced usage of the installer.
The installer itself installs and configures the artifacts. The configured artifacts will have their Properties file configured according to the choices made during the installation process. You may always change these later or use one of the override mechanisms.
Running the Obsidian Installer
The installer is an executable JAR file in the Obsidian download zip package available on our download page.
The installer can be run from the command line as a graphical user interface using java -jar Obsidian-Install-n-n-n.jar or in interactive console mode using java -jar Obsidian-Install-n-n-n.jar -console. Note that you will have to replace the JAR file name with the actual versioned name in your installation.
On some platforms, simple double-clicking the JAR file will start it in graphical interface mode.
If you are doing a version upgrade of Obsidian or are otherwise uninterested in actually configuring the artifacts, you can run the quick start mode to get the default configured artifacts using java -jar Obsidian-Install-n-n-n.jar h2-winstone-quick-start.xml.
Obsidian Installer Artifacts
The Obsidian Installer installs and configures a number of artifacts. You can choose which artifacts to create, but most users can leave the default options selected.
- Obsidian WAR - This is the Obsidian Web Admin UI with scheduler component enabled. Configuration will be found at INSTALL_PATH/obsidian.war!/WEB-INF/classes/com.carfey.properties.
- Obsidian Standalone Admin WAR - This is the Obsidian Web Admin UI with scheduler component disabled. Configuration will be found at INSTALL_PATH/standaloneObsidianAdmin.war!/WEB-INF/classes/com.carfey.properties.
- Standalone Obsidian Runtime - This is a runtime folder containing the libraries and configuration necessary for running the Obsidian Scheduler component either as a standalone module or for use as an Embedded Scheduler in your application. Configuration will be found at INSTALL_PATH/standalone/obsidian-props.jar!/com.carfey.properties.
- Obsidian License Proxy - Allows for local license leasing from a Key Server Proxy that ultimately leases licenses from the Obsidian License server.
- Documentation - README and Embedded API Javadoc.
- Jetty - A simple servlet container for quick evaluation of the Obsidian UI.
- License - Obsidian and 3rd party license information.
Obsidian Configuration
The installer will guide you through the configuration Obsidian.
First, you must choose what Authenticator mechanism will be used within Obsidian. Native (Database) authentication requires no additional configuration and is what most users will select. Select Other if you have implemented your own authentication mechanism, or LDAP to configure LDAP settings.
Next, you'll want to select the email usage type. We highly recommend you configure Obsidian for email use as it will allow you to benefit from the event notification and subscription support in Obsidian.
Then you'll configure the log file location, license key (optional) and registered company name (optional). Registered company name is only required for our Site License users.
LDAP Configuration
If you've selected LDAP Authentication, this screen takes you through configuring the server address and the various elements used to grant access. You should familiarize yourself with Obsidian Roles. The Access DN configuration element grants Read access to Obsidian application. You may use the same DN for more than one Role should you so wish.
Custom Authenticator Configuration
If you have chosen to use your own authentication mechanism, you must enter the fully qualified classname here.
Database Configuration
Next comes database configuration. If you are using JNDI, leave the username and password fields blank. If using JDBC URL, username and password fields are required.
The Database connections per instance and Database connection timeout(millis) fields are required and provide directive to the connection pool.
Database table name prefix is optional and is typically used when Obsidian will be colocated in an existing database/schema.
Database schema (Oracle/PostgreSQL) - This is used to allow for an alternate schema other than the default user's schema. We also recommend setting this value with Oracle/PostgreSQL when using JNDI as it allows more efficient database metadata loading.
By default, the Obsidian installation will only include the JDBC libraries necessary for your particular database. At times you may wish to include the others to be able to change between databases. In those cases, check Include all supported JDBC libs.
Email Configuration
If not using JNDI for mail sessions, provide the server and authentication details as required.
JNDI Configuration
If you have selected JNDI for mail sessions, provide the JNDI path here. If you are using JNDI for Database connections, specify the database type.
Configuring 3rd Party Library Conflict Management
The Obsidian installer allows you to use JarJar to handle potential conflicts between Obsidian's use of 3rd party libraries and versions used within your application. On this screen, simply select which libraries to which you wish to apply the JarJar bytecode modification process. This is optional and is skipped if no libraries are selected. Any jars not listed for which you are using more recent versions can be used and are therefore not included as options in the JarJar processing.
Selecting Script Libraries
The Obsidian installer allows you to select which script libraries you wish to include. Jython and JRuby are incompatible with each other, so the installer will only allow one of the two selected. If all script libraries are deselected, the only script jobs that can be run in Obsidian will be Javascript jobs as that engine is built into Java.
Completing the Installation
Once you've completed the Installation and Configuration screens, fully configured Obsidian Scheduler artifacts are now ready for you to use in the installation path you selected.
Should you wish to automate future installations with the same configuration, click Generate an automatic installation script. This will prompt you to save an XML file that can be used for future installations using the automated install procedure java -jar Obsidian-Install-n-n-n.jar my-obsidian-configuration.xml. Every effort is made to ensure compatibility of these automated install files between versions. Any incompatibility will be noted in the Release Notes. These automated installer files can also be used as templates for other environments, modifying them as necessary.
