Fossil SCM

fossil-scm / www / server / windows / service.md

Source Blame History 120 lines

f146e21…	drh	1	# Fossil as a Windows Service
f146e21…	drh	2
f146e21…	drh	3	If you need Fossil to start automatically on Windows, it is suggested to install
f146e21…	drh	4	Fossil as a Windows Service.
f146e21…	drh	5
f146e21…	drh	6	## Assumptions
f146e21…	drh	7
f146e21…	drh	8	1. You have Administrative access to a Windows 2012r2 or above server.
f146e21…	drh	9	2. You have PowerShell 5.1 or above installed.
f146e21…	drh	10
f146e21…	drh	11	## Place Fossil on Server
f146e21…	drh	12
f146e21…	drh	13	However you obtained your copy of Fossil, it is recommended that you follow
ad47a44…	wyoung	14	Windows conventions and place it within `\Program Files\FossilSCM`, the
ad47a44…	wyoung	15	proper location for the official 64-bit binary.
6a0ec82…	ckennedy	16	This way Fossil is at an expected location and you will have minimal issues with
f146e21…	drh	17	Windows interfering in your ability to run Fossil as a service. You will need
6a0ec82…	ckennedy	18	Administrative rights to place fossil at the recommended location. If you will
6a0ec82…	ckennedy	19	only be running Fossil as a service, you do not need to add this location to the
6a0ec82…	ckennedy	20	path, though you may do so if you wish.
f146e21…	drh	21
6a0ec82…	ckennedy	22	## Installing Fossil as a Service
f146e21…	drh	23
f146e21…	drh	24	Luckily the hard work to use Fossil as a Windows Service has been done by the
f146e21…	drh	25	Fossil team. We simply have to install it with the proper command line options.
cb13b61…	ckennedy	26	Fossil on Windows has a command `fossil winsrv` to allow installing Fossil as a
6a0ec82…	ckennedy	27	service on Windows. This command is only documented on the windows executable
6a0ec82…	ckennedy	28	of Fossil. You must also run the command as administrator for it to be
6a0ec82…	ckennedy	29	successful.
6a0ec82…	ckennedy	30
6a0ec82…	ckennedy	31	### Fossil winsrv Example
6a0ec82…	ckennedy	32
6a0ec82…	ckennedy	33	The simplest form of the command is:
6a0ec82…	ckennedy	34
6a0ec82…	ckennedy	35	```
6a0ec82…	ckennedy	36	fossil winsrv create --repository D:/Path/to/Repo.fossil
6a0ec82…	ckennedy	37	```
6a0ec82…	ckennedy	38
6a0ec82…	ckennedy	39	This will create a windows service named 'Fossil-DSCM' running under the local
6a0ec82…	ckennedy	40	system account and accessible on port 8080 by default. `fossil winsrv` can also
6a0ec82…	ckennedy	41	start, stop, and delete the service. For all available options, please execute
6a0ec82…	ckennedy	42	`fossil help winsrv` on a windows install of Fossil.
6a0ec82…	ckennedy	43
a3be0b8…	drh	44	If you wish to serve a directory of repositories, the `fossil winsrv` command
6a0ec82…	ckennedy	45	requires a slightly different set of options vs. `fossil server`:
6a0ec82…	ckennedy	46
6a0ec82…	ckennedy	47	```
6a0ec82…	ckennedy	48	fossil winsrv create --repository D:/Path/to/Repos --repolist
6a0ec82…	ckennedy	49	```
6a0ec82…	ckennedy	50
6b43913…	larrybr	51	### Choice of Directory Considerations
6b43913…	larrybr	52
6b43913…	larrybr	53	When the Fossil server will be used at times that files may be locked
6b43913…	larrybr	54	during virus scanning, it is prudent to arrange that its directory used
6b43913…	larrybr	55	for temporary files is exempted from such scanning. Ordinarily, this
6b43913…	larrybr	56	will be a subdirectory named "fossil" in the temporary directory given
4e688dc…	danield	57	by the Windows GetTempPath(...) API, [namely](https://learn.microsoft.com/en-us/windows/win32/api/fileapi/nf-fileapi-gettemppathw#remarks)
4e688dc…	danield	58	the value of the first existing environment variable from `%TMP%`, `%TEMP%`,
4e688dc…	danield	59	`%USERPROFILE%`, and `%SystemRoot%`; you can look for their actual values in
5df726a…	drh	60	your system by accessing the `/test-env` webpage.
1f184d0…	danield	61	Excluding this subdirectory will avoid certain rare failures where the
1f184d0…	danield	62	fossil.exe process is unable to use the directory normally during a scan.
93cee1f…	wyoung	63
93cee1f…	wyoung	64	### <a id='PowerShell'></a>Advanced service installation using PowerShell
6a0ec82…	ckennedy	65
6a0ec82…	ckennedy	66	As great as `fossil winsrv` is, it does not have one to one reflection of all of
c64f28d…	drh	67	the `fossil server` [options](/help/server). When you need to use some of
6a0ec82…	ckennedy	68	the more advanced options, such as `--https`, `--skin`, or `--extroot`, you will
6a0ec82…	ckennedy	69	need to use PowerShell to configure and install the Windows service.
6a0ec82…	ckennedy	70
6a0ec82…	ckennedy	71	PowerShell provides the [New-Service](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.management/new-service?view=powershell-5.1)
6a0ec82…	ckennedy	72	command, which we can use to install and configure Fossil as a service. The
6a0ec82…	ckennedy	73	below should all be entered as a single line in an Administrative PowerShell
6a0ec82…	ckennedy	74	console.
f146e21…	drh	75
f146e21…	drh	76	```PowerShell
6a0ec82…	ckennedy	77	New-Service -Name fossil -DisplayName fossil -BinaryPathName '"C:\Program Files\FossilSCM\fossil.exe" server --port 8080 --repolist "D:/Path/to/Repos"' -StartupType Automatic
f146e21…	drh	78	```
f146e21…	drh	79
cb13b61…	ckennedy	80	Please note the use of forward slashes in the repolist path passed to Fossil.
cb13b61…	ckennedy	81	Windows will accept either back slashes or forward slashes in path names, but
cb13b61…	ckennedy	82	Fossil has a preference for forward slashes. The use of `--repolist` will make
cb13b61…	ckennedy	83	this a multiple repository server. If you want to serve only a single
cb13b61…	ckennedy	84	repository, then leave off the `--repolist` parameter and provide the full path
cb13b61…	ckennedy	85	to the proper repository file. Other options are listed in the
c64f28d…	drh	86	[fossil server](/help/server) documentation.
f146e21…	drh	87
f146e21…	drh	88	The service will be installed by default to use the Local Service account.
f146e21…	drh	89	Since Fossil only needs access to local files, this is fine and causes no
f146e21…	drh	90	issues. The service will not be running once installed. You will need to start
f146e21…	drh	91	it to proceed (the `-StartupType Automatic` parameter to `New-Service` will
f146e21…	drh	92	result in the service auto-starting on boot). This can be done by entering
f146e21…	drh	93
f146e21…	drh	94	```PowerShell
f146e21…	drh	95	Start-Service -Name fossil
f146e21…	drh	96	```
f146e21…	drh	97
f146e21…	drh	98	in the PowerShell console.
f146e21…	drh	99
f146e21…	drh	100	Congratulations, you now have a base http accessible Fossil server running on
f146e21…	drh	101	Windows.
366fda0…	danield	102
366fda0…	danield	103	### Removing the Windows Service
366fda0…	danield	104
366fda0…	danield	105	If you want to remove the Fossil service, execute the following from an
366fda0…	danield	106	Administrative PowerShell or Command Prompt console:
366fda0…	danield	107
366fda0…	danield	108	```
366fda0…	danield	109	sc.exe delete fossil
366fda0…	danield	110	```
366fda0…	danield	111
366fda0…	danield	112	If you have Powershell version 6.0 or later, you can use:
366fda0…	danield	113
366fda0…	danield	114	```PowerShell
366fda0…	danield	115	Remove-Service -Name fossil
366fda0…	danield	116	```
366fda0…	danield	117
366fda0…	danield	118	with the same effect.
f146e21…	drh	119
f146e21…	drh	120	[Return to the top-level Fossil server article.](../)

Fossil SCM

Keyboard Shortcuts