432 lines
20 KiB
Markdown
432 lines
20 KiB
Markdown
# 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 = 'beffroi-laptop'; irm 'https://proxy.dandaedre.com/gitea/Beffroi/config-central/raw/branch/main/install.ps1' | iex
|
|
```
|
|
|
|
Setup backs up and replaces existing managed settings by default, just like the
|
|
web config updater. To preserve local settings and report conflicts during setup:
|
|
|
|
```powershell
|
|
& ([scriptblock]::Create((irm 'https://proxy.dandaedre.com/gitea/Beffroi/config-central/raw/branch/main/install.ps1'))) -PreserveLocalConfigs
|
|
```
|
|
|
|
The same `-PreserveLocalConfigs` switch is available on `bootstrap.ps1`.
|
|
`-SkipApply` continues to skip deployment entirely.
|
|
|
|
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 beffroi-laptop
|
|
```
|
|
|
|
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
|
|
```
|
|
|
|
### Switching an existing example-desktop setup
|
|
|
|
After pulling this change, rerun the web installer once to replace the saved
|
|
`example-desktop` selection with `beffroi-laptop`. To refresh setup without
|
|
deploying configs or packages:
|
|
|
|
```powershell
|
|
& ([scriptblock]::Create((irm 'https://proxy.dandaedre.com/gitea/Beffroi/config-central/raw/branch/main/install.ps1'))) -Machine beffroi-laptop -SkipApply
|
|
```
|
|
|
|
## 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.
|
|
|
|
The web updater defaults to `-ForceConfigs`: local settings are backed up and
|
|
replaced with the online versions. To preserve local edits and report conflicts
|
|
instead, explicitly disable force:
|
|
|
|
```powershell
|
|
& ([scriptblock]::Create((irm 'https://proxy.dandaedre.com/gitea/Beffroi/config-central/raw/branch/main/update-configs.ps1'))) -ForceConfigs:$false
|
|
```
|
|
|
|
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 web updater leaves the installed `cc` checkout unchanged. Run
|
|
`cc update-software` to refresh the CLI and installed software, or rerun setup
|
|
with `-SkipApply` when you only want to repair the checkout and launcher.
|
|
|
|
## 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 update-software # refresh cc, then update declared software
|
|
cc software-update # alias for update-software
|
|
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' ./
|
|
```
|
|
|
|
## Setup outcomes
|
|
|
|
When deployment is incomplete, the web installer shows a short summary after the
|
|
per-item results. Successful changes remain applied. Correct the listed issue
|
|
and rerun setup. Reboot requests and an already-running update have separate
|
|
messages. Deployment logs are under `%LOCALAPPDATA%\ConfigCentral\logs`.
|
|
|
|
Running `install.ps1` as a file preserves the bootstrap process exit code.
|
|
With `irm | iex`, the terminal stays open and `$LASTEXITCODE` contains that code.
|
|
Runtime failures in setup, bootstrap, updates, capture, and SSH helpers use the
|
|
same concise error presentation. Native installer diagnostics remain visible;
|
|
PowerShell parameter-binding or syntax errors can still use PowerShell formatting.
|
|
|
|
## 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.
|
|
- Deletion of formerly managed configs remains manual. Removing a package entry
|
|
only stops management; an explicit WinGet `state: "absent"` policy uninstalls
|
|
that exact package.
|
|
|
|
Item results color status labels; script summaries use the same palette: red
|
|
errors, yellow warnings, green completion, gray unchanged items, and cyan planned
|
|
actions. Redirected output and JSON remain plain. Set `$env:NO_COLOR = "1"` to
|
|
disable colors in a terminal. Errors go to stderr; JSON errors stay structured.
|
|
Runtime failures preserve nonzero status codes, and web commands leave the
|
|
terminal open with the outcome in `$LASTEXITCODE`.
|
|
|
|
## Portable package updates
|
|
|
|
The desktop profile includes Deckstride 0.1.96 and PPTX Reporter 0.2.0 for
|
|
Windows x64 from their published portable releases. Their exact ZIP hashes and
|
|
executable paths were checked against each release's SHA256SUMS and artifact
|
|
manifest. The Windows binaries are unsigned; native Windows acceptance remains
|
|
pending here too.
|
|
|
|
Portable packages use `provider: "portable"`, user scope and a version pinned in
|
|
Git. `source` is a namespace (here `idle-org`), not a WinGet source. They appear
|
|
alongside WinGet packages in `cc plan`, `cc status`, `cc apply` and full `cc sync`.
|
|
Config-only commands and the scheduled config sync leave software alone.
|
|
|
|
To update installed software, close Deckstride and PPTX Reporter and run:
|
|
|
|
```powershell
|
|
cc update-software
|
|
```
|
|
|
|
`cc software-update` runs the same command. In an interactive terminal the
|
|
outer command shows an elapsed spinner while the refreshed snapshot works.
|
|
Redirected output gets one plain start line; `-Json` suppresses progress output.
|
|
|
|
The command fetches the configured repository branch and continues from an
|
|
immutable snapshot of that commit, so the current run uses the latest Config
|
|
Central code and policy. It then checks the Gitea releases API for opted-in
|
|
portable packages and asks WinGet to apply each declared package's policy by
|
|
exact ID. Deckstride follows the newest eligible stable release.
|
|
Unmanaged WinGet applications are left alone. Configs are not planned or changed.
|
|
The profile declares Pympress absent, so each software run silently leaves it
|
|
alone when missing and uninstalls it by exact WinGet ID when found.
|
|
Each release lookup resolves one exact ZIP, reads its exact entry from
|
|
`SHA256SUMS`, and verifies the downloaded archive before activation. Both tools
|
|
follow stable releases. A lookup or checksum failure is reported for that package
|
|
while independent packages continue. As with `sync`, local checkout changes must be committed or removed
|
|
before the fetch; Config Central never discards them automatically. After the
|
|
software run, the installed checkout is advanced to the resolved commit with a
|
|
fast-forward-only merge so subsequent `cc` commands use the refreshed version.
|
|
|
|
To review and advance the deterministic repository pin:
|
|
|
|
1. Select and review an upstream release, download its Windows portable ZIP,
|
|
and compare `Get-FileHash -Algorithm SHA256` with its published SHA256SUMS.
|
|
2. Update `version`, `url`, `sha256` and `executable` together in
|
|
`profiles/desktop-apps.json`. Use the version-specific download URL. These
|
|
fields remain the reviewed fallback used by `apply` and `sync`; only the
|
|
explicit `update-software` command follows the configured release channel.
|
|
3. Commit and push the change. `cc sync` applies that pin on each desktop. Use
|
|
`cc apply` for an updated local checkout; `cc plan` previews the pin without
|
|
contacting the release API or downloading it.
|
|
|
|
Default files live under
|
|
`%LOCALAPPDATA%\ConfigCentral\apps\idle-org\deckstride`. `launch.ps1` is the
|
|
stable terminal launcher; the Start menu shortcut under `Config Central\idle-org`
|
|
targets `deckstride.exe` directly and uses its embedded icon. `current.json`
|
|
records the active version and hashes. A successful update removes older managed
|
|
version directories. The working version remains active when download,
|
|
verification, or setup fails. Removing the profile entry does not uninstall anything.
|
|
|
|
The package also declares `displayName`, `fileAssociations`, and a dedicated
|
|
`fileAssociationIcon`, which register Deckstride per user as a `.pdf` handler
|
|
with Windows Default Apps. Config Central copies the icon into the stable package
|
|
root so Explorer does not depend on a versioned executable. The open command
|
|
passes the selected PDF directly to the active executable. Windows requires the
|
|
user to confirm the protected default-app choice. After applying the package,
|
|
open its settings page and select Deckstride for `.pdf`:
|
|
|
|
```powershell
|
|
Start-Process 'ms-settings:defaultapps?registeredAppUser=ConfigCentral.idle-org.deckstride'
|
|
```
|
|
|
|
Updates repair the registration to point at the new verified executable without
|
|
rewriting the user's default-app preference.
|
|
|
|
Deckstride's declaration includes a `replaces` entry for
|
|
`idle-org/pdf-presenter`. On the first successful update, Config Central
|
|
activates Deckstride before removing PDF Presenter's managed files, shortcut and
|
|
old `.pdf` registration, including PDF Presenter's own obsolete Default Apps and
|
|
Open With ProgID entries. If the old installation was locally modified or cannot
|
|
be removed, Deckstride stays installed and cleanup is retried later. Select
|
|
Deckstride once in Windows Default Apps because Windows does not allow software
|
|
to transfer the protected `.pdf` default choice to a renamed handler.
|
|
|
|
On a failed download, checksum check or setup step, fix the reported cause and
|
|
retry. Missing managed files are repaired. Locally changed binaries or launchers
|
|
are conflicts: inspect and save those changes elsewhere, then remove the affected
|
|
file to let the next apply repair it. `-ForceConfigs` does not override portable
|
|
package conflicts. Never change the hash of an existing release to bypass a
|
|
checksum mismatch. Cleanup failures are warnings and are retried on the next run
|
|
without another download. Persistent application settings must live outside the
|
|
managed version directory because older versions are deleted after activation.
|
|
|
|
Linux Pester tests cover archive validation, hash verification, partial failure,
|
|
retry, version policies, conflict handling, launcher errors and elevation
|
|
rejection. Disposable Windows x64 acceptance still needs to verify first install,
|
|
Start menu launch, a no-change rerun, running-app refusal, and an upgrade with
|
|
settings preserved. Run the controller as the desktop user, not as a separate
|
|
administrator account.
|