# Installation

# Requirements

Windows — the provisioning service runs as a Windows service
.NET Framework 4.8 — must be installed on the host machine
Full-control NTFS permissions — the account running the service must have full control on the installation directory
Disk space — approximately 80 MB for the installed service itself, excluding growth of the monitor directory, logs, and any migration data
Hardware — minimum 2 CPU cores and 8 GB RAM. On Azure, a Standard_B2s v2 VM is a reasonable baseline size. For migrations larger than 100 GB, use a separate, dedicated server for the migration tool rather than running it alongside the production provisioning service instance

# Supported Windows Server versions

Version	Support status
Windows Server 2012 / 2012 R2	Unsupported — Microsoft extended support ended October 10, 2023. Do not deploy on these.
Windows Server 2016	Extended support only — ends January 12, 2027
Windows Server 2019	Extended support only — ends January 9, 2029
Windows Server 2022	Currently supported — extended support ends October 14, 2031

Prefer Windows Server 2019 or later for new deployments. Support status follows Microsoft's own lifecycle policy for each OS version, independent of this service.

# Choosing the right package

Two builds are published per release:

Package	SharePoint target	Use when
`SiteProvisioning_ReleaseOnline_<version>_public.zip`	SharePoint Online	Customer is on Microsoft 365
`SiteProvisioning_Release2016_<version>_public.zip`	SharePoint 2016 (on-premises)	Customer is on SharePoint 2016

Customer-specific plugins are distributed separately in a _private.zip alongside the public zip.

# Installation steps

Download the appropriate zip file for the target SharePoint version.
Extract the zip to the installation directory (e.g., C:\Epona\SiteProvisioning). Full-control NTFS permissions are required on this folder for the service account.

The package includes the following pre-created folders: _Certificates, Config, Config_Disabled, Migrate_Data, Html, Scripts. These are empty on a fresh install — populate them as needed for your deployment.
Unblock the extracted files. Windows marks files downloaded from the internet as blocked, which prevents them from loading. Run the included script:
```
.\_unblock.ps1
```
Or run this command from the installation directory:
```
Get-ChildItem -Recurse | Unblock-File
```
Start the Configurator (Epona.Configurator.exe) and configure the service. See Configuration for the available settings. Run the Configurator as the same Windows account that will run the service — credentials are encrypted using that account and cannot be decrypted by a different one. See Secrets and encryption for details.
Register and start the Epona Provisioning Service. See Running the service below.

# Running the service

Epona.ProvisioningService.exe can run as a Windows service or interactively as a console application.

# As a console application

Run Epona.ProvisioningService.exe without arguments. Useful for initial setup and troubleshooting.

# As a Windows service

Register the service using the install command. Run from an elevated command prompt in the installation directory. Use the same account you used in the Configurator — see Secrets and encryption.

Epona.ProvisioningService.exe install -username:DOMAIN\svcaccount -password:<password>

Parameter values are supplied using a colon: -option:value. Options without a value (switches) use --switch.

Common options:

Option	Description
`-username`	Service account username (e.g., `DOMAIN\svcaccount`)
`-password`	Password for the service account
`-servicename`	Custom Windows service name (useful for multiple instances)
`-displayname`	Display name shown in the Services console
`-description`	Service description
`-instance`	Instance identifier for running multiple service instances side by side
`--autostart`	Start automatically at boot (default)
`--delayed`	Automatic start with a delay after boot
`--manual`	Manual start only
`--disabled`	Service is disabled
`--localsystem`	Run as Local System account
`--localservice`	Run as Local Service account
`--networkservice`	Run as Network Service account
`--sudo`	Request UAC elevation during installation

# Examples

Standard install with a delayed autostart:

Epona.ProvisioningService.exe install -username:DOMAIN\svcaccount -password:<password> --delayed

Install a second instance alongside an existing one (each instance must live in its own installation directory):

Epona.ProvisioningService.exe install -username:DOMAIN\svcaccount -password:<password> -instance:ClientB -displayname:"Epona Provisioning – ClientB"

The -instance value is appended to the internal service name (e.g., EponaProvisioningService$ClientB), so both instances can coexist in the Windows service registry. Pass the same -instance value when managing that instance:

Epona.ProvisioningService.exe start -instance:ClientB
Epona.ProvisioningService.exe stop -instance:ClientB
Epona.ProvisioningService.exe uninstall -instance:ClientB

After installation, manage the default (single) instance with:

Epona.ProvisioningService.exe start
Epona.ProvisioningService.exe stop
Epona.ProvisioningService.exe uninstall

# As an Azure WebJob

Epona.ProvisioningService.exe can also run as a continuous Azure WebJob inside an Azure App Service, as an alternative to an on-premises/IaaS Windows Service — the same executable runs as a console application under the App Service's WebJob host.

Since an App Service instance does not guarantee persistent local disk across restarts or scale-out, configuration and job state must be stored externally instead of on local disk:

Install the AzureStorage plugin (Plugins/AzureStorage/) using the standard plugin installation steps.
Set the AzureStorageConnectionString application setting (in Epona.ProvisioningService.exe.config, alongside other app-level settings) to an Azure Storage account connection string. A file share named dmsforlegalsiteprovisioning is created automatically in that account on first use, and configuration files and job state are read from and written to it instead of local disk.
Set the service's NLog configuration to write to the Trace target instead of the file-based targets, so log output appears in the WebJob's log stream in the Azure Portal. The shipped Epona.ProvisioningService.exe.nlog includes a commented-out rule for this — enable it (and disable the file-based logging rules) when deploying as a WebJob.

# Installing plugins

Plugins are optional integration DLLs. Each plugin is distributed in a Plugins/<PluginName>/ subfolder inside the zip.

To install a plugin:

Copy all files from Plugins/<PluginName>/ to the service root directory.
Restart the service (or configurator).
The service auto-discovers the plugin — no manual registration needed.
If the plugin has configuration properties, they appear in the Configurator under the relevant SharepointCfg.

See Plugins for the list of available plugins and their configuration.

# Updates

To update an existing installation:

Download the new zip file for the correct SharePoint target.
Stop the Epona Provisioning Service (and close the Configurator if running).
Extract the zip, overwriting all existing files in the installation directory.
Update installed plugins by copying the updated files from Plugins/<PluginName>/ to the service root. Repeat for each plugin in use.
Unblock the extracted files:
```
Get-ChildItem -Recurse | Unblock-File
```
Start the Configurator. It automatically extends existing configuration files with any new optional settings introduced in the new version. Review the new settings before starting the service.
Restart the Epona Provisioning Service.

Configuration — configure the service after installation
Plugins — available integration plugins
Version Numbering — what an installed version number means

← API Permissions (Registered Application) Version Numbering →