Getting Started - Revision history

Craig at 15:11, 31 July 2026

2026-07-31T15:11:41Z

← Older revision		Revision as of 15:11, 31 July 2026
Line 152:		Line 152:
	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.		As of 7.0.0, you can also select OAuth / OIDC or SAML 2.0 authentication to enable Single Sign-On via an external identity provider. See [[Authenticator#OAuthAuthenticator_(OIDC_SSO)\|OAuthAuthenticator]] and [[Authenticator#SAMLAuthenticator_(SAML_2.0_SSO)\|SAMLAuthenticator]] 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: Remove pre-4.x version references (4.0.0 is the oldest documented release)

2026-07-31T14:49:52Z

Remove pre-4.x version references (4.0.0 is the oldest documented release)

← Older revision		Revision as of 14:49, 31 July 2026
Line 1:		Line 1:
	This Getting Started is for Obsidian 4.0 and newer ~~versions. See the [[Getting_Started_(3.x.x_and_earlier)\|Previous Getting Started]] for prior~~ versions.''		This Getting Started is for Obsidian 4.0 and newer versions.''

Craig at 21:18, 30 July 2026

2026-07-30T21:18:39Z

← Older revision		Revision as of 21:18, 30 July 2026
Line 12:		Line 12:

	* Obsidian is OS-independent, and runs on the Java Virtual Machine. It works in a variety of environments, including Linux, OSX and Windows, and can be run inside virtual machines.		* Obsidian is OS-independent, and runs on the Java Virtual Machine. It works in a variety of environments, including Linux, OSX and Windows, and can be run inside virtual machines.
	* 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, 6.x.x and 7.x.x run on Java 11 or above (Obsidian 4.x.x runs on Java 1.7 or above). A JRE is sufficient — the embedded Tomcat runtime does not compile JSPs and needs no JDK.
	* 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		** 7.x.x has been tested on Tomcat 10.x

Craig at 21:10, 30 July 2026

2026-07-30T21:10:49Z

← Older revision		Revision as of 21:10, 30 July 2026
Line 355:		Line 355:
	To deploy the standalone admin web application, simply deploy the <code>standaloneObsidianAdmin.war</code> file your servlet container of choice (e.g. Tomcat) after configuring it appropriately. You may rename the WAR file to have it deployed under a different context path, if desired (e.g. "ROOT.war" or "obsidian.war"). Consult your servlet documentation to find out how to deploy the application and start the servlet container.		To deploy the standalone admin web application, simply deploy the <code>standaloneObsidianAdmin.war</code> file your servlet container of choice (e.g. Tomcat) after configuring it appropriately. You may rename the WAR file to have it deployed under a different context path, if desired (e.g. "ROOT.war" or "obsidian.war"). Consult your servlet documentation to find out how to deploy the application and start the servlet container.

	'''Note:''' If you ~~want to use~~ the ~~included Jetty server as your servlet container~~, you can use the scripts included in your installation instead of deploying the WAR. This will make the application accessible at http://localhost:8080.		'''Note:''' If you selected the '''Obsidian Standalone Admin Embedded Tomcat JAR''' pack, you can use the '''webObsidian''' scripts included in your installation instead of deploying the WAR. This will make the application accessible at http://localhost:8080.

	* To start		* To start
	** Linux: <code>./webObsidian.sh start adminOnly</code>		** Linux: <code>./webObsidian.sh start adminOnly</code>
Line 391:		Line 392:
	To deploy the combined scheduler and admin web application, simply deploy the <code>obsidian.war</code> file your servlet container of choice (e.g. Tomcat) after configuring it appropriately. You may rename the WAR file to have it deployed under a different context path, if desired (e.g. "ROOT.war"). Consult your servlet documentation to find out how to deploy the application and start the servlet container.		To deploy the combined scheduler and admin web application, simply deploy the <code>obsidian.war</code> file your servlet container of choice (e.g. Tomcat) after configuring it appropriately. You may rename the WAR file to have it deployed under a different context path, if desired (e.g. "ROOT.war"). Consult your servlet documentation to find out how to deploy the application and start the servlet container.

	'''Note:''' If you ~~want to use~~ the ~~included Jetty server as your servlet container~~, you can use the scripts included in your installation instead of deploying the WAR. This will make the web application accessible at the URL http://localhost:8080.		'''Note:''' If you selected the '''Obsidian Embedded Tomcat JAR''' pack, you can use the '''webObsidian''' scripts included in your installation instead of deploying the WAR. This will make the web application accessible at the URL http://localhost:8080.

	* To start		* To start

Craig at 20:55, 30 July 2026

2026-07-30T20:55:42Z

← Older revision		Revision as of 20:55, 30 July 2026
Line 183:		Line 183:
	├───embed-tomcat-lib (present when an Embedded Tomcat pack is selected)		├───embed-tomcat-lib (present when an Embedded Tomcat pack is selected)
	├───license		├───license
			├───linux (present on Unix when an Embedded Tomcat pack is selected)
	├───logs		├───logs
	└───standalone		└───standalone
Line 204:		Line 205:
	; embed-tomcat-lib		; embed-tomcat-lib
	: Present when an Embedded Tomcat pack is selected. Contains the embedded Tomcat runtime JARs used by the '''webObsidian''' scripts.		: Present when an Embedded Tomcat pack is selected. Contains the embedded Tomcat runtime JARs used by the '''webObsidian''' scripts.
			; linux
			: Present on Unix when an Embedded Tomcat pack is selected. Optional user-level systemd unit and desktop-entry templates, plus '''install-embedded-linux-integration.sh''' and '''README-linux-integration.md'''. See [[#Running_Obsidian_as_a_Linux_user_service\|Running Obsidian as a Linux user service]].
	; standalone		; 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.		: 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.

Craig at 20:53, 30 July 2026

2026-07-30T20:53:07Z

← Older revision		Revision as of 20:53, 30 July 2026
Line 230:		Line 230:

	If you are deploying '''obsidian.war''' to your own external servlet container instead, refer to your container's deployment documentation.		If you are deploying '''obsidian.war''' to your own external servlet container instead, refer to your container's deployment documentation.

			= Running Obsidian as a Linux user service =

			On Linux, an embedded Tomcat pack can install a user-level systemd unit and a desktop entry — see [[Installation_Guide#Linux_desktop_and_systemd_integration\|Linux desktop and systemd integration]] for the installer option and the manual '''linux/install-embedded-linux-integration.sh''' script. Installing those files does not enable or start anything, so enable the service yourself:

			systemctl --user enable --now obsidian-embedded@scheduler.service

			Check and stop it with:

			systemctl --user status obsidian-embedded@scheduler.service
			systemctl --user stop obsidian-embedded@scheduler.service

			''./webObsidian.sh stop'' also stops a service-started instance. Do '''not''' run ''./webObsidian.sh start scheduler'' by hand while the service is running — both bind the same HTTP and stop ports.

			== Ports ==

			The unit and the desktop entry both invoke '''webObsidian.sh''', so they use the script's ports: HTTP '''8080''' and stop port '''9597'''. Passing ''-Dembedded.tomcat.*'' on a ''java'' command line has no effect on the service — edit the values in '''webObsidian.sh''' before enabling it.

			== Running without an active login session ==

			This is a '''user''' service, so by default it runs only while that user has a login session and stops at logout. To keep Obsidian running after logout and start it at boot, enable lingering for the account:

			loginctl enable-linger <nowiki><username></nowiki>

			If you want Obsidian to run as a system service independent of any user account, write your own unit under ''/etc/systemd/system/'' using '''linux/obsidian-embedded@.service.in''' as a starting point.

			== Standalone admin installs ==

			The generated unit runs '''webObsidian.sh start scheduler'''. If you installed only the '''Obsidian Standalone Admin Embedded Tomcat JAR''' pack, change ''ExecStart'' in ''~/.config/systemd/user/obsidian-embedded@scheduler.service'' to use '''start adminOnly''' before enabling the service.

			== Removing the integration ==

			systemctl --user disable --now obsidian-embedded@scheduler.service
			rm ~/.config/systemd/user/obsidian-embedded@scheduler.service
			rm ~/.local/share/applications/obsidian-embedded.desktop
			systemctl --user daemon-reload

			The same details ship as '''linux/README-linux-integration.md''' in your install directory.

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

Craig at 20:52, 30 July 2026

2026-07-30T20:52:00Z

← Older revision		Revision as of 20:52, 30 July 2026
Line 226:		Line 226:

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

			On Linux you can also run Obsidian as a user-level systemd service, or launch it from a desktop entry, instead of calling the script by hand — see [[#Running_Obsidian_as_a_Linux_user_service\|Running Obsidian as a Linux user service]] below.

	If you are deploying '''obsidian.war''' to your own external servlet container instead, refer to your container's deployment documentation.		If you are deploying '''obsidian.war''' to your own external servlet container instead, refer to your container's deployment documentation.

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 =