Upgrading Obsidian

There are a number of options available to you. Select the one that best suits your situation.

Note that you don't necessarily need to go through the installer UI again, although you're free to do so. Since the primary purpose of the installer is to provide fully configured Obsidian artifacts and your environment would already be configured, you really just need the updated artifacts (libraries and WAR files). Even if you want to take advantage of new configuration options, you could use the Configuration Reference to make the necessary changes.

Upgrading to 7.0.0

Remember Me removal

The Remember Me feature has been removed. No operator action is required. On first startup after the upgrade, Release7Dot0Dot0Upgrader runs automatically and drops the USER_COOKIE table (if it exists) and removes the allowRememberMe system parameter. Users who had active Remember Me sessions will be prompted to log in on their next visit.

OAuth / OIDC authentication (optional)

Obsidian 7.0.0 adds an optional OAuth / OIDC authenticator. Existing installations continue to use their current authenticator (DB or LDAP) with no changes required. To switch to OAuth / OIDC: configure OAuthAuthenticator properties in the Obsidian configuration file (com.carfey.properties or YAML equivalent) — see Authenticator#OAuthAuthenticator_(OIDC_SSO) and Advanced_Configuration#OAuth_/_OIDC_Authentication_Properties — then restart Obsidian.

Migrating saved automated install XML (Obsidian 6 → 7)

If you use headless / automated install with an XML file saved from Obsidian 6 (IzPack 4.3.5), you must migrate that file before installing with Obsidian 7. Unzip the Obsidian 7.0.0 download and run the migrate helper (Windows: migrate-headless.bat --in my-old-config.xml --out my-config-izpack5.xml, Unix: migrate-headless.sh with the same arguments, or java -jar Obsidian-Install-Migrate.jar --in my-old-config.xml --out my-config-izpack5.xml). Review my-config-izpack5.xml.migration-report.txt only if the tool creates one — if it lists unknown panels or keys, contact Carfey support. Then install with the migrated file: java -jar Obsidian-Install-7.0.0.jar my-config-izpack5.xml. The migrate helper covers Obsidian's standard installer panels only and does not modify product installer descriptors or custom installers.

Upgrading evaluation installs (Jetty quick start → embedded Tomcat)

Obsidian 7.0.0 removes the Jetty quick-start pack and jetty-home distribution. If you previously installed with a Jetty-based quick start or embedded Jetty pack:

1. Re-run the installer or edit your automated install XML to select Obsidian Embedded Tomcat JAR (scheduler) or Obsidian Standalone Admin Embedded Tomcat JAR (admin), and the matching WAR pack.
2. Remove references to legacy Jetty pack names in any saved automated install XML. If the file is still IzPack 4 format, run the migrate helper first (see Migrating saved automated install XML).
3. After install, use webObsidian start scheduler (or start adminOnly) instead of the Jetty start.jar.

If the migrate helper produces a .migration-report.txt file, review it before running the install — it will flag any pack renames that need attention.

Installer breaking changes (Obsidian 6 → 7)

• Headless automated install XML must use IzPack 5 panel class names and id attributes — migrate saved Obsidian 6 files with the tooling above.
• GUI installer — same configuration panels and outcomes; underlying engine is IzPack 5.
• Release zip — adds migrate JAR/scripts.
• Groovy and Flexmark libraries are now modular — see Advanced_Configuration#Dependent_Libraries.

Automated Installer File

This section applies if you have saved an automated installer XML file from a previous version of Obsidian.

If the release notes do not document any installer incompatibility between source and target releases, this means there are no new configuration options available and you can use your automated installer file without modification.

You can see installation configuration for more information, but essentially all you need to do is run java -jar Obsidian-Install-n-n-n.jar my-obsidian-install-config.xml. You may wish to change the target installation path before proceeding.

If the release notes do document installer incompatibility between releases, follow the relevant instructions to update your installer configuration file and then follow the same procedure.

Existing Configuration

You have a choice when it comes to upgrading an Obsidian environment that is already configured.

1. You can rerun the installer UI to get the configured artifacts.
2. Use the quickstart installation mode to get the updated artifacts with the quickstart configuration.

Existing Configuration with QuickStart

If you are using overrides support to specify ALL your configuration items, you likely are ready to go as the default configuration items are being overridden.

Otherwise, you are relying at least partially on embedded configuration items. You will need to replace the quickstart configuration values with your existing configuration values. The Obsidian WAR files have the com.carfey.(properties/yaml) file inside at WEB-INF/classes/com.carfey.(properties/yaml) and the standalone installation has it at the root of obsidian-properties-configuration.jar or obsidian-yaml-configuration.jar.

Performing the Upgrade

We highly recommend performing a database backup and an installation backup (filesystem backup) prior to performing the upgrade with rollback strategies in place to restore the previous installation with its data.

Obsidian automatically applies any database modifications during the first deployment of the new version.

The simplest mechanism is to bring down all your Obsidian Scheduler nodes during a quiet scheduling period. Deploy the new artifacts and start the each node individually verifying its startup before proceeding to the next node.

Database Upgrade Scripts

Available as of version 3.0

When you start Obsidian, it will automatically upgrade the schema in your target database. However, if you wish to run Obsidian with a database user without create and drop privileges, or simply wish to prepare your database structure ahead of time, you can use the database upgrade scripts provided with your download zip file under the "db_scripts" directory.

First locate all files named "*upgrade.sql" under the directory for the database you are using under the "db_scripts" directory. Statements within these files contain the token "$px$" to enable table prefixes. Before you run the SQL files, replace all instances of the token "$px$" (without quotes) with a table prefix 6 characters or shorter (letters and underscores supported), or with blank.

Then, in your SQL client of choice, execute the scripts in order of their version numbers. This will upgrade your schema to your target version.

You'll need to allow the data portion of the migrations to execute while preventing the DDL scripts to run. To do this, you need to disable DDL Updates.

Performing an Always On Cluster Upgrade

If you absolutely must maintain at least one node running, Obsidian should be able to continue scheduling and executing on a single node while the other(s) is/are upgraded although we make no assurances and recommend that you test out your specific upgrade scenario first. Depending on the content between source and target releases, we also recommend that you don't attempt to perform other changes such as job configuration changes, failure resubmissions, etc. during this time. Feel free to contact us with questions about your specific upgrade scenario.

Always On Cluster Upgrade Steps

1. Bring down all but one Obsidian Scheduler node.
2. Target a downed node for upgrade.
3. Deploy the upgraded artifacts to the targeted downed node.
4. Startup the upgraded node.
5. Verify successful startup.
6. Bring down the still-running older Obsidian Scheduler node.
7. Repeat steps 3-5 for each remaining downed node in the cluster.