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.

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-tomcat-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 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. For how to start, stop and change the ports of the embedded runtime, see Starting Obsidian with embedded Tomcat.

Linux desktop and systemd integration

As of Obsidian 7.1.0, on a Linux host, when an Embedded Tomcat pack and/or Standalone Obsidian Runtime is selected, the installer may offer Install Linux systemd integration. The panel is not shown on Windows or macOS, and not shown when none of those packs is selected.

A GUI install writes user-level units only. When the installer runs as root (typical headless sudo), the standalone template is also copied to /etc/systemd/system/[email protected].

Tick the checkbox to have the installer run the integration script for you. Leaving it unchecked still copies the linux/ templates with those packs, so you can opt in later:

./linux/install-embedded-linux-integration.sh "$PWD" scheduler

Use adminOnly for Standalone Admin embed installs, or standalone for Standalone Runtime.

For an automated (headless) install, request the integration with:

<entry key="embed.linux.integration" value="true"/>

Standalone stop waits three minutes by default (TimeoutStopSec=180). To wait longer, add (seconds):

<entry key="embed.linux.standalone.timeoutStopSec" value="300"/>

Installing these files does not enable or start anything. For details on how to enable, stop, reconfigure or remove the service, see Linux Service.

Obsidian Configuration

First, you must choose what Authenticator mechanism will be used within Obsidian. Obsidian supports five authentication methods: native (database), LDAP, OAuth (OIDC), SAML 2.0, and custom. Select Native (Database), LDAP, OAuth (OIDC), SAML 2.0, or Other (custom). Native (Database) requires no additional configuration and is what most users will select at least to start.

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

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

SAML 2.0 Configuration

If you selected SAML 2.0 as the authentication type, the installer displays additional panels that configure the Service Provider identity, SAML signing credentials, federation metadata, attribute options, and group→role mapping.

Service Provider

• SP Entity ID — HTTPS URI registered as the SAML SP entity (must match IdP registrations).
• Assertion Consumer Service URL — HTTPS ACS endpoint where SAML responses arrive (HTTP-POST); aligns with the ACS in /saml/metadata.
• SP Single Logout Service URL — Optional HTTPS URL for IdP-initiated SLO when logout mode targets IdP-mediated logout.
• SSO button label — Required label shown on Sign in with ….
• Logout mode — Local (Obsidian-only) or IdP / SLO (participates in SAML single logout when advertised).
• Post-logout redirect URI — Optional HTTPS landing URI after LogoutResponse.
• Keystore path / alias / passwords — Required when signing SAML requests (password field is dual-entry validated).
• Sign SAML authentication requests — Toggle (installer default true).
• Require signed SAML assertions — Toggle (recommended true for production).

Identity Provider

Choose the IdP type: Microsoft Entra ID (Azure AD), AD FS (on-premises), Okta, Auth0, or Generic SAML 2.0 (covers Keycloak /protocol/saml/descriptor, Ping, Google Workspace, and similar). Follow-on screens seed example metadata URLs and default attribute names.

Provide either an HTTPS federation metadata URL or a local federation XML absolute path — choose exactly one. Later panels cover attribute options (friendlyName, valuePath, stripPrefix, attribute.user, attribute.displayName, ForceAuthn, RequestedAuthnContext, NameID format).

Group → Role Mapping

The closing panels map IdP group attribute values to Obsidian roles, including Require role assignment (default yes) and optional dynamicRole.prefix / suffix. At least one mapping to the Admin role is required. See SAML Authentication Properties for the full property reference.

SP metadata artefacts

During install the tooling writes sp-metadata.xml under the Obsidian deployment directory; the same metadata is available live at /saml/metadata after startup. Register whichever artefact your IdP admin prefers.

Before you complete install

• Ensure ACS and Entity ID https URLs are reachable from IdPs (align with reverse proxies).
• For Entra 150+ group memberships in SAML assertions, expect attribute suppression — filter groups or map assigned app roles instead. (OIDC uses a 200 group threshold; the numbers differ by protocol.)

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.

As of Obsidian 7.1.0, JNDI Email Path must be a JNDI name (optional java: prefix). See Advanced Configuration.

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.

