Getting Started - Revision history

Craig at 20:38, 9 July 2026

2026-07-09T20:38:37Z

← Older revision		Revision as of 20:38, 9 July 2026
Line 207:		Line 207:
	: Directory containing JARs required to run the standalone scheduler process. '''obsidian-yaml-configuration.jar''' or '''obsidian-properties-configuration.jar''' contains the Obsidian configuration file. To make configuration changes for the standalone scheduler, update the configuration file within this JAR.		: Directory containing JARs required to run the standalone scheduler process. '''obsidian-yaml-configuration.jar''' or '''obsidian-properties-configuration.jar''' contains the Obsidian configuration file. To make configuration changes for the standalone scheduler, update the configuration file within this JAR.

	== Starting Obsidian with embedded Tomcat ==		= Starting Obsidian with embedded Tomcat =

	If you selected the '''Obsidian Embedded Tomcat JAR''' or '''Obsidian Standalone Admin Embedded Tomcat JAR''' pack during installation, use the '''webObsidian''' scripts to start and stop Obsidian.		If you selected the '''Obsidian Embedded Tomcat JAR''' or '''Obsidian Standalone Admin Embedded Tomcat JAR''' pack during installation, use the '''webObsidian''' scripts to start and stop Obsidian.

Craig at 20:38, 9 July 2026

2026-07-09T20:38:07Z

← Older revision		Revision as of 20:38, 9 July 2026
Line 207:		Line 207:
	: Directory containing JARs required to run the standalone scheduler process. '''obsidian-yaml-configuration.jar''' or '''obsidian-properties-configuration.jar''' contains the Obsidian configuration file. To make configuration changes for the standalone scheduler, update the configuration file within this JAR.		: Directory containing JARs required to run the standalone scheduler process. '''obsidian-yaml-configuration.jar''' or '''obsidian-properties-configuration.jar''' contains the Obsidian configuration file. To make configuration changes for the standalone scheduler, update the configuration file within this JAR.

	=== Starting Obsidian with embedded Tomcat ===		== Starting Obsidian with embedded Tomcat ==

	If you selected the '''Obsidian Embedded Tomcat JAR''' or '''Obsidian Standalone Admin Embedded Tomcat JAR''' pack during installation, use the '''webObsidian''' scripts to start and stop Obsidian.		If you selected the '''Obsidian Embedded Tomcat JAR''' or '''Obsidian Standalone Admin Embedded Tomcat JAR''' pack during installation, use the '''webObsidian''' scripts to start and stop Obsidian.

Craig at 20:37, 9 July 2026

2026-07-09T20:37:40Z

@@ Line 92: / Line 92: @@
 '''Note:''' If you see a <code>java.net.BindException: Permission denied</code> error on startup, you will need to use an alternate port. See [[Troubleshooting]] for details on how to change this.
 == Quick Method Using Existing Database ==
@@ Line 224: / Line 206: @@
 ; standalone
 : Directory containing JARs required to run the standalone scheduler process. '''obsidian-yaml-configuration.jar''' or '''obsidian-properties-configuration.jar''' contains the Obsidian configuration file. To make configuration changes for the standalone scheduler, update the configuration file within this JAR.
 = Embedding Obsidian & Customizing Artifacts =

Craig at 20:36, 9 July 2026

2026-07-09T20:36:16Z

← Older revision		Revision as of 20:36, 9 July 2026
Line 92:		Line 92:

	'''Note:''' If you see a <code>java.net.BindException: Permission denied</code> error on startup, you will need to use an alternate port. See [[Troubleshooting]] for details on how to change this.		'''Note:''' If you see a <code>java.net.BindException: Permission denied</code> error on startup, you will need to use an alternate port. See [[Troubleshooting]] for details on how to change this.

			=== Starting embedded Tomcat ===

			From the Obsidian install directory:

			webObsidian.bat start scheduler
			(Unix: ./webObsidian.sh start scheduler)

			For standalone admin only:

			webObsidian.bat start adminOnly

			Stop:

			webObsidian.bat stop
			(Unix: ./webObsidian.sh stop)

			Default HTTP port is '''8080'''. To change ports, pass '''-Dembedded.tomcat.http.port''', '''-Dembedded.tomcat.stop.port''', and '''-Dembedded.tomcat.stop.key''' as JVM arguments before starting.

	== Quick Method Using Existing Database ==		== Quick Method Using Existing Database ==

