Simplify setup and config update documentation
Config Central CI Config Central passed all CI integrity checks.
Beffroi/config-central/pipeline/head This commit looks good
Details
Config Central CI Config Central passed all CI integrity checks.
Beffroi/config-central/pipeline/head This commit looks good
Details
This commit is contained in:
parent
fde35a661c
commit
40039a4171
276
README.md
276
README.md
|
|
@ -1,256 +1,64 @@
|
|||
# Config Central
|
||||
|
||||
Config Central is a small PowerShell CLI for keeping several Windows desktops on
|
||||
the same declared software and configuration baseline. Each machine pulls this
|
||||
Git repository, resolves its profiles, installs or updates declared packages with
|
||||
WinGet, and copies managed config files with drift detection and backups.
|
||||
Install the software and settings for a Windows desktop, then keep its configs
|
||||
up to date with one command. No management server or background agent is needed.
|
||||
|
||||
There is no central server or resident agent. The normal workflow is:
|
||||
## 1. Set up the computer once
|
||||
|
||||
```text
|
||||
Git fetch -> immutable commit snapshot -> plan -> WinGet -> config copies -> state
|
||||
```
|
||||
|
||||
## Requirements
|
||||
|
||||
- Windows 10 version 1809 or newer, Windows 11, or Windows Server 2025
|
||||
- Windows PowerShell 5.1 for initial bootstrap
|
||||
- PowerShell 7, Git, and WinGet after bootstrap
|
||||
- An interactive desktop account; administrator credentials when a machine-scope
|
||||
installer needs them
|
||||
|
||||
The bootstrap checks and installs its prerequisites. WinGet must be supported by
|
||||
the Windows edition and able to reach its configured sources.
|
||||
|
||||
## Onboard a machine
|
||||
|
||||
Run the one-stop installer in Windows PowerShell:
|
||||
Open **Windows PowerShell** as your normal desktop user and paste:
|
||||
|
||||
```powershell
|
||||
irm 'https://proxy.dandaedre.com/gitea/Beffroi/config-central/raw/branch/main/install.ps1' | iex
|
||||
```
|
||||
|
||||
On a new computer, the installer retrieves the machine manifests and selects the
|
||||
only one, matches the Windows computer name, or displays a numbered prompt. On a
|
||||
configured computer it reuses the saved machine automatically. It then stages
|
||||
`bootstrap.ps1` as a temporary file, establishes every prerequisite, clones or
|
||||
updates the repository, and applies the machine manifest. The temporary file is
|
||||
removed afterward.
|
||||
Setup selects the matching machine profile or asks you to choose one. It installs
|
||||
Git, PowerShell 7, and the declared software, then applies the configs. Approve
|
||||
administrator prompts when needed. Rerun this command to repair setup.
|
||||
|
||||
For unattended installation, select the machine in the same command:
|
||||
Requires Windows 10 1809 or newer, Windows 11, or Windows Server 2025, with
|
||||
internet access and support for WinGet.
|
||||
|
||||
## 2. Update configs whenever needed
|
||||
|
||||
Close the applications whose settings you are updating, then paste into
|
||||
**PowerShell**:
|
||||
|
||||
```powershell
|
||||
$env:CONFIG_CENTRAL_MACHINE = 'example-desktop'; irm 'https://proxy.dandaedre.com/gitea/Beffroi/config-central/raw/branch/main/install.ps1' | iex
|
||||
irm 'https://proxy.dandaedre.com/gitea/Beffroi/config-central/raw/branch/main/update-configs.ps1' | iex
|
||||
```
|
||||
|
||||
The installer is safe to rerun for repair or setup updates. Use `cc sync` for
|
||||
normal repository, package, and configuration updates after onboarding.
|
||||
This downloads the latest configs and updater code from your saved repository
|
||||
branch and applies them to your saved machine profile. No menu, manual Git pull,
|
||||
or software installation. Temporary downloads are removed afterward.
|
||||
|
||||
Download `bootstrap.ps1` from a trusted revision of this repository, inspect it,
|
||||
then run it from Windows PowerShell:
|
||||
Unchanged configs are skipped and replacements are backed up. Local edits are
|
||||
reported as conflicts instead of being silently lost; see
|
||||
[replacing local edits](docs/advanced_commands.md#web-config-updater).
|
||||
Windows may request administrator approval for settings such as the hosts file.
|
||||
|
||||
## Collect settings from a computer
|
||||
|
||||
After changing settings in an application, close it and run in a new terminal:
|
||||
|
||||
```powershell
|
||||
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\bootstrap.ps1 `
|
||||
-Repository 'https://your-server/you/config-central.git' `
|
||||
-Branch main `
|
||||
-Machine example-desktop
|
||||
cc capture
|
||||
```
|
||||
|
||||
The underlying bootstrap repairs WinGet if necessary, installs Git and
|
||||
PowerShell 7, clones the configured branch under
|
||||
`%LOCALAPPDATA%\ConfigCentral\repository`, saves the machine selection, adds `cc`
|
||||
to the user PATH, and performs the first apply. It is safe to rerun after a
|
||||
failed prerequisite installation. Use `-SkipApply` when you only want to
|
||||
establish the checkout and launcher.
|
||||
The files are saved under
|
||||
`Documents\ConfigCentral\captures\MACHINE-yyyyMMdd-HHmmss`.
|
||||
Review them, copy the desired settings into this repository, then commit and
|
||||
push. Run the update command on the other computers to receive those changes.
|
||||
Capture does not upload anything automatically; some exports need curation.
|
||||
See the [application config guide](docs/desktop-app-configs.md) for details.
|
||||
|
||||
A UAC prompt appears only when administrator work is pending and the current
|
||||
terminal is not already elevated. The prompt covers WinGet repair or the batch
|
||||
of machine-scope packages and machine configuration changes.
|
||||
## Troubleshooting and advanced use
|
||||
|
||||
Open a new terminal after bootstrap so the updated user PATH is visible, then
|
||||
check the installation:
|
||||
Run `cc doctor` in a new terminal to check setup, or `cc status` to inspect the
|
||||
last run and config drift.
|
||||
|
||||
```powershell
|
||||
cc doctor
|
||||
cc plan
|
||||
cc apply
|
||||
```
|
||||
|
||||
## Define profiles and machines
|
||||
|
||||
Profiles live in `profiles/`. Machines live in `machines/` and list profiles in
|
||||
precedence order. Later profiles replace earlier entries; machine entries replace
|
||||
all profile entries. A package is identified by `source/id`, and a config by
|
||||
`name`. Set `enabled` to `false` in a later layer to remove an inherited item.
|
||||
|
||||
```json
|
||||
{
|
||||
"schemaVersion": 1,
|
||||
"name": "workstation",
|
||||
"profiles": ["base", "development"],
|
||||
"packages": [
|
||||
{
|
||||
"id": "Microsoft.VisualStudioCode",
|
||||
"source": "winget",
|
||||
"scope": "machine",
|
||||
"update": "latest"
|
||||
}
|
||||
],
|
||||
"configs": []
|
||||
}
|
||||
```
|
||||
|
||||
Put source files below `configs/`. Config targets accept `%APPDATA%`,
|
||||
`%LOCALAPPDATA%`, `%USERPROFILE%`, and `%PROGRAMDATA%`:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "helix-config",
|
||||
"source": "configs/helix/config.toml",
|
||||
"target": "%APPDATA%/helix/config.toml",
|
||||
"mode": "copy",
|
||||
"requiresPackage": "Helix.Helix"
|
||||
}
|
||||
```
|
||||
|
||||
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
|
||||
cc plan # show intended work; change nothing
|
||||
cc apply # apply the current checkout
|
||||
cc sync # fetch and apply an immutable remote snapshot
|
||||
cc status # show drift and the last run
|
||||
cc sync -ConfigsOnly # fetch and deploy configs; do not call WinGet
|
||||
cc apply -ForceConfigs # back up local edits, then replace them
|
||||
cc configs # show repository and live computer config paths
|
||||
cc configs -Config helix-config # show paths for one managed config
|
||||
cc capture # collect live configs under Documents for upload
|
||||
cc capture -Config ontime-style # capture one config
|
||||
cc restore -Config helix-config # restore the newest backup
|
||||
cc doctor # inspect prerequisites and sources
|
||||
cc menu # optional numbered menu
|
||||
```
|
||||
|
||||
For a two-command temporary debugging shell, or for permanent key-based access
|
||||
from CachyOS, follow the
|
||||
[advanced remote access guide](docs/advanced-remote-access.md#quick-temporary-access).
|
||||
The temporary helper prints an SSH command that opens PowerShell directly;
|
||||
ordinary Windows SSH sessions open `cmd.exe`, which does not recognize `irm`.
|
||||
|
||||
`sync` refuses to run while the checkout has uncommitted or untracked files. It
|
||||
does not reset the checkout. Commit your edits first, or remove files you did not
|
||||
intend to keep.
|
||||
|
||||
Package installs run sequentially. Machine-scope packages are sent together to a
|
||||
constrained elevated worker, so one UAC approval covers the batch. User config
|
||||
paths come from the original desktop session even when different administrator
|
||||
credentials approve the package work. A required reboot is reported with exit
|
||||
code `6`; Config Central never reboots the machine itself.
|
||||
|
||||
## Find and update configuration sources
|
||||
|
||||
Run `cc configs` on a managed computer to see the repository source and resolved
|
||||
live destination for every config. `Present` means the computer destination
|
||||
exists; `Missing` means the application has not created it yet. Use `-Config
|
||||
NAME` to select one entry, or `-Json` for structured output:
|
||||
|
||||
```powershell
|
||||
cc configs
|
||||
cc configs -Config ontime-style
|
||||
cc configs -Config xnviewmp-settings -Json
|
||||
```
|
||||
|
||||
For a `copy` config, close the application, copy the live computer file to the
|
||||
reported repository path, and review `git diff` before committing it. For an
|
||||
`ini-overlay`, copy only the portable keys you intend to manage; do not replace
|
||||
the overlay with the entire application file. Use
|
||||
`tools\Export-MpcHcSettings.ps1` for the MPC-HC registry declaration. Never copy
|
||||
the complete Nextcloud config because it can contain account and authentication
|
||||
data.
|
||||
|
||||
`cc capture` automates the collection side without changing live files. By
|
||||
default it creates
|
||||
`Documents\ConfigCentral\captures\MACHINE-yyyyMMdd-HHmmss`. Whole-file configs
|
||||
retain their `configs/` repository paths. Raw XnView, hosts, and filtered MPC-HC
|
||||
exports are placed under `review/` for curation. Nextcloud capture reads only
|
||||
keys already allowlisted in `managed.ini`; its account sections and complete
|
||||
config are always excluded. Use `-OutputPath PATH` to select an exact empty
|
||||
destination.
|
||||
|
||||
From CachyOS, retrieve a completed capture for review with:
|
||||
|
||||
```bash
|
||||
scp -r USER@WINDOWS-PC:'Documents/ConfigCentral/captures/MACHINE-yyyyMMdd-HHmmss' ./
|
||||
```
|
||||
|
||||
## Config conflicts and recovery
|
||||
|
||||
Config Central stores the hash it last deployed. A different destination hash,
|
||||
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 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`:
|
||||
|
||||
```text
|
||||
settings.json repository, branch, machine, and original user paths
|
||||
state.json deployed hashes, last run, and applied revision
|
||||
logs/ per-run package and config results
|
||||
backups/ timestamped config backups grouped by config name
|
||||
snapshots/ immutable Git commit snapshots used by sync
|
||||
```
|
||||
|
||||
## Optional logon sync
|
||||
|
||||
```powershell
|
||||
cc schedule
|
||||
cc unschedule
|
||||
```
|
||||
|
||||
The scheduled task runs in the interactive user's limited context and always
|
||||
uses `sync -ConfigsOnly`. Package installation remains manual because a logon
|
||||
task must not stall on UAC or an installer prompt.
|
||||
|
||||
## Validation
|
||||
|
||||
On a Windows development machine with Pester 5:
|
||||
|
||||
```powershell
|
||||
Invoke-Pester -Path .\tests
|
||||
```
|
||||
|
||||
Real bootstrap, WinGet, UAC, and separate-admin-account tests require a disposable
|
||||
Windows machine. Opt in to the integration suite there with
|
||||
`CONFIG_CENTRAL_INTEGRATION=1`. The Jenkins pipeline follows the project's
|
||||
FreeBSD worker style and runs dependency-free PowerShell structure, JSON contract,
|
||||
and repository hygiene checks; it does not pretend to execute Windows behavior.
|
||||
|
||||
## Current limitations
|
||||
|
||||
- Config deployment supports whole-file copies only. It does not merge arbitrary
|
||||
application formats.
|
||||
- `latest` packages are offered to WinGet during apply. WinGet decides whether an
|
||||
upgrade exists, so a plan may say `Upgrade` when the installed version is
|
||||
already current.
|
||||
- WinGet inventory contains only packages WinGet recognizes. Unknown versions and
|
||||
installer-specific scope failures are reported with WinGet diagnostics.
|
||||
- Package operations are not transactional and are not rolled back after a later
|
||||
failure. Successful independent work is recorded so the next run can resume.
|
||||
- Config Central does not disable Defender, UAC, malware scanning, or installer
|
||||
integrity checks.
|
||||
- Package removal and deletion of formerly managed configs are deliberately
|
||||
manual operations.
|
||||
- [Advanced commands](docs/advanced_commands.md): profiles, packages, conflicts,
|
||||
backups, schedules, and development checks.
|
||||
- [Remote access from CachyOS](docs/advanced-remote-access.md): temporary debugging
|
||||
shells and permanent SSH access.
|
||||
- [Application configs](docs/desktop-app-configs.md): MPC-HC, Ontime, XnView MP,
|
||||
Nextcloud, and hosts.
|
||||
|
|
|
|||
1
TASKS.md
1
TASKS.md
|
|
@ -120,3 +120,4 @@ open until it is run on disposable machines with the required account setups.
|
|||
## Simple web workflow
|
||||
|
||||
- [x] Add a one-command config-only updater using the saved machine and a fresh repository revision, with failure and cleanup tests.
|
||||
- [x] Simplify the README around setup and web config updates; move detailed CLI workflows into an advanced guide.
|
||||
|
|
|
|||
|
|
@ -0,0 +1,288 @@
|
|||
# Advanced commands and maintenance
|
||||
|
||||
Config Central is a small PowerShell CLI for keeping several Windows desktops on
|
||||
the same declared software and configuration baseline. Each machine pulls this
|
||||
Git repository, resolves its profiles, installs or updates declared packages with
|
||||
WinGet, and copies managed config files with drift detection and backups.
|
||||
|
||||
For the everyday setup and config-update commands, see the [README](../README.md).
|
||||
This guide covers the installed CLI, customization, and recovery.
|
||||
|
||||
## Requirements
|
||||
|
||||
- Windows 10 version 1809 or newer, Windows 11, or Windows Server 2025
|
||||
- Windows PowerShell 5.1 for initial bootstrap
|
||||
- PowerShell 7, Git, and WinGet after bootstrap
|
||||
- An interactive desktop account; administrator credentials when a machine-scope
|
||||
installer needs them
|
||||
|
||||
The bootstrap checks and installs its prerequisites. WinGet must be supported by
|
||||
the Windows edition and able to reach its configured sources.
|
||||
|
||||
## Onboard a machine
|
||||
|
||||
Run the one-stop installer in Windows PowerShell:
|
||||
|
||||
```powershell
|
||||
irm 'https://proxy.dandaedre.com/gitea/Beffroi/config-central/raw/branch/main/install.ps1' | iex
|
||||
```
|
||||
|
||||
On a new computer, the installer retrieves the machine manifests and selects the
|
||||
only one, matches the Windows computer name, or displays a numbered prompt. On a
|
||||
configured computer it reuses the saved machine automatically. It then stages
|
||||
`bootstrap.ps1` as a temporary file, establishes every prerequisite, clones or
|
||||
updates the repository, and applies the machine manifest. The temporary file is
|
||||
removed afterward.
|
||||
|
||||
For unattended installation, select the machine in the same command:
|
||||
|
||||
```powershell
|
||||
$env:CONFIG_CENTRAL_MACHINE = 'example-desktop'; irm 'https://proxy.dandaedre.com/gitea/Beffroi/config-central/raw/branch/main/install.ps1' | iex
|
||||
```
|
||||
|
||||
The installer is safe to rerun for repair or setup updates. Use the web updater
|
||||
for routine config updates. Use `cc sync` when you also want package updates.
|
||||
|
||||
Download `bootstrap.ps1` from a trusted revision of this repository, inspect it,
|
||||
then run it from Windows PowerShell:
|
||||
|
||||
```powershell
|
||||
powershell.exe -NoProfile -ExecutionPolicy Bypass -File .\bootstrap.ps1 `
|
||||
-Repository 'https://your-server/you/config-central.git' `
|
||||
-Branch main `
|
||||
-Machine example-desktop
|
||||
```
|
||||
|
||||
The underlying bootstrap repairs WinGet if necessary, installs Git and
|
||||
PowerShell 7, clones the configured branch under
|
||||
`%LOCALAPPDATA%\ConfigCentral\repository`, saves the machine selection, adds `cc`
|
||||
to the user PATH, and performs the first apply. It is safe to rerun after a
|
||||
failed prerequisite installation. Use `-SkipApply` when you only want to
|
||||
establish the checkout and launcher.
|
||||
|
||||
A UAC prompt appears only when administrator work is pending and the current
|
||||
terminal is not already elevated. The prompt covers WinGet repair or the batch
|
||||
of machine-scope packages and machine configuration changes.
|
||||
|
||||
Open a new terminal after bootstrap so the updated user PATH is visible, then
|
||||
check the installation:
|
||||
|
||||
```powershell
|
||||
cc doctor
|
||||
cc plan
|
||||
cc apply
|
||||
```
|
||||
|
||||
## Web config updater
|
||||
|
||||
After setup, run this in Windows PowerShell or PowerShell 7:
|
||||
|
||||
```powershell
|
||||
irm 'https://proxy.dandaedre.com/gitea/Beffroi/config-central/raw/branch/main/update-configs.ps1' | iex
|
||||
```
|
||||
|
||||
The script reads the machine, HTTPS repository URL, and branch saved in
|
||||
`%LOCALAPPDATA%\ConfigCentral\settings.json`. It shallow-clones that branch into a
|
||||
temporary directory, checks out the resolved commit, and runs that revision's
|
||||
CLI with `apply -ConfigsOnly`. It removes the temporary checkout afterward.
|
||||
Git and PowerShell 7 must already be installed by setup.
|
||||
|
||||
There is no machine-selection menu, package installation, or persistent checkout
|
||||
update. Each invocation downloads the current deployment code as well as configs.
|
||||
Existing state, locks, backups, and logs are reused. An administrator prompt may
|
||||
still be required for machine settings such as hosts. Close managed applications
|
||||
first so they do not overwrite deployed settings on exit.
|
||||
|
||||
Local changes remain conflicts. To deliberately back them up and replace them
|
||||
with the online versions:
|
||||
|
||||
```powershell
|
||||
& ([scriptblock]::Create((irm 'https://proxy.dandaedre.com/gitea/Beffroi/config-central/raw/branch/main/update-configs.ps1'))) -ForceConfigs
|
||||
```
|
||||
|
||||
A failed download makes no deployment changes. Partial deployment failures are
|
||||
reported; rerun after correcting the reported problem. The downloaded code runs
|
||||
with your account's permissions, so use a repository you trust.
|
||||
|
||||
The installed `cc` continues to use its existing local checkout. To refresh that
|
||||
checkout and its CLI for advanced work, rerun setup (use `-SkipApply` if
|
||||
you only want to refresh tooling). The web updater itself needs no such refresh.
|
||||
|
||||
## Define profiles and machines
|
||||
|
||||
Profiles live in `profiles/`. Machines live in `machines/` and list profiles in
|
||||
precedence order. Later profiles replace earlier entries; machine entries replace
|
||||
all profile entries. A package is identified by `source/id`, and a config by
|
||||
`name`. Set `enabled` to `false` in a later layer to remove an inherited item.
|
||||
|
||||
```json
|
||||
{
|
||||
"schemaVersion": 1,
|
||||
"name": "workstation",
|
||||
"profiles": ["base", "development"],
|
||||
"packages": [
|
||||
{
|
||||
"id": "Microsoft.VisualStudioCode",
|
||||
"source": "winget",
|
||||
"scope": "machine",
|
||||
"update": "latest"
|
||||
}
|
||||
],
|
||||
"configs": []
|
||||
}
|
||||
```
|
||||
|
||||
Put source files below `configs/`. Config targets accept `%APPDATA%`,
|
||||
`%LOCALAPPDATA%`, `%USERPROFILE%`, and `%PROGRAMDATA%`:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "helix-config",
|
||||
"source": "configs/helix/config.toml",
|
||||
"target": "%APPDATA%/helix/config.toml",
|
||||
"mode": "copy",
|
||||
"requiresPackage": "Helix.Helix"
|
||||
}
|
||||
```
|
||||
|
||||
The complete schema, precedence rules, package policies, and exit codes are in
|
||||
[the manifest contract](manifest-contract.md).
|
||||
|
||||
MPC-HC, Ontime, XnView MP, Nextcloud, and Windows hosts configuration have
|
||||
application-specific safety rules. See the
|
||||
[desktop application configuration guide](desktop-app-configs.md) before
|
||||
populating those declarations.
|
||||
|
||||
## Daily commands
|
||||
|
||||
```powershell
|
||||
cc plan # show intended work; change nothing
|
||||
cc apply # apply the current checkout
|
||||
cc sync # fetch and apply an immutable remote snapshot
|
||||
cc status # show drift and the last run
|
||||
cc sync -ConfigsOnly # fetch and deploy configs; do not call WinGet
|
||||
cc apply -ForceConfigs # back up local edits, then replace them
|
||||
cc configs # show repository and live computer config paths
|
||||
cc configs -Config helix-config # show paths for one managed config
|
||||
cc capture # collect live configs under Documents for upload
|
||||
cc capture -Config ontime-style # capture one config
|
||||
cc restore -Config helix-config # restore the newest backup
|
||||
cc doctor # inspect prerequisites and sources
|
||||
cc menu # optional numbered menu
|
||||
```
|
||||
|
||||
For a two-command temporary debugging shell, or for permanent key-based access
|
||||
from CachyOS, follow the
|
||||
[advanced remote access guide](advanced-remote-access.md#quick-temporary-access).
|
||||
The temporary helper prints an SSH command that opens PowerShell directly;
|
||||
ordinary Windows SSH sessions open `cmd.exe`, which does not recognize `irm`.
|
||||
|
||||
`sync` refuses to run while the checkout has uncommitted or untracked files. It
|
||||
does not reset the checkout. Commit your edits first, or remove files you did not
|
||||
intend to keep.
|
||||
|
||||
Package installs run sequentially. Machine-scope packages are sent together to a
|
||||
constrained elevated worker, so one UAC approval covers the batch. User config
|
||||
paths come from the original desktop session even when different administrator
|
||||
credentials approve the package work. A required reboot is reported with exit
|
||||
code `6`; Config Central never reboots the machine itself.
|
||||
|
||||
## Find and update configuration sources
|
||||
|
||||
Run `cc configs` on a managed computer to see the repository source and resolved
|
||||
live destination for every config. `Present` means the computer destination
|
||||
exists; `Missing` means the application has not created it yet. Use `-Config
|
||||
NAME` to select one entry, or `-Json` for structured output:
|
||||
|
||||
```powershell
|
||||
cc configs
|
||||
cc configs -Config ontime-style
|
||||
cc configs -Config xnviewmp-settings -Json
|
||||
```
|
||||
|
||||
For a `copy` config, close the application, copy the live computer file to the
|
||||
reported repository path, and review `git diff` before committing it. For an
|
||||
`ini-overlay`, copy only the portable keys you intend to manage; do not replace
|
||||
the overlay with the entire application file. Use
|
||||
`tools\Export-MpcHcSettings.ps1` for the MPC-HC registry declaration. Never copy
|
||||
the complete Nextcloud config because it can contain account and authentication
|
||||
data.
|
||||
|
||||
`cc capture` automates the collection side without changing live files. By
|
||||
default it creates
|
||||
`Documents\ConfigCentral\captures\MACHINE-yyyyMMdd-HHmmss`. Whole-file configs
|
||||
retain their `configs/` repository paths. Raw XnView, hosts, and filtered MPC-HC
|
||||
exports are placed under `review/` for curation. Nextcloud capture reads only
|
||||
keys already allowlisted in `managed.ini`; its account sections and complete
|
||||
config are always excluded. Use `-OutputPath PATH` to select an exact empty
|
||||
destination.
|
||||
|
||||
From CachyOS, retrieve a completed capture for review with:
|
||||
|
||||
```bash
|
||||
scp -r USER@WINDOWS-PC:'Documents/ConfigCentral/captures/MACHINE-yyyyMMdd-HHmmss' ./
|
||||
```
|
||||
|
||||
## Config conflicts and recovery
|
||||
|
||||
Config Central stores the hash it last deployed. A different destination hash,
|
||||
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 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`:
|
||||
|
||||
```text
|
||||
settings.json repository, branch, machine, and original user paths
|
||||
state.json deployed hashes, last run, and applied revision
|
||||
logs/ per-run package and config results
|
||||
backups/ timestamped config backups grouped by config name
|
||||
snapshots/ immutable Git commit snapshots used by sync
|
||||
```
|
||||
|
||||
## Optional logon sync
|
||||
|
||||
```powershell
|
||||
cc schedule
|
||||
cc unschedule
|
||||
```
|
||||
|
||||
The scheduled task runs in the interactive user's limited context and always
|
||||
uses `sync -ConfigsOnly`. Package installation remains manual because a logon
|
||||
task must not stall on UAC or an installer prompt.
|
||||
|
||||
## Validation
|
||||
|
||||
On a Windows development machine with Pester 5:
|
||||
|
||||
```powershell
|
||||
Invoke-Pester -Path .\tests
|
||||
```
|
||||
|
||||
Real bootstrap, WinGet, UAC, and separate-admin-account tests require a disposable
|
||||
Windows machine. Opt in to the integration suite there with
|
||||
`CONFIG_CENTRAL_INTEGRATION=1`. The Jenkins pipeline follows the project's
|
||||
FreeBSD worker style and runs dependency-free PowerShell structure, JSON contract,
|
||||
and repository hygiene checks; it does not pretend to execute Windows behavior.
|
||||
|
||||
## Current limitations
|
||||
|
||||
- Config deployment supports whole-file copies and the declared application
|
||||
adapters. It does not merge arbitrary application formats.
|
||||
- `latest` packages are offered to WinGet during apply. WinGet decides whether an
|
||||
upgrade exists, so a plan may say `Upgrade` when the installed version is
|
||||
already current.
|
||||
- WinGet inventory contains only packages WinGet recognizes. Unknown versions and
|
||||
installer-specific scope failures are reported with WinGet diagnostics.
|
||||
- Package operations are not transactional and are not rolled back after a later
|
||||
failure. Successful independent work is recorded so the next run can resume.
|
||||
- Config Central does not disable Defender, UAC, malware scanning, or installer
|
||||
integrity checks.
|
||||
- Package removal and deletion of formerly managed configs are deliberately
|
||||
manual operations.
|
||||
Loading…
Reference in New Issue