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

139 lines
5.8 KiB
Markdown

# 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.
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](https://github.com/clsid2/mpc-hc/blob/develop/src/mpc-hc/mplayerc.cpp).
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:
```powershell
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.
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:
```powershell
& '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`:
```text
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:
```text
# 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:
```powershell
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.