config-central/README.md

169 lines
8.4 KiB
Markdown

# Config Central
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.
The workflows below separate initial setup, software updates, and routine config
updates. This keeps each operation explicit and makes its effects easy to review.
## 1. Install software and apply configs
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
```
The bundled machine profile is `beffroi-laptop`, selected automatically. If you
add more machines, setup matches the computer name or asks you to choose one. It
installs Git, PowerShell 7, and the declared software, then applies the configs.
Approve administrator prompts when needed. Existing managed settings are backed
up and replaced with repository versions. Run this command on a new computer,
when you add software to the install list, or when you need to repair setup.
During the first apply, setup shows an elapsed spinner while it inventories and
installs software; redirected output receives a plain status line instead.
Requires Windows 10 1809 or newer, Windows 11, or Windows Server 2025, with
internet access and support for WinGet.
Setup installs PowerShell using the official MSI (`--installer-type wix`), which
bundles its .NET runtime. It checks that PowerShell starts before configuring the
checkout and pins the `cc` launcher to that executable. A broken existing
installation is reported for repair rather than silently replaced. If startup
asks for .NET, keep the full error and check which executable is being launched
with `Get-Command pwsh.exe -All` in Windows PowerShell; a .NET-tool installation
or a stale PATH entry can differ from the MSI installation.
Config Central does not update PowerShell during apply or software updates,
because replacing its own runtime can interrupt the operation. Update PowerShell
separately with Config Central and PowerShell 7 sessions closed, using the original
installation method. For an MSI installation, run this from **Windows PowerShell**:
```powershell
winget upgrade --id Microsoft.PowerShell --exact --source winget --installer-type wix
```
WinGet can recognize manually installed software too. Previously the base profile
requested PowerShell upgrades, which could replace that manual installation.
The installer logs are needed to establish why a particular upgrade left it missing.
See Microsoft's [PowerShell installation and upgrade guidance](https://learn.microsoft.com/en-us/powershell/scripting/install/install-powershell-on-windows).
## 2. Update installed software
Close applications that may be updated, open PowerShell as your normal desktop
user, and run:
```powershell
cc update-software
```
`cc software-update` is an equivalent alias. The command shows an elapsed
spinner while its refreshed snapshot updates software. Redirected output gets a
single plain status line, and `-Json` remains machine-readable without progress
text.
This command updates Config Central and the software selected by the machine
manifest without deploying any configs. It runs operations in this order:
1. Fetch the configured repository branch and run the rest of the command from
an immutable snapshot of that exact commit. This gives the update the latest
Config Central code and software policy without replacing a running script.
2. Resolve and apply opted-in portable packages. Config Central selects the
newest release allowed by the package's channel, downloads its exact Windows
asset, verifies it against the release's published SHA-256 checksum, stages
it in a new version directory, and switches to it only after setup succeeds.
3. Install or upgrade every declared WinGet package by exact ID and source,
according to its `latest`, `pinned`, or `install-only` policy. Applications
not declared in Config Central are left alone; the command does not run an
unrestricted `winget upgrade --all`.
After the snapshot finishes, Config Central fast-forwards its installed checkout
to that same revision so later `cc` commands use the updated CLI. A checkout that
has diverged is preserved and reported as a failed self-update.
Machine-scope WinGet operations may request administrator approval. Config
Central preserves installer diagnostics, continues independent packages after
an item failure, reports reboot requirements, and never restarts Windows. Close
a running portable application before updating it. The working version remains
available until its replacement is fully activated, then older versions are removed.
The desktop profile installs Deckstride and PPTX Reporter as verified portable
packages and creates per-user Start menu shortcuts under Config Central.
Deckstride is also registered as a per-user PDF handler, with a separate document
icon based on its turquoise presentation mark. After the first
`cc update-software` or full apply, open its Windows Default Apps page:
```powershell
Start-Process 'ms-settings:defaultapps?registeredAppUser=ConfigCentral.idle-org.deckstride'
```
Select Deckstride for `.pdf`. On older Windows builds that open the general
Default Apps page, right-click a PDF, choose **Open with → Choose another app**,
select **Deckstride**, and enable **Always**. Windows requires this one-time
user confirmation and Config Central preserves that choice across updates.
The first Deckstride update installs and verifies
[Deckstride 0.1.96](https://proxy.dandaedre.com/gitea/idle-org/Deckstride/releases/tag/v0.1.96)
before removing the managed PDF Presenter files, Start menu shortcut and old
handler registration. Cleanup also removes PDF Presenter's obsolete Default Apps
and **Open with** registry entries. The desktop policy declares Pympress absent,
so Config Central uninstalls it by its exact WinGet ID when found and treats an
already removed copy as unchanged.
Like `cc sync`, `update-software` refuses to fetch while the checkout contains
uncommitted or untracked files. It does not reset or overwrite those edits.
For the release declaration and manual pin-review workflow, see
[portable package updates](docs/advanced_commands.md#portable-package-updates).
## 3. Update configs without touching software
Close the applications whose settings you are updating, then paste into
**PowerShell**:
```powershell
irm 'https://proxy.dandaedre.com/gitea/Beffroi/config-central/raw/branch/main/update-configs.ps1' | iex
```
This downloads the latest configs and updater code from your saved repository
branch and applies them to your saved machine profile, using the same config
deployment as install. It skips prerequisite setup and software installation or
upgrades. No menu or manual Git pull is needed; temporary downloads are removed
afterward. Run install once before using update on a new computer.
Unchanged configs are skipped. Local settings are backed up and replaced with
the repository versions by default. To preserve local edits instead, see
[advanced update options](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
cc capture
```
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.
This includes Windows sound-event settings and the active power plan's battery
screen timeout. The repository defaults disable system sounds and keep the
screen on while on battery.
Capture does not upload anything automatically; some exports need curation.
See the [application config guide](docs/desktop-app-configs.md) for details.
## Troubleshooting and advanced use
Run `cc doctor` in a new terminal to check setup, or `cc status` to inspect the
last run and config drift. Status colors highlight failures (red), conflicts or
skips (yellow), completed work (green), and unchanged items (gray).
- [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.