config-central/docs/desktop-app-configs.md

7.4 KiB

Desktop application configuration

The desktop-apps profile installs XnView MP, Zoom, Nextcloud Desktop, Notepad++, HandBrake, GIMP, Krita, LibreOffice, Waterfox, Shotcut, and MPC-HC. Ontime configuration is also managed when Ontime is installed separately. Close an application before applying its config so it does not immediately overwrite the result.

The checked-in declarations start as safe no-ops or comment-only files. Populate only the values you want shared across every selected machine.

Run cc capture to collect the current machine's configuration without applying repository content. Captures are written beneath Documents\ConfigCentral\captures and split between repository-shaped configs/ files and raw review/ files that require curation. Nextcloud's full configuration is excluded; only keys already declared in its safe overlay are captured. Close applications first so their files reflect the latest saved preferences.

MPC-HC

MPC-HC normally stores preferences below HKCU\Software\MPC-HC\MPC-HC. Config Central applies only values listed in configs/mpc-hc/settings.json; it does not delete other values or registry keys. The standard x86 and x64 builds use this same settings key for the same Windows user: applying once configures both. This HKCU location is shared across registry views; do not add a speculative Wow6432Node or "MPC-HC x64" target. See MPC-HC's settings store and Windows registry sharing rules.

Apply attempts to create missing registry keys and writes each declared value independently. If some writes fail, the summary is a yellow warning listing only the keys that could not be written; other values continue to apply. If every write fails, the config fails. The existing running-player and backup checks still apply. Full Windows errors are saved alongside the registry backup in a *.write-results.json file. Partial deployments track the observed registry state, so a later update retries the missing values instead of claiming that all desired settings are current. Capture still explains how to initialize settings when no registry profile exists.

Close both mpc-hc.exe and mpc-hc64.exe before applying. The adapter refuses writes while either process is running, to prevent an open player from saving stale settings over the new values. If the two players still differ, check each one's settings-storage option and Windows account: separate INI files are not managed by this registry adapter.

This adapter supports registry mode only. MPC-HC also supports an INI file next to its executable (mpc-hc.ini or mpc-hc64.ini). Check the player's settings-storage option before capture or apply: an old registry key can remain even when the active player uses INI storage. A successful registry write does not prove the player reads that registry key. See MPC-HC's storage implementation.

Capture is deliberately filtered, not a complete player backup: monitor/device selection and other machine-specific or private values are excluded. Apply only updates declared values for the current Windows user. Close MPC-HC before capture or deployment, then reopen it afterward.

On the machine whose settings should be the baseline, close MPC-HC and run:

pwsh -File .\tools\Export-MpcHcSettings.ps1

The exporter omits history, favorites, recent files, URLs, and common path-like values by default. Review the generated JSON anyway before committing it. Remove any value that is machine-specific. -IncludePrivateValues exists for deliberate local export work, but its output should almost never be committed.

Ontime

The profile manages Ontime's supported CSS override at %APPDATA%\Ontime\user\styles\override.css. Edit configs/ontime/override.css to define the shared presentation. The event timer hides current/next event cards, uses the same enlarged font size for the countdown and bottom message, and flashes the background red when Blink is active. Text stays visible. Fullscreen messages are bottom-aligned, share the countdown font size, and use the same background blink effect. The upper-right clock is enlarged and shows hours/minutes without seconds. Blink uses a gradual three-second cycle; reduced-motion browsers show steady red instead. Slower flashing is not a guarantee of photosensitive safety. Keep bottom messages short to fit at countdown size. The background trigger uses CSS :has(), so use a current browser for the timer display.

The shared size is --cc-timer-size, the clock size is --cc-clock-size, and the flash color is --cc-blink-red at the top of the stylesheet. After deploying, reload the timer browser view.

Ontime stores projects, uploads, logs, crash data, its database, and volatile app-state.json beneath %APPDATA%\Ontime. Config Central leaves those files alone. In particular, app-state.json contains the active project, rundown, server port, and session health, so copying it between machines would be wrong.

XnView MP

The profile overlays keys from configs/xnviewmp/xnview.ini onto %APPDATA%\XnViewMP\xnview.ini. Unlisted sections and keys remain untouched, including the catalog and thumbnail databases.

Use Settings > Integration > Paths > Open Config Files Location in XnView MP to locate the active INI file. Copy only portable sections and keys into the repository overlay. Some XnView installations use an additional settings subdirectory or portable mode; override the xnviewmp-settings target in that machine's manifest when its displayed path differs.

Avoid sharing catalog paths, recent folders, database locations, or other values that name a local drive.

Nextcloud Desktop

Nextcloud's Windows configuration file is %APPDATA%\Nextcloud\nextcloud.cfg. The profile uses an INI overlay from configs/nextcloud/managed.ini, so account sections and other unlisted keys stay untouched.

Never commit the full nextcloud.cfg: it contains account and authentication material. Add only documented, non-secret preferences to managed.ini. Account setup should remain interactive. To prefill a first-run wizard without storing a password, Nextcloud supports commands such as:

& 'C:\Program Files\Nextcloud\nextcloud.exe' `
  --overrideserverurl 'https://cloud.example.com' `
  --overridelocaldir 'D:/Nextcloud'

The local folder is commonly machine-specific, so this command is not run by the shared profile.

Windows hosts file

Add entries to configs/windows/hosts.entries:

192.0.2.10 service.example.test
2001:db8::10 service-v6.example.test alias.example.test

Config Central validates every active line, requests elevation, backs up the hosts file, and owns only this marked section:

# BEGIN CONFIG CENTRAL: windows-hosts
...
# END CONFIG CENTRAL: windows-hosts

Lines outside that block are preserved. A comment-only declaration is a no-op.

Applying changes

Run cc plan first. Existing unmanaged values are reported as conflicts rather than overwritten. Once the repository version is correct, use:

cc apply -ForceConfigs

Forced file and hosts updates are backed up under %LOCALAPPDATA%\ConfigCentral\backups. Registry backups contain only the values managed by the declaration. Inspect and commit each source file separately so no history, credentials, tokens, or machine-specific paths enter Git.