169 lines
8.4 KiB
Markdown
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.
|