config-central/README.md

257 lines
10 KiB
Markdown

# 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.
There is no central server or resident agent. The normal workflow is:
```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:
```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 `cc sync` for
normal repository, package, and configuration updates after onboarding.
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
```
## 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.