Installation and updates

The Print Service has no installer. The program is delivered as a git repository that contains only the released build. Updates are a git checkout, driven by a script that stops the service gracefully first. Configuration, token, job journal and logs live in a separate data folder and survive every update.

Requirements

Folder layout

C:\kiwisoftware\VeloxPrint\
  app\          clone of the release repository, program only, updated by update.ps1
    bin\        kiwisoftware.VeloxFactory.PrintService.App.exe and its libraries
    update.ps1
    README.md
  data\         created by the app, never part of git
    config.json     configuration without token
    secrets.json    API token, encrypted
    state.db        job journal, outbox, statistics, log buffer, engine status (SQLite)
    logs\           rolling log files

Where the data folder is:

1. --config <path> sets it explicitly: all files of the instance live next to that configuration file.
2. If the program runs from a folder named app or below it, the data folder is data next to that app folder.
3. Otherwise it is %ProgramData%\kiwisoftware\VeloxPrint\.

The first start with administrator rights creates the data folder and sets these permissions. Setting up the scheduled task adds the service account.

First installation

1. Create the service account

The scheduled task runs under its own account. It must exist before the task is set up, the Print Service does not create it. PowerShell as administrator:

$pw = Read-Host -AsSecureString "Password"
New-LocalUser -Name "svc-veloxprint" -Password $pw -FullName "VeloxFactory Print Service" `
  -Description "Service account VeloxFactory Print Service" -PasswordNeverExpires -UserMayNotChangePassword

1. Do not add the account to the Administrators group, the standard Users group is enough.
2. Use -PasswordNeverExpires. An expired password stops the task until it is set up again.
3. For printers on a print server in a domain, use a domain account (DOMAIN\svc-veloxprint) instead. Only a domain account can authenticate at the print server.
4. Do not use SYSTEM. It accesses print servers with the computer account, shares often refuse that.

2. Clone the release

PowerShell as administrator:

New-Item -ItemType Directory C:\kiwisoftware\VeloxPrint
git clone https://git.fischernetz.xyz/bfischer/veloxfactory-printservice-release.git C:\kiwisoftware\VeloxPrint\app

3. Configure

1. Start C:\kiwisoftware\VeloxPrint\app\bin\kiwisoftware.VeloxFactory.PrintService.App.exe as administrator. The first elevated start creates data\ and restricts its permissions.
2. Settings → Connection: base URL of VeloxFactory and API token. Test connection checks reachability, token, channel authorization, WebSocket handshake and rate limit headers.
3. Settings → WebSocket (Reverb): host, port, scheme and app key of your Reverb server.
4. Settings → Receiving: the broadcast ids of this site.
5. Save. See the Configuration reference for every setting.

4. Set up the scheduled task

Settings → Operation → Set up scheduled task, enter the service account (.\svc-veloxprint for a local account) and its password. Alternatively on the command line (as administrator):

& "C:\kiwisoftware\VeloxPrint\app\bin\kiwisoftware.VeloxFactory.PrintService.App.exe" --install-task --user .\svc-veloxprint

The setup:

1. grants the account the right Log on as a batch job,
2. sets the permissions of the data folder and secrets.json for the account,
3. registers the Windows event log source VeloxFactory Print Service,
4. creates or updates the task with the settings below.

The window shows the task under Settings → Operation: state, account, last and next run, last result and the XML definition. It can start and remove the task there, too.

5. Verify

1. Printers: print a test page on every printer the site uses.
2. Start the task (Settings → Operation → Start or reboot). The window switches to monitor mode.
3. Create a print task in VeloxFactory for one of the broadcast ids and watch it on the Dashboard.

Updates and rollback

PowerShell as administrator:

# newest release
powershell -ExecutionPolicy Bypass -File C:\kiwisoftware\VeloxPrint\app\update.ps1

# a specific release, also the way back to an older one
powershell -ExecutionPolicy Bypass -File C:\kiwisoftware\VeloxPrint\app\update.ps1 -Version 2.0.1

1. Releases are git tags (v2.0.1). git -C C:\kiwisoftware\VeloxPrint\app log --oneline shows the source commit of every release.
2. New settings are added to config.json with their defaults on the next start.
3. Never change files inside app\. The script refuses to update a modified folder. Settings belong into data\.

Several instances on one machine

Each instance needs its own configuration file. Its name becomes the prefix of all files of the instance, so several instances can share one data folder:

data\config.json               default instance
data\lager-nord.json           second instance
data\lager-nord.secrets.json
data\lager-nord.state.db
data\logs\lager-nord\

$exe = "C:\kiwisoftware\VeloxPrint\app\bin\kiwisoftware.VeloxFactory.PrintService.App.exe"
& $exe --config C:\kiwisoftware\VeloxPrint\data\lager-nord.json                                   # window of this instance
& $exe --config C:\kiwisoftware\VeloxPrint\data\lager-nord.json --install-task --user .\svc-veloxprint

The task of that instance is called VeloxFactory Print Service (lager-nord). Give every instance its own broadcast ids.