Central config manager
Go to file
Dandaedre 3f8fe66e48
Config Central CI Config Central passed all CI integrity checks.
Beffroi/config-central/pipeline/head This commit looks good Details
Add one-stop web installer
2026-10-17 09:03:09 +02:00
configs Updated configs 2026-10-17 08:05:12 +02:00
docs Document CachyOS SSH client setup 2026-10-17 08:11:12 +02:00
machines Add requested desktop application packages 2026-10-16 14:25:36 +02:00
profiles Add Shotcut to desktop packages 2026-10-16 17:04:12 +02:00
schemas Add application configuration adapters 2026-10-16 14:29:15 +02:00
src Fix web bootstrap elevation 2026-10-17 08:13:39 +02:00
tests Add one-stop web installer 2026-10-17 09:03:09 +02:00
tools Show managed config locations 2026-10-17 08:01:21 +02:00
AGENTS.md Add one-stop web installer 2026-10-17 09:03:09 +02:00
Jenkinsfile Add one-stop web installer 2026-10-17 09:03:09 +02:00
README.md Add one-stop web installer 2026-10-17 09:03:09 +02:00
TASKS.md Add one-stop web installer 2026-10-17 09:03:09 +02:00
bootstrap.ps1 Fix web bootstrap elevation 2026-10-17 08:13:39 +02:00
cc.cmd Wire CLI planning and apply workflow 2026-10-16 13:48:50 +02:00
cc.ps1 Show managed config locations 2026-10-17 08:01:21 +02:00
install.ps1 Add one-stop web installer 2026-10-17 09:03:09 +02:00

README.md

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:

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:

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:

$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.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:

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.

{
  "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%:

{
  "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.

MPC-HC, Ontime, XnView MP, Nextcloud, and Windows hosts configuration have application-specific safety rules. See the desktop application configuration guide before populating those declarations.

Daily commands

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 restore -Config helix-config # restore the newest backup
cc doctor                       # inspect prerequisites and sources
cc menu                         # optional numbered menu

For key-based shells, file transfer, and remote Config Central commands from CachyOS, follow the advanced remote access guide.

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:

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.

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:

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

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:

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.