Set up the service manually as a system service

On Windows, the installation package sets up the service. Without the package—for a test computer, for example, or on Linux—set it up as follows. The same program runs as a console process, Windows service, or systemd service and reports start and stop to the respective service manager.

Under the Windows Service Control Manager, the service uses its program directory as the content root (appsettings*.json, a relative store path); under systemd, WorkingDirectory applies. The service account needs read access to the program and master key, and write access to the data folder with the administration store.

Configuration, master key, permissions of the data folder, and the firewall rule are set up by the setup-host command, the same one the installation package calls (see Commands on the server). Only copying the files and registering the service remain manual.

Which service account. The installation package uses the virtual account NT SERVICE\Wkl.Data.Gateway: it needs no password, and its rights apply only to this service. NT AUTHORITY\NetworkService works as well, but is shared by many services; whatever the data folder allows it, those services may then do too. A virtual account can be resolved only once the service is registered; that's why the service is created before setup-host.

Windows (PowerShell as an administrator)

1. Copy the published files to the program folder:

   $program = Join-Path $env:ProgramFiles 'Wkl\Data Gateway'
   New-Item -ItemType Directory -Force $program | Out-Null
   Copy-Item -Recurse .\publish\* $program

2. Register the service, without starting it yet:

   sc.exe create Wkl.Data.Gateway binPath= "`"$program\dbgwsvc.exe`"" start= auto obj= "NT SERVICE\Wkl.Data.Gateway"

3. Set up the configuration, data folder, and master key. Without --certificate, the service listens only on http://127.0.0.1:8434; add HTTPS afterwards as described in HTTPS and certificate:

   & "$program\dbgwsvc.exe" setup-host --program $program `
       --data (Join-Path $env:ProgramData 'Wkl.Data.Gateway') --service-account 'NT SERVICE\Wkl.Data.Gateway'

   Return value 0. The command writes appsettings.Production.json to the program folder, creates the data folder with permissions only for administrators, System, and the service account, and creates geheim\hauptschluessel.key. Back up this file outside the server.

4. Register the event source so that the service writes to the event log (Windows PowerShell 5.1): New-EventLog -LogName Application -Source Wkl.Data.Gateway.
5. Start the service: Start-Service Wkl.Data.Gateway.
6. Create the first administrator; see Create the first administrator.
7. Check: Invoke-RestMethod http://127.0.0.1:8434/health/live responds Healthy; Get-Service Wkl.Data.Gateway reports Running.

Linux

1. Create an account without sign-in (useradd --system --no-create-home wkl-gateway), copy the files of the Linux edition (linux-x64, delivered by the vendor as a separate archive; the installation package contains only the Windows edition) to /opt/wkl/gateway, and give the account write permission only on the data folder. Write the configuration there yourself to appsettings.Production.json: at least Kestrel:Endpoints and Gateway:Store with path and master key (see Configuration); setup-host doesn't set up Linux.

2. Create the unit file /etc/systemd/system/wkl-gateway.service:

   [Unit]
   Description=Wkl.Data.Gateway
   After=network-online.target
    
   [Service]
   Type=notify
   WorkingDirectory=/opt/wkl/gateway
   ExecStart=/opt/wkl/gateway/Wkl.Data.Gateway
   User=wkl-gateway
    
   [Install]
   WantedBy=multi-user.target

   Without the [Install] section, systemctl enable rejects the unit.

3. Start with systemctl enable --now wkl-gateway; the log is in the journal (journalctl -u wkl-gateway).

• A folder the service creates itself may be read only by the service account and the administrators; the administrators need access for the commands on the server.
• Started from the console, the service behaves the same way.
• Without a registered event source, the service keeps running, but writes nothing to the event log; see Troubleshooting.

• Installation package (reference) · Commands