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

116 lines
4.4 KiB
Markdown

# Desktop application configuration
The `desktop-apps` profile installs XnView MP, Zoom, Nextcloud Desktop, Notepad++,
HandBrake, GIMP, Krita, LibreOffice, Waterfox, and Shotcut. It also declares safe
configuration surfaces for MPC-HC and Ontime when those applications are
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. 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.
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.
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.