Getting Started - Prior to Obsidian 2.4.0

From Obsidian Scheduler
Jump to: navigation, search

This guide covers your initial installation and setup of Obsidian Scheduler for versions prior to Obsidian 2.4.0. It also covers the startup and deployment options available to you, and various tweaks you can make.

You should have already downloaded Obsidian Scheduler. If you have not done so, see Downloads.

Quick Start

If you wish to evaluate or quickly check out Obsidian, here are the steps you need to follow:

  1. Create database for use by Obsidian (MySQL 5, Oracle 10g or PostgreSQL 9). If a database already exists that you wish to share or you wish to use H2 in memory database with filesystem failover, you may skip this step, though you may wish to consult Obsidian Tables before proceeding.
  2. Use the provided Ant installer file to configure. Run the following command and follow the instructions.
    ant install.props
  3. Deploy the admin/scheduler war to your chosen servlet container (Tomcat, Jetty or Winstone).
  4. Log in to the admin web application with the default user admin and password changeme.

Really Quick Start With H2 and Winstone

If you wish to quickly try Obsidian without setting up a database or web server, you can take advantage of our in-memory H2 database and Winstone web server support.

With your provided zip installation package, use Ant to set up and start your combined scheduler and webapp using these steps. You will need a recent version of Ant installed.

  1. Ensure you have a JDK (1.6 or up) installed and that the JAVA_HOME environment variable is set to your JDK installation directory.
  2. Unzip the obsidian package zip file and execute your chosen command below in the unzip directory (it contains build.xml and obsidian.war).
  3. If you have Ant, at the command line, execute the command below to start the scheduler web application. This will start a web server running on port 80. To configure this in more detail, simple invoke ant and help will be listed.
    ant run.war
  4. If you don't have Ant, you can run winstone directly using
    java -cp winstone/winstone-0.9.10.jar winstone.Launcher --warfile=obsidian.war --config=winstone/ --commonLibFolder=winstone/lib 
    from within the winstone directory. If winstone complains about a missing Tools.jar file or you encounter an error in your browser saying JAVA_HOME is not set, you can add an argument when you start winstone to point it to the location of your JDK:
  5. Go to http://localhost and check out your fully functional Obsidian web app and scheduler! You can log in to the admin web application with the default user admin and password changeme.

Note: If you restart the demo instance using H2 and see "lock wait timeout" or similar errors in the log screen, you may have to delete your H2 lock file. By default, the file name is obsidianTrial.lock.db and is located in local directory.

Note: If you see a Permission denied error on startup, you will need to use an alternate port. See Troubleshooting for details on how to change this.

Supported Platforms

  • Obsidian is OS-independent.
  • Obsidian runs on Java 1.6 or above.
  • Obsidian is fully tested on MySQL 5.1 & 5.5, Oracle 10g && 11.x, PostgreSQL 9 and H2. Larger major versions are likely to work but are not supported.
  • Obsidian's administration web application is tested on Tomcat 6 & 7, Jetty 9 and Winstone 0.9, but is likely to work in any compliant servlet container version 2.4 or up. It works on all modern browsers and is tested on recent versions of Chrome and Firefox, plus IE 10.

Note: Scheduler instances must have access to contact license servers over the Internet, or access to an internal proxy license server that you may set up. See Licenses & Nodes for more information.

Choose Your Installation Type

If you skipped the Quick Start section or wish more control over your installation, the following sections will detail your choices and steps to configure and deploy Obsidian.

Obsidian consists of two main processes:

  • Scheduler
  • Admin Web Application

These can be run together or in separate processes in the following configurations:

  1. Standalone Scheduler
  2. Embedded Scheduler (within your application)
  3. Standalone Admin Web Application
  4. Combined Scheduler and Admin Web Application

Choosing which option works best for you depends on your specific needs. The setups which are suitable for most cases would be:

  • Using an embedded scheduler (option 2) along with a standalone admin webapp (option 3)
  • Using a combined scheduler and admin web app (option 4)

You may wish to use multiple configurations together. For example, you may combine standalone schedulers along with a combined scheduler and web application.

Note: A key server proxy package also exists and you may choose to deploy it within a servlet container like Jetty or Tomcat. See Key Server Proxy for details on key server proxies.

Initial Setup

This section covers the setup required after you've selected your deployment setup.


Obsidian relies on a database which should be configured before attempting to deploy your scheduler processes.

Currently Obsidian supports MySQL 5.1/5.5/5.6, Oracle 10g & 11.x, PostgreSQL 9 and H2.

To configure which database Obsidian will use, you can simply use the provided installer Ant file to setup the configuration that is stored in that is to be accessible on the classpath. To review a detailed breakdown of the resulting configuration, see Advanced Configuration. To make use of our external property file override support, use the System property Between the default properties and the override, all expected properties must be specified. Any properties found in both files will use the override file's values. Usage:

Note that the database must exist before deployment, but Obsidian will automatically perform initial setup including table creation. When you first deploy your scheduler web app, either standalone admin or embedded scheduler, it will perform all necessarily initialization.

Note: Obsidian needs to create the tables in the target database. If the schema is shared with your application’s tables, please ensure there are no name conflicts. If there are conflicts, separate schemas/databases can be used, or a table prefix can be specified as shown in Advanced Configuration. See the Obsidian Tables that are created upon first deployment.

Alternate Oracle Schemas

Note: This feature is available as of Obsidian 2.1.