Craig at 20:29, 9 July 2026

2026-07-09T20:29:33Z

← Older revision		Revision as of 20:29, 9 July 2026
Line 14:		Line 14:
	* Obsidian 5.x.x and 6.x.x run on Java 11 or above (Obsidian 4.x.x runs on Java 1.7 or above)		* Obsidian 5.x.x and 6.x.x run on Java 11 or above (Obsidian 4.x.x runs on Java 1.7 or above)
	* Obsidian's administration web application is a servlet application.		* Obsidian's administration web application is a servlet application.
			** 7.x.x has been tested on Tomcat 10.x
	** 6.x.x has been tested on Tomcat 10.x and Jetty 11.x (Jakarta Servlet 5.0)		** 6.x.x has been tested on Tomcat 10.x and Jetty 11.x (Jakarta Servlet 5.0)
	** 5.x.x has been tested on Tomcat 9.x and Jetty 10.x (Javax Servlet 4.0)		** 5.x.x has been tested on Tomcat 9.x and Jetty 10.x (Javax Servlet 4.0)
Line 82:		Line 83:
	# Ensure you have a JDK (11 or up for Obsidian 6.x.x & 5.x.x, 1.7 or up for Obsidian 4.x.x) installed and that the <code>JAVA_HOME</code> environment variable is set to your JDK installation directory.		# Ensure you have a JDK (11 or up for Obsidian 6.x.x & 5.x.x, 1.7 or up for Obsidian 4.x.x) installed and that the <code>JAVA_HOME</code> environment variable is set to your JDK installation directory.
	# Unzip the Obsidian download zip file to a directory of your choice.		# Unzip the Obsidian download zip file to a directory of your choice.
	# At the command line, in the zip extraction directory, run the [[Installation_Guide\|installer]] using this command, substituting the appropriate Obsidian version number: <code>java -jar Obsidian-Install-''n''-''n''-''n''.jar h2-~~jetty~~-quick-start.xml</code>		# At the command line, in the zip extraction directory, run the [[Installation_Guide\|installer]] using this command, substituting the appropriate Obsidian version number: <code>java -jar Obsidian-Install-''n''-''n''-''n''.jar h2-tomcat-quick-start.xml</code>
	# Start Obsidian using the command: <code>./webObsidian.sh start scheduler</code> for Linux or <code>webObsidian.bat start scheduler</code> for Windows.		# Start Obsidian using the command: <code>./webObsidian.sh start scheduler</code> for Linux or <code>webObsidian.bat start scheduler</code> for Windows.
	# Go to http://localhost:8080 in your browser and check out your fully functional Obsidian web application and scheduler! You can log in to the admin web application with the default user ''admin'' and password ''changeme''.		# Go to http://localhost:8080 in your browser and check out your fully functional Obsidian web application and scheduler! You can log in to the admin web application with the default user ''admin'' and password ''changeme''.
Line 161:		Line 162:
	To run the installer, please follow our detailed [[Installation_Guide\|installation guide]].		To run the installer, please follow our detailed [[Installation_Guide\|installation guide]].

	== Installer-Created Artifacts ==		=== Installer-Created Artifacts ===

	Once you've run the installer, your installation directory will look something like the following, depending on which artifacts you chose to generate~~. Key files and directories are shown below~~.		Once you've run the installer, your installation directory will look something like the following, depending on which artifacts you chose to generate.

	<pre>		<pre>
	├───db_scripts		├───db_scripts
	└───Obsidian-6.n.n		└───Obsidian-7.0.0
	│ com.carfey.yaml.reference		│ com.carfey.yaml.reference
	│ obsidian.war		│ obsidian.war
Line 180:		Line 181:
	│ webObsidian.sh		│ webObsidian.sh
	│		│
	~~├───jetty~~		├───embed-tomcat-lib (present when an Embedded Tomcat pack is selected)
	├───license		├───license
	├───logs		├───logs