As of Obsidian 7.1.0, JavaScript is a Script Libraries option. It installs OpenJDK Nashorn so JavaScript jobs run on JDK 15 and later. The option is cleared by default. Automated install XML uses the script.javascript key. Omit the key or set it to false to leave JavaScript uninstalled.

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.

As of Obsidian 7.1.0, that panel choice still selects one third-party mail stack and also writes com.carfey.jdk.mail.implementation ( com.carfey.jdk.mail.JavaMailEmail or com.carfey.jdk.mail.JakartaMailEmail). See Advanced Configuration.

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.x.x 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.x.x.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.x.x.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.x.x.jar

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

Additional Maven dependencies

As of Obsidian 7.1.0, after the installer dependency-source panel, an optional panel accepts extra Maven libraries for the scheduler WAR and standalone runtime.

Use a file, paste text, or both. Pasted text is used when both are set. Leave both empty to skip. Accepted formats:

• One group:artifact:version per line (# comments allowed)
• A Maven <dependencies> XML block
• JSON:

{"dependencies":["com.acme:jobs:1.0.0"], "overrides":{"com.google.guava:guava":"33.0.0-jre"}, "exclude":["com.unwanted:lib"]}

Headless / automated install entries on UserInputPanel.37:

• obsidian.install.extra.deps.file — absolute path to a file in one of those formats
• obsidian.install.extra.deps.inline — the same content as panel paste (wins if both are set)

Automated-install XML that omits these UserInputPanel.37 entries (or the CustomerDepsPanel element) installs no extra libraries.

The installer walks compile and runtime transitives from each root POM, following each module's parent POM chain and scope=import BOM dependencyManagement, so a short root list is enough when those parents and BOMs are reachable. A versioned dependencies entry pins that group:artifact. Use overrides only for a coordinate that is not a root. A following panel lists version conflicts. When two extra roots require different versions of the same group:artifact, or the extra list names two versions of one group:artifact, choose one version or exclude it. When a requested library is already shipped in WEB-INF/lib, keep the Obsidian version (default), replace it, or exclude it.

Headless / automated install entries on panel id CustomerDepsPanel:

• obsidian.install.dep.override. plus group:artifact — pin that coordinate to a version
• obsidian.install.dep.exclude.N — drop a group:artifact
• obsidian.install.dep.accept-obsidian.N — keep the shipped Obsidian version
• obsidian.install.dep.replace.N — replace the shipped JAR with the extra version

JSON overrides / exclude are equivalent to the first two keys and run before conflict detection. An override does not skip the shipped-library choice; declare accept-obsidian or replace (or exclude) for that coordinate. An undeclared conflict fails and names the group:artifact.

For an air-gapped install, add every extra root, transitive, parent, and BOM JAR and POM to the offline cache directory used for Obsidian's own libraries (see Offline or restricted-network install). POMs use the same layouts as JARs.

Log path

As of Obsidian 7.1.0, when more than one of Obsidian WAR, Standalone Admin WAR, or Standalone Runtime is selected, the first configuration panel also shows an optional path for each selected artifact. Leave a field blank to use the required default Log Path. Unselected packs do not show a path field. When only one of those artifacts is selected, only the default field is shown.

Headless / automated install entries on UserInputPanel.0:

• log.path — required default (used when an artifact key is omitted)
• log.path.war — Obsidian WAR
• log.path.admin — Standalone Admin WAR
• log.path.standalone — Standalone Runtime

Embedded Tomcat uses the WAR it launches. There is no separate embed log path.

UserInputPanel.18 has an optional sidecar file and the next panel shows the generated log4j2.xml to edit (or leave the generated default).

• obsidian.install.log4j2.file — optional sidecar XML file
• obsidian.install.log4j2.inline — the XML in the installer (paste wins when both are set)

${obsidian.log.file}, ${obsidian.log.dir}, and ${obsidian.log.name} (the log file basename, used by the rollover Delete filter) are replaced from the Log Path fields for each artifact. A hardcoded path is used as-is for every artifact. Leave both entries empty to bake the generated default.

Example logger inside Loggers:

<Logger name="com.carfey.ops.schedule" level="debug" additivity="false"><AppenderRef ref="fileLogger"/></Logger>

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.