After allowing Obsidian to create the target schema fully by deploying it a single time, Obsidian can be run with an alternate user by specifying the target schema on Oracle databases. See Advanced Configuration for the property to set in the installation properties file.

If you use a separate user from the schema owner, you must grant the user certain privileges for Obsidian to function correctly.


The Obsidian admin web application supports both native users and LDAP-enabled authentication or you can implement your own authenticator.

By default, it is configured to use native login, and a default “admin” user is created when the scheduler is first deployed. Users can then be created and managed from within the admin management console.

To use LDAP-based authentication, following the instructions provided in the installer Ant file. To review a detailed breakdown of the resulting configuration, see Advanced Configuration.


You are now ready to deploy your scheduler and/or admin web application. You may first wish view your high-level deployment options.

Before deploying Obsidian, you'll have to obtain the installation package which includes various deployment artifacts at Downloads.

Classpath Notes

To run a scheduler with your custom code and jobs, you need to ensure the scheduler process classpath includes your jars. This applies to all the deployment options listed below, including the web application. If a compiled job is updated, you will have to restart your application or the servlet container after deploying updated jars. For details on setting your classpath, follow these guidelines.

Setting Host Names

Obsidian instances will automatically assign themselves host names if no host name is explicitly set, but you may wish to give them explicit names to make scheduling and monitoring simpler.

If you wish to assign explicit names, simply set the Java system property schedulerDesignation to the host name of your choice. For example, if starting an instance using the standalone scheduler using java directly, simply add the value -DschedulerDesignation=myHostName to the end of the command.

Standalone Scheduler

To deploy and run the standalone scheduler, use the provided Ant file (target run.obsidian) or in your preferred means invoke the main starter method:

java com.carfey.ops.job.SchedulerStarter start <listenerPort>

Listener port is a port number used by Obsidian to subsequently issue a shut down:

java com.carfey.ops.job.SchedulerStarter stop <listenerPort>

Startup and Shutdown example:

java com.carfey.ops.job.SchedulerStarter start 10451
java com.carfey.ops.job.SchedulerStarter stop 10451

Embedded Scheduler

To deploy and run the embedded scheduler in any existing java application, you can use the included scheduler starter to initialize and shut down the scheduler processes:

// will start scheduler on first call to get()

com.carfey.ops.job.SchedulerStarter starter = com.carfey.ops.job.SchedulerStarter.get(com.carfey.ops.job.SchedulerStarter.SchedulerMode.EMBEDDED);

// ...

// later, we can gracefully shut down the scheduler 

If you are wanting to embed the scheduler instance and/or the admin web app in an existing web application, just extract the necessary info from the WEB-INF/web.xml file in the obsidian.war file withing your installation package. Note the use of our com.carfey.ops.servlet.StartupShutdownListener which takes care of starting up the scheduler instance and using the web container's default shutdown mechanism to ensure graceful shutdown.

Combined Scheduler and Admin Web Application

To deploy and run the combined scheduler and admin web application, simply deploy the obsidian.war file to your servlet container (Jetty or Tomcat) after configuring it appropriately using ant install.props or by editing the file within the WAR directly. You may also need to package your custom jars in with the war so the scheduler can run your custom jobs.

Security Note: By default, the admin web application allows non-secure connections. If you wish to force secure connections through HTTPS, you can edit the web.xml in your war and uncomment the <security-constraint> element in the file. This will force all requests to redirect to an encrypted connection. For details on setting up SSL on your servlet container, refer to its documentation.

Note: If using Winstone to enable running Obsidian without setting up Tomcat or another servlet container, you can use the build.xml provided and run the command ant run.war to run an instance of the Obsidian web application.

Standalone Admin Web Application

As with the combined scheduler and admin web application, to deploy the standalone admin web application, simply deploy the standalone admin war to your servlet container after configuring it appropriately using ant install.props or by editing the file within the WAR directly.

Note: If using Winstone to enable running Obsidian without setting up Tomcat or another servlet container, you can use the build.xml provided and run the command ant run.war to run an instance of the Obsidian web application. First you will need to edit within the winstone directory and change which warfile property is commented out. For the standalone web application, the warfile property should be set to ../standaloneObsidianAdmin.war.

Disabling Job Execution & Scheduling in the Web Application

If you have web application package already built (i.e. a WAR file), you can easily tweak it to enable or disable the scheduler process.

Simply add the following to your WEB-INF/web.xml file after any listener elements:


Disabling Automatic Database Updates

Obsidian automatically applies schema updates and data upgrades to its database on startup. In some cases, it may be desirable to disable this once the database has been fully initialized and upgrades the new versions are not going to be deployed. For example, you may wish to run Obsidian with a user who does not have privileges to modify the database schema.

To do so, you can either set a Java system property, or if you are using the web application WAR, you can add a setting to your WEB-INF/web.xml.

As a system property:

In WEB-INF/web.xml, after any listener elements:


You’re Good to Go!

You are now ready to run the admin web app! As the default admin user if using native authentication or a designated admin user in LDAP, login to the admin web app, navigate to the system tab, and review/adjust system settings as needed. Defaults are provided for all settings.

If you are an admin user, you can log into the admin web application and customize your installation settings using system settings. This has advanced options that allow you to customize scheduler and administration settings.

To get started writing jobs that you can run in Obsidian, see Implementing Jobs.

See the User Guide if you have questions or wish to explore what Obsidian offers.

Default User: Each Obsidian installation using native authentication (the default) starts with a single default user named admin with password changeme. You should change this after your first login. See User Management for how to change a user's password.