Line 188:		Line 189:
	obsidian.jar		obsidian.jar
	</pre>		</pre>
	~~The installer creates a top-level directory named <code>Obsidian-''n''.''n''.''n''</code> containing generated artifacts. The key files and directories are:~~

	* '''com.carfey.yaml.reference~~'''~~ or ~~'''~~com.carfey.properties.reference~~''' -~~ Copy of configuration file generated by the installer.		The installer creates a top-level directory named '''Obsidian-n.n.n''' containing generated artifacts. The key files and directories are:
	* '''obsidian.war~~''' -~~ Combined scheduler and admin web application WAR. ~~This can be deployed~~ directly to a servlet container. ~~This artifact can be customized~~ by adding your job code and dependencies as ~~JARS~~ to ~~the <code>~~/WEB-INF/lib~~</code> directory~~ within the archive.
	* '''standaloneObsidian.bat~~'''~~ and ~~'''~~standaloneObsidian.sh~~''' -~~ Windows and Linux scripts to start the standalone scheduler process with no web application. ~~The standalone scheduler can be customized~~ by adding your job code and dependencies as ~~JARS~~ to the ~~<code>~~standalone~~</code>~~ directory.		; com.carfey.yaml.reference or com.carfey.properties.reference
	* '''~~webObsidian.bat~~''' ~~and~~ '''~~webObsidian~~.sh''' ~~- .bat - Windows and Linux scripts~~ to ~~start either~~ the ~~standalone web application or~~ combined scheduler ~~and~~ admin ~~web application within~~ the ~~bundled Jetty server~~.		: Copy of the configuration file generated by the installer.
	* '''standaloneObsidianAdmin.war~~''' -~~ Standalone admin web application WAR (no scheduler). ~~This can be deployed~~ directly to a servlet container.		; obsidian.war
	* '''~~standalone~~''' - Directory containing JARs ~~that Obsidian requires~~ to run the standalone scheduler process. ~~The standalone scheduler can be customized by adding your job code and dependencies as JARS to this directory.~~		: Combined scheduler and admin web application WAR. Deploy directly to a servlet container, or run locally using the Embedded Tomcat pack (see below). Customise by adding your job code and dependencies as JARs to '''/WEB-INF/lib''' within the archive.
	** '''obsidian-yaml-configuration.jar''' or '''obsidian-properties-configuration.jar''' ~~- JAR file containing~~ the Obsidian configuration file ~~- either <code>com.carfey.yaml</code> or <code>com.carfey~~.~~properties</code> respectively. If you wish to~~ make configuration changes for the standalone scheduler, the configuration file within this JAR ~~will need to be updated~~.		; standaloneObsidian.bat and standaloneObsidian.sh
			: Windows and Linux scripts to start the standalone scheduler process with no web application. Customise by adding your job code and dependencies as JARs to the '''standalone''' directory.
			; webObsidian.bat and webObsidian.sh
			: Windows and Linux scripts to start Obsidian using the embedded Tomcat runtime (requires the '''Obsidian Embedded Tomcat JAR''' or '''Obsidian Standalone Admin Embedded Tomcat JAR''' pack). Use '''start scheduler''' to run the combined scheduler+admin WAR, or '''start adminOnly''' to run the standalone admin WAR. Stop with '''stop'''.
			; standaloneObsidianAdmin.war
			: Standalone admin web application WAR (no scheduler). Deploy directly to a servlet container or run via the embedded Tomcat pack.
			; embed-tomcat-lib
			: Present when an Embedded Tomcat pack is selected. Contains the embedded Tomcat runtime JARs used by the '''webObsidian''' scripts.
			; standalone
			: Directory containing JARs required to run the standalone scheduler process. '''obsidian-yaml-configuration.jar''' or '''obsidian-properties-configuration.jar''' contains the Obsidian configuration file. To make configuration changes for the standalone scheduler, update the configuration file within this JAR.

	= Embedding Obsidian & Customizing Artifacts =		= Embedding Obsidian & Customizing Artifacts =

Craig at 19:24, 9 July 2026

2026-07-09T19:24:12Z

