# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## What this is

A Fedora automated mass-installation and post-setup scripting collection. It uses an **OEMDRV** partition (BTRFS, mounted at `/opt/sys_config`) that Anaconda/Kickstart picks up automatically during Fedora installation. The system requires:
- A FreeIPA server (domain controller, KRA vault for encryption keys)
- A Nextcloud instance (config and software sync, WebDAV token auth)
- Client PCs with an OEMDRV partition prepared beforehand

## Configuration

Before any script runs, copy the dist file and fill in your environment:
```sh
cp /opt/sys_config/config/setup_system.conf.dist /opt/sys_config/config/setup_system.conf
# Edit setup_system.conf with your domain, server FQDNs, paths, etc.
```

Local per-machine overrides go in `config.d/*.conf` (gitignored). These are sourced after `setup_system.conf` and can override any exported variable (e.g. `config.d/system_defines.conf` overrides `UPGRADEBRANCH`).

`config/skel.tar.zst` (gitignored) holds the `/etc/skel` archive deployed to new installs. The `.dist` version is the default. To modify skel: extract, edit, then repack:
```sh
cd /opt/sys_config/config
tar -I 'zstd -9' -cf skel.tar.zst skel/   # or use pack_skel.sh
```

## Installation lifecycle

1. **Kickstart pre** — `ks_base_profiles/basic_pre_script.inc` runs inside Anaconda's `%pre` section. It locates the OEMDRV partition, identifies the target drive, and **deletes all other partitions on that drive** (non-interactive, no prompt).

2. **Kickstart post** — After Fedora installs, `setup_system_full.sh install` runs (as root, non-interactive). It adjusts umask, adds the OEMDRV fstab entry, deploys `/etc/skel` via `setup_skel.sh`, and installs the `setup-system.service` systemd unit.

3. **First boot** (`firstrun_run` mode) — The `setup-system.service` unit runs `setup_system_full.sh firstrun_run` on `/dev/tty2`. It calls `ipa_register_host` which prompts for domain credentials and joins the PC to FreeIPA via `ipa-client-install`. The service then disables itself.

4. **User logon** — `logon_script.sh` is triggered by KDE autostart. It:
   - Mounts the gocryptfs-encrypted home directory (`mount_ecrypt_home.sh`) using a key stored in the FreeIPA KRA vault (`IPAVAULTNAME`)
   - Obtains a Nextcloud WebDAV app token (`get_nc_token` in `setup_system.inc.sh`)
   - Checks for a matching IPA sudo rule, then calls `sync_client_software.sh install` as root (preserving env) to sync configs and run software installs
   - Calls `client_software/user_run.sh` (as the logged-in user)
   - Syncs Firefox and Thunderbird profiles via Nextcloud (`mozilla_starter.sh`)

## Script roles

| Script | Who runs it | How called |
|---|---|---|
| `system_setup/setup_system.inc.sh` | sourced, never executed directly | `source`d by all other scripts |
| `system_setup/setup_system_full.sh` | root | kickstart post, firstrun service, or manual |
| `system_setup/logon_script.sh` | domain user | KDE autostart (via `.desktop` in autostart) |
| `system_setup/sync_client_software.sh` | root (sudo, preserve-env) | called by logon_script.sh |
| `system_setup/mount_ecrypt_home.sh` | user | called by logon_script.sh |
| `system_setup/mozilla_starter.sh` | user | called by logon_script.sh; args: `firefox\|thunderbird run\|sync [profile]` |
| `system_setup/setup_skel.sh` | root | called by setup_system_full.sh or manually |
| `config/pack_skel.sh` | root | manually, to repack skel archive after editing |
| `system_setup/create_nc_package_from_sys_config.sh` | user | manually, creates `~/temp/sys_config.tar.zst` |

## client_software layout

`client_software/` is synced from Nextcloud (`CLIENT_SOFTWARE_SRC` → `CLIENT_SOFTWARE_DST`). Each numbered subdirectory may contain:
- `install.sh` — run as root by `client_software/install.sh` (iterates sorted dirs)
- `user_run.sh` — run as the logged-in user by `client_software/user_run.sh`

Naming convention: directories `< 0100` are base installs, `>= 0100` are additional apps. Pass a filter string to run only matching directories:
```sh
# Run only the kwallet install:
${CLIENT_SOFTWARE_DST}/install.sh 0010_kwallet
```

## Kickstart files

- `ks.cfg` — the primary kickstart used for production installs (Fedora 43, KDE, x86_64, German locale/keyboard)
- `ks_base_profiles/kde_fullsetup.cfg` — an alternate/reference profile generated by Anaconda
- `ks_pc_prof/` — per-machine kickstart overrides, named by system UUID suffix (e.g. `pc-9cdb93ef7c20.cfg`)

## Sudo rule required for logon_script

The logon script requires a FreeIPA sudo rule allowing the domain user group to run `sync_client_software.sh` as root without a password, with environment preservation. The rule must include `!authenticate` and `setenv` options. The expected command pattern:
```
^/opt/sys_config/system_setup/sync_client_software\.sh.*$
```

## gitignore notes

The following are intentionally excluded from git and must be set up locally:
- `config/setup_system.conf` — site-specific config (copy from `.dist`)
- `config/skel.tar.zst` — skel archive (copy from `.dist` or rebuild)
- `config.d/*.conf` — local overrides
- `client_software/.sync_*.db` — Nextcloud sync DB files