Getting Started

This guide covers your initial installation and setup of Obsidian Scheduler.

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 PosgreSQL 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 scheduler.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/winstone.properties --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:

   --javaHome=/path/to/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 the user home directory. Note: If you see a java.net.BindException: 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 7 and Winstone 0.9, but is likely to work in any compliant servlet container version 2.4 or up.

Note: Scheduler instances must have access to contact licence servers over the Internet, or access to an internal proxy licence server that you may set up. See Licences & 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.

Database

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

Currently Obsidian supports MySQL 5.1 & 5.5, 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 com.carfey.properties 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 carfey.properties.file. 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: -Dcarfey.properties.file=/home/obsidian/obsidian.properties.

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. See the Obsidian Tables that are created upon first deployment.

Authentication

The Obsidian admin web application supports both native users and LDAP-enabled authentication.

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.

Deployment

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

Important: To run a scheduler with your custom code and jobs, you simply need to ensure the scheduler process classpath includes your jars. This applies to all the deployment options listed below.

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 class 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.JVM);

// ...

// later, we can gracefully shut down the scheduler 
starter.shutDown();

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.xml in the provided obsidian.war. 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 of the scheduler.

Combined Scheduler and Admin Web Application

To deploy and run the combined scheduler and admin web application, simply deploy the war to your servlet container (Jetty or Tomcat). 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.

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 winstone.properties 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".

You’re Good to Go!

You are now ready to go! You can now 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 the Systems tab. This has advanced options that allow you to customize scheduler and administration settings.

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.