Custom Maria Service Hoster Installer

This page describes how to create a custom installer for MariaServiceHoster, either from repository sources or by repackaging files from a supplied Maria service installer.

For configuration details, see the MariaServiceHoster README (repository access required).

Required package contents

Package a complete, matching release rather than selecting individual DLLs:

• MariaServiceHoster.exe and its managed dependencies, runtime files and native libraries.
• The Data directory and other supplied runtime resources.
• The complete wwwroot directory, including the monitor and Swagger pages.
• appSettings.json and the configuration sidecars required by the deployment.
• Any separate service payloads referenced by the configuration, including their manifests and detached signatures where applicable.

Preserve the supplied directory structure. Separate service payloads must be installed beneath the configured HostedExternalProcesses:RootPath; they are not necessarily located beside the host executable.

Configuration and Windows service registration

The installer must register the configuration path as the first command-line argument in the Windows service's executable command line.

For example, the registered command line could be:

"C:\Program Files\Customer\MariaServiceHoster\MariaServiceHoster.exe" "C:\ProgramData\Customer\MariaServiceHoster\appSettings.json"

Configure these as the executable and its arguments in your installer tool. Quote both paths separately. The host takes the configuration filename directly: do not prefix it with --config.

Use an absolute configuration path. If no argument is supplied, the host loads appSettings.json beside its executable.

Place the required sidecars beside the selected configuration file:

appSettings.json
appSettings.Proxy.json
appSettings.ServiceSettings.json
appSettings.ExternalProcesses.json

Matching *.Local.json files can provide customer-specific overrides. If the base file is renamed, rename its sidecars accordingly; for example, Customer.json uses Customer.Proxy.json.

Important: Copy the configuration files as a coherent set. An old configuration without front-door endpoints and proxy routes may start services successfully but will not expose the shared front door or /host/monitor/.

Give the Windows service account read/execute access to the installed payload, read access to configuration, and write access to the required data/log directories. Provision certificate access and manifest-signer trust for that account where required.

Building an installer from the repository

For internal teams with repository access:

1. Build/publish Src\Hosts\MariaServiceHoster\MariaServiceHoster.csproj using the repository's release process. Include the native libraries and resources staged by the repository copy scripts.
2. Publish/stage any separate service packages required by the deployment. The repository's publish_to_maria_hoster_external_services.ps1 scripts demonstrate this, including executable hash stamping and optional manifest signing.
3. Package the complete output and configuration set. Use Inst\MariaServiceHoster.ism as the reference for the existing installer layout and Windows service registration.
4. If using InstallShield, Build\Scripts\BuildInstaller.ps1 provides the repository's installer build wrapper.

Do not assume publishing the host alone produces every separately installed service package.

Building an installer from supplied binaries

For teams repackaging a supplied Maria service installer:

1. Extract the release payload, or collect it from a clean installation of that release.
2. Include both the application installation directory and any separately installed service payloads. Collect the configuration set as well; it may be installed under %ProgramData% rather than beside the executable.
3. Preserve the complete runtime/resource directory structure and package manifests/signatures. Do not mix files from different releases or modify signed manifests.
4. Apply the intended customer configuration and register the Windows service with the explicit configuration path shown above.

Use clean release files, not an operational installation containing customer data, logs, credentials or machine-specific overrides. Repackaging does not remove runtime prerequisites or certificate/trust provisioning requirements.

Installation verification

• Confirm the registered Windows service command line points to the intended executable and configuration.
• Start the service and check the logged Config, Proxy enabled and Host listeners values.
• Open /host/monitor/ on the configured HTTP/HTTPS front door and verify the expected services.
• Check remote access, firewall rules and HTTPS trust where applicable.

During upgrades, stop affected processes before replacing binaries and preserve customer configuration and persistent data.