Installation Guide

This installation guide generally applies to Obsidian versions 4.0 and newer but is specific to 7.0. You may see a few minor differences in 4.x, 5.x and 6.x releases. See the Installation Guide for all 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.

1. 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.
2. 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.
3. 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.
4. Obsidian License Proxy - Allows for local license leasing from a Key Server Proxy that ultimately leases licenses from the Obsidian License server.
5. Documentation - README and Embedded API Javadoc.
6. Obsidian Embedded Tomcat JAR — An embedded Apache Tomcat runtime for running Obsidian locally without an external servlet container. Requires the Obsidian WAR pack.
7. Obsidian Standalone Admin Embedded Tomcat JAR — An embedded Apache Tomcat runtime for running the standalone admin WAR locally. Requires the Obsidian Standalone Admin WAR pack.
8. License - Obsidian and 3rd party license information.

Deployment options

Obsidian 7.0.0 offers four deployment profiles in the installer:

• Obsidian WAR — deploy obsidian.war to your own servlet container (Tomcat, WebLogic, etc.).
• Obsidian Embedded Tomcat JAR — adds an embedded Tomcat runtime and webObsidian scripts to run obsidian.war locally (start scheduler). Requires the Obsidian WAR pack.
• Obsidian Standalone Admin WAR — admin console WAR for an external servlet container.
• Obsidian Standalone Admin Embedded Tomcat JAR — embedded runtime for the admin WAR (start adminOnly). Requires the Standalone Admin WAR pack.

Embedded Tomcat does not replace the WAR on disk — it runs the installed WAR via the helper. Do not select an embed pack without its matching WAR pack.

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, OAuth (OIDC), SAML or LDAP according to your desired mechanism.

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.

OAuth / OIDC Configuration

If you selected OAuth (OIDC) as the authentication type, the installer displays additional panels for OAuth configuration.

Provider and Common Settings

• Identity Provider — Select your provider: Keycloak, Microsoft Entra ID, Okta, Auth0, or Generic OIDC.
• SSO Button label — Label shown on the "Sign in with…" button (e.g. Keycloak, Acme Corp SSO). If left blank the button reads "Sign in with SSO".
• Redirect URI — The callback URL Obsidian receives after IdP login. Must be registered at the IdP (e.g. https://app.example.com/oauth/callback).
• Logout mode — local (default) or rp (RP-initiated logout via the IdP's end_session_endpoint).

Provider-Specific Settings

Fill in the connection details for your chosen provider.

Keycloak

• Issuer URL — e.g. https://keycloak.example.com/realms/myrealm.
• Client ID and Client Secret from the Keycloak client settings.
• Scopes — recommended: openid profile email groups.

Note: Keycloak does not include a groups claim by default — a Group Membership mapper must be configured in the client's Mappers tab.

Microsoft Entra ID

• Issuer URL — https://login.microsoftonline.com/<tenant-id>/v2.0.
• Client ID — the Application (client) ID from the Azure portal.
• Client Secret — a client secret value from the Azure portal.
• Scopes — openid profile email.

Note: the groups claim contains GUIDs by default; configure Optional Claims in the Azure portal to receive group display names. Multi-tenant applications are not supported in Obsidian 7.0.0.

Okta

• Issuer URL — use the Custom Authorization Server URL, e.g. https://<domain>.okta.com/oauth2/default. Do not use the Org Authorization Server URL.
• Client ID and Client Secret from Okta application settings.
• Scopes — openid profile email groups.

Auth0

• Domain / Issuer URL — e.g. https://<domain>.auth0.com/.
• Client ID and Client Secret from Auth0 application settings.
• Scopes — openid profile email.

Important: Auth0 issues opaque access tokens by default which are not supported on Obsidian's REST/Bearer path — configure a custom API in Auth0 to get JWT access tokens.

Generic OIDC

• Issuer URL — the base URL; Obsidian appends /.well-known/openid-configuration to discover endpoints.
• Client ID and Client Secret from the provider.
• Scopes — at minimum openid; add profile and your groups scope as needed.

Group → Role Mapping

The final OAuth panel maps IdP group values to Obsidian roles. Require role assignment (default yes) — when enabled, users with no matching roles cannot complete browser login. At least one mapping to the Admin role is required. The installer supports up to 10 group→role pairs; additional pairs can be added directly to the configuration file after install. See Advanced_Configuration#OAuth_/_OIDC_Authentication_Properties for the full property reference.

Registering the redirect URI at the IdP

Before starting Obsidian, register the redirect URI shown in the installer at your IdP: Keycloak — Client → Settings → Valid Redirect URIs; Entra ID — App Registration → Authentication → Redirect URIs; Okta — Application → General Settings → Sign-in Redirect URIs; Auth0 — Application → Settings → Allowed Callback URLs. The URI must match com.carfey.suite.security.OAuthAuthenticator.redirectUri exactly, including scheme and port.

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.

Choosing Email Support

As of Obsidian 5.2.0, you can choose between JavaMail (javax) and Jakarta mail (Jakarta EE) implementations. When choosing Jakarta, you can also choose to bundle the Angus Jakarta compatible implementation.

If you are using JNDI, this will only include the relevant support in the Obsidian WAR artifacts and the actual libraries in use must be provided by you and bundled with your container. If the standalone scheduler is selected along with JNDI, JNDI is assumed only relevant for WARs. As such, default libraries for either JavaMail or Jakarta will be included in the standalone installation.

Additional configuration items

As of Obsidian 5.5.0, if you require any additional configuration items such as additional appenders/loggers or event hook configurations, you can add them here.

Offline or restricted-network install

Obsidian 7.0.0 resolves third-party libraries when you run the installer. For environments without direct access to Maven Central:

1. Pre-stage a local dependency cache containing every coordinate listed in the Obsidian dependency inventory for your release (contact Carfey support or your account team for the checklist file matching Obsidian-Install-7.0.0.jar).
2. Copy the cache to the install host. Two layouts are supported:
   • Flat: one file per installed JAR name directly under the cache root.
   • File Maven repo: <group>/<artifact>/<version>/<installed-filename>.jar
3. Run the installer with offline mode and the cache directory:

java -Dobsidian.install.deps.offline=true -Dobsidian.install.deps.cache.dir=/path/to/cache -jar Obsidian-Install-7.0.0.jar

If a required library is missing from the cache, the install stops with an error naming the coordinate — add that artifact to the cache and re-run.

Corporate Maven mirror (online)

When your site mirrors Maven Central, point the installer at your repository base URL:

java -Dobsidian.install.deps.repo.url=https://nexus.example.com/repository/maven-public/ -jar Obsidian-Install-7.0.0.jar

The installer reuses resolved artifacts for the duration of one install session.

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.