diff --git a/README.md b/README.md index 6a3703b..532cd94 100644 --- a/README.md +++ b/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. diff --git a/TASKS.md b/TASKS.md index 7b8235f..eac62bb 100644 --- a/TASKS.md +++ b/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. diff --git a/docs/advanced_commands.md b/docs/advanced_commands.md new file mode 100644 index 0000000..9888bd6 --- /dev/null +++ b/docs/advanced_commands.md @@ -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.