← Older revision		Revision as of 19:24, 9 July 2026
Line 150:		Line 150:

	Alternatively, to use LDAP authentication, select the LDAP option in the installer and enter your LDAP details.		Alternatively, to use LDAP authentication, select the LDAP option in the installer and enter your LDAP details.

			As of 7.0.0, you can also select OAuth / OIDC authentication to enable Single Sign-On via an external identity provider. See [[Authenticator#OAuthAuthenticator_(OIDC_SSO)\|OAuthAuthenticator]] for details.

	Finally, you may implement your own [[authenticator\|custom authenticator]] Java class, which you also enter when running the installer.		Finally, you may implement your own [[authenticator\|custom authenticator]] Java class, which you also enter when running the installer.

Craig: /* Updating the Properties File in Admin Web Applications */

2024-12-28T02:07:50Z

Updating the Properties File in Admin Web Applications

← Older revision		Revision as of 02:07, 28 December 2024
Line 247:		Line 247:
	# Obtain the WAR artifact from your installation that requires changes. This is either <code>obsidian.war</code> or <code>standaloneObsidianAdmin.war</code>.		# Obtain the WAR artifact from your installation that requires changes. This is either <code>obsidian.war</code> or <code>standaloneObsidianAdmin.war</code>.
	# Extract the WAR file to a clean directory.		# Extract the WAR file to a clean directory.
	# Edit the <code>com.carfey.properties</code> file within the subdirectory <code>WEB-INF/classes</code> and save your changes.		# Edit the <code>com.carfey.(yaml/properties)</code> file within the subdirectory <code>WEB-INF/classes</code> and save your changes.
	# Rebundled the WAR artifact using a zip utility or the JDK <code>jar</code> utility.		# Rebundled the WAR artifact using a zip utility or the JDK <code>jar</code> utility.
	#* Some zip utilities such as 7Zip will allow you to edit files within an archive directly without the previous steps. It is generally safe to do so.		#* Some zip utilities such as 7Zip will allow you to edit files within an archive directly without the previous steps. It is generally safe to do so.

Craig: /* Embedding Obsidian - Importing Libraries and Properties File */

2024-12-28T02:07:31Z

Embedding Obsidian - Importing Libraries and Properties File

← Older revision		Revision as of 02:07, 28 December 2024
Line 211:		Line 211:
	#* These can be obtained from the <code>standalone</code> directory of your installation. Make sure you '''exclude''' <code>obsidian-(yaml/properties)-configuration.jar</code>		#* These can be obtained from the <code>standalone</code> directory of your installation. Make sure you '''exclude''' <code>obsidian-(yaml/properties)-configuration.jar</code>
	#* Ensure your Maven, Gradle or Ant files are updated to include all required libraries in your build, along with your IDE.		#* Ensure your Maven, Gradle or Ant files are updated to include all required libraries in your build, along with your IDE.
	# Make a copy of <code>com.carfey.yaml.reference</code> or <code>com.carfey.properties.reference</code> from your installation with the <code>.~~copy~~</code> suffix removed, and add it to your project's classpath.		# Make a copy of <code>com.carfey.yaml.reference</code> or <code>com.carfey.properties.reference</code> from your installation with the <code>.reference</code> suffix removed, and add it to your project's classpath.
	#* This is typically just a matter of adding it to your project's resources directory.		#* This is typically just a matter of adding it to your project's resources directory.
	#* From now on, you can update this file to change the various configuration options such as database connection details.		#* From now on, you can update this file to change the various configuration options such as database connection details.

Craig: /* Embedding Obsidian - Importing Libraries and Properties File */

2024-12-28T02:07:13Z

Embedding Obsidian - Importing Libraries and Properties File

← Older revision		Revision as of 02:07, 28 December 2024
Line 209:		Line 209:

	# Import all required [[Advanced_Configuration#Dependent_Libraries\|Obsidian JAR files]] into your project and reference them in your build files.		# Import all required [[Advanced_Configuration#Dependent_Libraries\|Obsidian JAR files]] into your project and reference them in your build files.
	#* These can be obtained from the <code>standalone</code> directory of your installation. Make sure you '''exclude''' <code>obsidian-~~props~~.jar</code>		#* These can be obtained from the <code>standalone</code> directory of your installation. Make sure you '''exclude''' <code>obsidian-(yaml/properties)-configuration.jar</code>
	#* Ensure your Maven, Gradle or Ant files are updated to include all required libraries in your build, along with your IDE.		#* Ensure your Maven, Gradle or Ant files are updated to include all required libraries in your build, along with your IDE.
	# Make a copy of <code>com.carfey.properties.~~copy~~</code> from your installation with the <code>.copy</code> suffix removed, and add it to your project's classpath.		# Make a copy of <code>com.carfey.yaml.reference</code> or <code>com.carfey.properties.reference</code> from your installation with the <code>.copy</code> suffix removed, and add it to your project's classpath.
	#* This is typically just a matter of adding it to your project's resources directory.		#* This is typically just a matter of adding it to your project's resources directory.
	#* From now on, you can update this file to change the various configuration options such as database connection details.		#* From now on, you can update this file to change the various configuration options such as database connection details.

Craig: /* Installer-Created Artifacts */

2024-12-28T02:05:11Z

Installer-Created Artifacts

← Older revision		Revision as of 02:05, 28 December 2024
Line 165:		Line 165:
	<pre>		<pre>
	├───db_scripts		├───db_scripts
	└───Obsidian-5.n.n		└───Obsidian-6.n.n
	│ com.carfey.~~properties~~.~~copy~~		│ com.carfey.yaml.reference
	│ obsidian.war		│ obsidian.war
	│ obsidian-builtin-job-src.jar		│ obsidian-builtin-job-src.jar
Line 183:		Line 183:
	└───standalone		└───standalone
	(various JAR files...)		(various JAR files...)
	obsidian-~~props~~.jar		obsidian-yaml-configuration.jar
	obsidian.jar		obsidian.jar
	</pre>		</pre>
	The installer creates a top-level directory named <code>Obsidian-''n''.''n''.''n''</code> containing generated artifacts. The key files and directories are:		The installer creates a top-level directory named <code>Obsidian-''n''.''n''.''n''</code> containing generated artifacts. The key files and directories are:

	* '''com.carfey.properties.~~copy~~''' - Copy of ~~properties~~ file generated by the installer.		* '''com.carfey.yaml.reference''' or '''com.carfey.properties.reference''' - Copy of configuration file generated by the installer.
	* '''obsidian.war''' - Combined scheduler and admin web application WAR. This can be deployed directly to a servlet container. This artifact can be customized by adding your job code and dependencies as JARS to the <code>/WEB-INF/lib</code> directory within the archive.		* '''obsidian.war''' - Combined scheduler and admin web application WAR. This can be deployed directly to a servlet container. This artifact can be customized by adding your job code and dependencies as JARS to the <code>/WEB-INF/lib</code> directory within the archive.
	* '''standaloneObsidian.bat''' and '''standaloneObsidian.sh''' - Windows and Linux scripts to start the standalone scheduler process with no web application. The standalone scheduler can be customized by adding your job code and dependencies as JARS to the <code>standalone</code> directory.		* '''standaloneObsidian.bat''' and '''standaloneObsidian.sh''' - Windows and Linux scripts to start the standalone scheduler process with no web application. The standalone scheduler can be customized by adding your job code and dependencies as JARS to the <code>standalone</code> directory.
Line 194:		Line 194:
	* '''standaloneObsidianAdmin.war''' - Standalone admin web application WAR (no scheduler). This can be deployed directly to a servlet container.		* '''standaloneObsidianAdmin.war''' - Standalone admin web application WAR (no scheduler). This can be deployed directly to a servlet container.
	* '''standalone''' - Directory containing JARs that Obsidian requires to run the standalone scheduler process. The standalone scheduler can be customized by adding your job code and dependencies as JARS to this directory.		* '''standalone''' - Directory containing JARs that Obsidian requires to run the standalone scheduler process. The standalone scheduler can be customized by adding your job code and dependencies as JARS to this directory.
	** '''obsidian-~~props~~.jar''' - JAR file containing the Obsidian ~~properties~~ file <code>com.carfey.properties</code>. If you wish to make configuration changes for the standalone scheduler, the ~~properties~~ file within this JAR will need to be updated.		** '''obsidian-yaml-configuration.jar''' or '''obsidian-properties-configuration.jar''' - JAR file containing the Obsidian configuration file - either <code>com.carfey.yaml</code> or <code>com.carfey.properties</code> respectively. If you wish to make configuration changes for the standalone scheduler, the configuration file within this JAR will need to be updated.

	= Embedding Obsidian & Customizing Artifacts =		= Embedding Obsidian & Customizing Artifacts =