Document setup and operating workflow
Beffroi/config-central/pipeline/head There was a failure building this commit
Details
Beffroi/config-central/pipeline/head There was a failure building this commit
Details
This commit is contained in:
parent
0de3272d54
commit
32e83a6e5c
|
|
@ -0,0 +1,177 @@
|
|||
# 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
|
||||
|
||||
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
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
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).
|
||||
|
||||
## 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 restore -Config helix-config # restore the newest backup
|
||||
cc doctor # inspect prerequisites and sources
|
||||
cc menu # optional numbered menu
|
||||
```
|
||||
|
||||
`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.
|
||||
|
||||
## 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 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.
|
||||
|
||||
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.
|
||||
8
TASKS.md
8
TASKS.md
|
|
@ -1,7 +1,7 @@
|
|||
# Implementation tasks
|
||||
|
||||
The architecture is agreed as a starting point; implementation has not begun.
|
||||
Complete the core CLI and manual workflow before optional automation or a TUI.
|
||||
The core CLI and manual workflow are implemented. Windows-only validation remains
|
||||
open until it is run on disposable machines with the required account setups.
|
||||
|
||||
## 1. Define manifests and command contracts
|
||||
|
||||
|
|
@ -87,9 +87,9 @@ Complete the core CLI and manual workflow before optional automation or a TUI.
|
|||
- [ ] Test elevation using both the same account and separate admin credentials.
|
||||
- [x] Test paths containing spaces/non-ASCII characters and interrupted runs.
|
||||
- [x] Test config-only updates and recovery after an installer requests a reboot.
|
||||
- [ ] Write README instructions for onboarding a machine, editing profiles,
|
||||
- [x] Write README instructions for onboarding a machine, editing profiles,
|
||||
syncing, resolving conflicts, restoring configs, and finding logs.
|
||||
- [ ] Document supported Windows versions, limitations, and which verification
|
||||
- [x] Document supported Windows versions, limitations, and which verification
|
||||
requires Windows.
|
||||
|
||||
## Later, only when useful
|
||||
|
|
|
|||
Loading…
Reference in New Issue