Document desktop application configuration
This commit is contained in:
parent
32549e0fe8
commit
0ba08e53ec
14
README.md
14
README.md
|
|
@ -89,6 +89,11 @@ Put source files below `configs/`. Config targets accept `%APPDATA%`,
|
|||
The complete schema, precedence rules, package policies, and exit codes are in
|
||||
[the manifest contract](docs/manifest-contract.md).
|
||||
|
||||
MPC-HC, Ontime, XnView MP, Nextcloud, and Windows hosts configuration have
|
||||
application-specific safety rules. See the
|
||||
[desktop application configuration guide](docs/desktop-app-configs.md) before
|
||||
populating those declarations.
|
||||
|
||||
## Daily commands
|
||||
|
||||
```powershell
|
||||
|
|
@ -120,10 +125,11 @@ an existing file it has never managed, or a locally deleted managed file is a
|
|||
conflict. Normal apply leaves the destination alone. `-ForceConfigs` makes a
|
||||
timestamped backup and then deploys the repository version.
|
||||
|
||||
`cc restore -Config NAME` restores the newest backup and first backs up the file
|
||||
being replaced. Removing a config from a manifest stops managing it; it does not
|
||||
delete the destination. Removing a package stops managing it; it does not
|
||||
uninstall software.
|
||||
`cc restore -Config NAME` restores the newest whole-file or INI backup and first
|
||||
backs up the file being replaced. Registry and hosts backups require deliberate
|
||||
manual restoration from an administrator shell. Removing a config from a
|
||||
manifest stops managing it; it does not delete the destination. Removing a
|
||||
package stops managing it; it does not uninstall software.
|
||||
|
||||
User state is stored under `%LOCALAPPDATA%\ConfigCentral`:
|
||||
|
||||
|
|
|
|||
8
TASKS.md
8
TASKS.md
|
|
@ -104,8 +104,8 @@ open until it is run on disposable machines with the required account setups.
|
|||
|
||||
- [x] Add WinGet packages for MPC-HC, Ontime, XnView MP, and Nextcloud Desktop.
|
||||
- [x] Add a safe registry-value adapter for MPC-HC settings.
|
||||
- [ ] Manage Ontime user settings without treating projects, uploads, or logs as config.
|
||||
- [ ] Manage XnView MP preferences without committing its catalog or thumbnails.
|
||||
- [ ] Add safe Nextcloud preconfiguration without committing account credentials.
|
||||
- [x] Manage Ontime user settings without treating projects, uploads, or logs as config.
|
||||
- [x] Manage XnView MP preferences without committing its catalog or thumbnails.
|
||||
- [x] Add safe Nextcloud preconfiguration without committing account credentials.
|
||||
- [x] Manage a marked block in the Windows hosts file through the elevated worker.
|
||||
- [ ] Document how to capture and customize the application-specific values.
|
||||
- [x] Document how to capture and customize the application-specific values.
|
||||
|
|
|
|||
|
|
@ -0,0 +1,106 @@
|
|||
# Desktop application configuration
|
||||
|
||||
The `desktop-apps` profile installs MPC-HC, Ontime, XnView MP, and Nextcloud
|
||||
Desktop and declares their safe configuration surfaces. 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.
|
||||
|
||||
## 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.
|
||||
|
|
@ -25,13 +25,19 @@ An unavailable requested version, unsupported installer scope, ambiguous
|
|||
inventory, or unknown installed version becomes a failed package operation with
|
||||
the WinGet diagnostics preserved. Configs requiring that package are skipped.
|
||||
|
||||
Config mode is currently `copy`. Sources are repository-relative files and must
|
||||
remain below `configs/` after canonicalization. Targets may be absolute Windows
|
||||
paths and may use `%APPDATA%`, `%LOCALAPPDATA%`, `%USERPROFILE%`, or
|
||||
`%PROGRAMDATA%`. Expansion uses the original desktop user's captured paths.
|
||||
Config modes are `copy`, `ini-overlay`, `registry`, and `hosts-block`. Sources
|
||||
are repository-relative files and must remain below `configs/` after
|
||||
canonicalization. File targets may be absolute Windows paths and may use
|
||||
`%APPDATA%`, `%LOCALAPPDATA%`, `%USERPROFILE%`, `%PROGRAMDATA%`, or
|
||||
`%SYSTEMROOT%`. Expansion uses the original desktop user's captured paths.
|
||||
Unknown variables, relative targets, colliding destinations, and sources escaping
|
||||
the repository are errors. Target comparisons are case-insensitive.
|
||||
|
||||
An INI overlay owns only the sections and keys declared in its source. Registry
|
||||
mode accepts typed JSON values and is constrained to the MPC-HC HKCU subtree.
|
||||
Hosts mode validates entries and owns one named marker block in the Windows hosts
|
||||
file; changes use the elevated worker. Empty adapter declarations are no-ops.
|
||||
|
||||
The commands are:
|
||||
|
||||
```text
|
||||
|
|
|
|||
|
|
@ -0,0 +1,41 @@
|
|||
[CmdletBinding()]
|
||||
param(
|
||||
[string]$OutputPath = (Join-Path $PSScriptRoot '..\configs\mpc-hc\settings.json'),
|
||||
[switch]$IncludePrivateValues
|
||||
)
|
||||
|
||||
Set-StrictMode -Version Latest
|
||||
$ErrorActionPreference = 'Stop'
|
||||
|
||||
$rootPath = 'HKCU:\Software\MPC-HC\MPC-HC'
|
||||
if (-not (Test-Path -LiteralPath $rootPath)) { throw "MPC-HC registry settings were not found at '$rootPath'. Start MPC-HC and save its settings first." }
|
||||
|
||||
$root = Get-Item -LiteralPath $rootPath
|
||||
$excludedSubkeys = '(?i)(^|\\)(MediaHistory|Recent File List|Favorites)(\\|$)'
|
||||
$excludedValues = '(?i)(path|directory|folder|filename|lastopen|lastused|recent|url)'
|
||||
$values = [Collections.Generic.List[object]]::new()
|
||||
|
||||
foreach ($key in @($root) + @(Get-ChildItem -LiteralPath $rootPath -Recurse)) {
|
||||
$relativePath = $key.Name.Substring($root.Name.Length).TrimStart('\')
|
||||
if (-not $IncludePrivateValues -and $relativePath -match $excludedSubkeys) { continue }
|
||||
foreach ($name in $key.GetValueNames()) {
|
||||
if ([string]::IsNullOrWhiteSpace($name)) { continue }
|
||||
if (-not $IncludePrivateValues -and $name -match $excludedValues) { continue }
|
||||
$kind = [string]$key.GetValueKind($name)
|
||||
if ($kind -notin @('String', 'ExpandString', 'DWord', 'QWord', 'MultiString', 'Binary')) { continue }
|
||||
$raw = $key.GetValue($name, $null, [Microsoft.Win32.RegistryValueOptions]::DoNotExpandEnvironmentNames)
|
||||
$value = switch ($kind) {
|
||||
'Binary' { @([byte[]]$raw) }
|
||||
'MultiString' { @([string[]]$raw) }
|
||||
default { $raw }
|
||||
}
|
||||
$values.Add([ordered]@{ path = $relativePath; name = $name; type = $kind; value = $value })
|
||||
}
|
||||
}
|
||||
|
||||
$document = [ordered]@{ schemaVersion = 1; values = @($values | Sort-Object path, name) }
|
||||
$fullOutputPath = [IO.Path]::GetFullPath($OutputPath)
|
||||
[void](New-Item -ItemType Directory -Path (Split-Path -Parent $fullOutputPath) -Force)
|
||||
$document | ConvertTo-Json -Depth 16 | Set-Content -LiteralPath $fullOutputPath -Encoding utf8NoBOM
|
||||
Write-Host "Exported $($values.Count) MPC-HC values to '$fullOutputPath'."
|
||||
Write-Warning 'Review the file for machine-specific paths or private history before committing it.'
|
||||
Loading…
Reference in New Issue