feat(forge): chain mios-forge admin creation through build-mios.ps1 + install.env + firstboot service

End-to-end chain so the user identity defined in mios-bootstrap.git/
mios.toml propagates all the way to the Forgejo admin account on the
deployed image:

  mios-bootstrap/mios.toml
        |
        v
  build-mios.ps1   (Windows orchestrator) interactive prompts
  build-mios.sh    (bootstrap Linux installer) interactive prompts
        |  Read-Timed / prompt_default with 3-min auto-accept
        |  defaulting to MIOS_LINUX_USER and <user>@<host>.local
        v
  /etc/mios/install.env (mode 0640 in the imported WSL2 distro)
        |  written by tools/lib/install-env.ps1 (Windows side) and
        |  by build-mios.sh's PROFILE_FILE writer (Linux side); both
        |  emit MIOS_FORGE_ADMIN_USER, MIOS_FORGE_ADMIN_EMAIL, and
        |  MIOS_FORGE_ADMIN_PASSWORD= (empty -> generated below)
        v
  mios-forge.service starts at boot
        v
  mios-forge-firstboot.service (oneshot, RemainAfterExit=yes)
        |  After=mios-forge.service; runs once per fresh deployment;
        |  ConditionPathExists guards on install.env presence and on
        |  absence of the .firstboot-done sentinel.
        v
  /usr/libexec/mios/forge-firstboot.sh
        |  - waits up to 300s for Forgejo's /api/v1/version probe
        |  - if MIOS_FORGE_ADMIN_PASSWORD empty, generates a 24-byte
        |    URL-safe random pwd, writes /etc/mios/forge/admin-password
        |    (root-owned, mode 0600); operator reads via 'sudo cat'
        |  - 'podman exec mios-forge forgejo admin user create
        |    --admin --must-change-password=true' against the values
        |    from install.env
        |  - drops a sentinel at /var/lib/mios/forge/.firstboot-done
        |    so re-boots are no-ops
        v
  Operator runs:
    git remote add origin http://localhost:3000/<user>/<repo>.git
    git push origin main

NEW FILES (mios.git)

  usr/libexec/mios/forge-firstboot.sh      (executable; bash -n clean)
  usr/lib/systemd/system/mios-forge-firstboot.service
                                           (oneshot; ProtectSystem=
                                           strict; ReadWritePaths
                                           scoped to forge dirs only)

UPDATED FILES (mios.git)

  tools/lib/install-env.ps1
        Write-MiosInstallEnv signature gains -ForgeAdminUser and
        -ForgeAdminEmail (both default to the linux identity if
        omitted). Three new lines emitted into install.env:
        MIOS_FORGE_ADMIN_USER, MIOS_FORGE_ADMIN_EMAIL,
        MIOS_FORGE_ADMIN_PASSWORD= (empty -> firstboot generates).

  build-mios.ps1
        - Phase-0 custom workflow now prompts for forge admin user +
          email via Read-Timed (3-min auto-accept, defaulting to the
          linux $U and $U@$HostIn.local).
        - Non-custom workflow takes the same defaults silently.
        - WSL2 deployment branch passes $ForgeAdmin / $ForgeEmail
          through Write-MiosInstallEnv.
        - Phase-5 build summary prints the forge URL, admin user/email,
          how to read the generated password, and a 'git remote add'
          one-liner so the operator has the locally-hosted .git=./
          flow at their fingertips.

UPDATED FILES (mios-bootstrap.git, sibling commit)

  build-mios.sh
        - Phase-0 gather_user_choices() prompts for FORGE_ADMIN_USER
          and FORGE_ADMIN_EMAIL with the same 3-minute timeout
          (defaulting to LINUX_USER and LINUX_USER@HOSTNAME_VAL.local).
        - install.env writer emits the three MIOS_FORGE_ADMIN_*
          lines; password stays empty so firstboot can generate.

POSTCHECK COVERAGE

  No new failures introduced. The new oneshot service ships in
  /usr/lib/systemd/system/, where systemd-analyze verify already runs
  in postcheck #10. ConditionVirtualization=!container keeps it from
  trying to exec into a non-existent Quadlet inside nested containers.

Author: Kabuki94

build-mios.ps1

@@ -346,6 +346,14 @@ if ($DoCustom) {
     $LuksPass = if ($UseLuks) { Read-Timed "LUKS passphrase:" "mios" -Secret } else { "" }
     $RegistryUrl = Read-Timed "Registry URL:" $DefRegistry
 
+    # mios-forge (Forgejo) admin -- defaults to the linux identity above so
+    # the locally-hosted .git = ./ pattern works without further config.
+    # Empty password -> firstboot generates a random one and stores it at
+    # /etc/mios/forge/admin-password (root-owned, mode 0600).
+    $forgeHostFallback = if ($HostIn) { $HostIn } else { "mios" }
+    $ForgeAdmin = Read-Timed "Forge admin username (Forgejo):" $U
+    $ForgeEmail = Read-Timed "Forge admin email:" "$U@$forgeHostFallback.local"
+
     Write-Host ""
     Write-Host "      Select Deployment Targets (comma separated or 'all'):" -ForegroundColor DarkCyan
     Write-Host "      1) RAW, 2) VHDX, 3) WSL, 4) ISO" -ForegroundColor DarkGray
@@ -359,6 +367,8 @@ if ($DoCustom) {
     $UseLuks = $false
     $LuksPass = ""
     $RegistryUrl = $DefRegistry
+    $ForgeAdmin = $U
+    $ForgeEmail = if ($env:MIOS_FORGE_ADMIN_EMAIL) { $env:MIOS_FORGE_ADMIN_EMAIL } else { "$U@$(if($HostIn){$HostIn}else{'mios'}).local" }
 
     # Target selection inheritance
     if ($env:MIOS_TARGETS) {
@@ -912,7 +922,7 @@ if ($env:MIOS_SKIP_DEPLOY -eq "1") {
 
                         # Seed /etc/mios/install.env so wsl-firstboot.service uses the
                         # operator-supplied identity instead of the default 'mios' password.
-                        if (Write-MiosInstallEnv -WslDistro $WslName -User $U -PasswordHash $passHash -Hostname $HostIn) {
+                        if (Write-MiosInstallEnv -WslDistro $WslName -User $U -PasswordHash $passHash -Hostname $HostIn -ForgeAdminUser $ForgeAdmin -ForgeAdminEmail $ForgeEmail) {
                             Write-OK "Seeded /etc/mios/install.env (user=$U, host=$HostIn)"
                         } else {
                             Write-Warn "install.env not written -- first-boot will fall back to default 'mios' password"
@@ -1023,6 +1033,22 @@ Write-Host "  On deployed 'MiOS':  mios-rebuild" -ForegroundColor Cyan
 Write-Host "  On any machine:       podman pull $GhcrImage" -ForegroundColor Cyan
 Write-Host ""
 
+# -- mios-forge (Forgejo) post-deploy operator hint --
+# The forge ships disabled-by-default behavior is bounded by the Quadlet's
+# Condition* directives, not by us; but we tell the operator how to reach
+# it once the deployed image boots and mios-forge-firstboot.service has
+# created the admin user from /etc/mios/install.env.
+$forgeUser = if ($ForgeAdmin) { $ForgeAdmin } else { $U }
+$forgeMail = if ($ForgeEmail) { $ForgeEmail } else { "$U@$(if($HostIn){$HostIn}else{'mios'}).local" }
+Write-Host "  Self-hosted Git forge (mios-forge / Forgejo)" -ForegroundColor Cyan
+Write-Host "    Web UI:        http://localhost:3000/" -ForegroundColor Gray
+Write-Host "    git+ssh:       ssh://git@localhost:2222/<user>/<repo>.git" -ForegroundColor Gray
+Write-Host "    Admin user:    $forgeUser" -ForegroundColor Gray
+Write-Host "    Admin email:   $forgeMail" -ForegroundColor Gray
+Write-Host "    Initial pwd:   sudo cat /etc/mios/forge/admin-password    (must change on first login)" -ForegroundColor Gray
+Write-Host "    Local push:    cd <repo>; git remote add origin http://localhost:3000/$forgeUser/<repo>.git; git push origin main" -ForegroundColor Gray
+Write-Host ""
+
 Write-Progress -Activity "'MiOS' Build ${Version}" -Id 0 -Completed
 
 Show-StatusCard

tools/lib/install-env.ps1

@@ -14,7 +14,9 @@ function Write-MiosInstallEnv {
         [Parameter(Mandatory)][string]$WslDistro,
         [Parameter(Mandatory)][string]$User,
         [Parameter(Mandatory)][string]$PasswordHash,
-        [Parameter(Mandatory)][string]$Hostname
+        [Parameter(Mandatory)][string]$Hostname,
+        [string]$ForgeAdminUser  = "",
+        [string]$ForgeAdminEmail = ""
     )
 
     # The hash MUST be sha512crypt ($6$salt$digest). Anything else is a bug
@@ -26,17 +28,25 @@ function Write-MiosInstallEnv {
         return $false
     }
 
+    # Default the forge admin to the linux user identity if not supplied.
+    if (-not $ForgeAdminUser)  { $ForgeAdminUser  = $User }
+    if (-not $ForgeAdminEmail) { $ForgeAdminEmail = "$User@$Hostname.local" }
+
     # Single-quote the hash because $6$... contains literal $-sigils that
     # bash would otherwise treat as parameter expansion when the env file
     # is sourced. sha512crypt charset is [A-Za-z0-9./$] -- no single quotes
     # ever appear in the hash, so the wrap is safe.
     $lines = @(
         "# /etc/mios/install.env -- written by the 'MiOS' Windows installer.",
-        "# Read by /usr/libexec/mios/wsl-firstboot and /usr/libexec/mios/motd.",
+        "# Read by /usr/libexec/mios/wsl-firstboot, /usr/libexec/mios/motd,",
+        "# and /usr/libexec/mios/forge-firstboot.sh.",
         "# Vendor defaults: /usr/share/mios/env.defaults",
         "MIOS_USER=$User",
         "MIOS_USER_PASSWORD_HASH='$PasswordHash'",
-        "MIOS_HOSTNAME=$Hostname"
+        "MIOS_HOSTNAME=$Hostname",
+        "MIOS_FORGE_ADMIN_USER=$ForgeAdminUser",
+        "MIOS_FORGE_ADMIN_EMAIL=$ForgeAdminEmail",
+        "MIOS_FORGE_ADMIN_PASSWORD="
     )
     $body = ($lines -join "`n") + "`n"
 

usr/lib/systemd/system/mios-forge-firstboot.service

@@ -0,0 +1,32 @@
+[Unit]
+Description='MiOS' Forge first-boot admin-bootstrap (Forgejo)
+Documentation=https://github.com/mios-dev/MiOS/blob/main/etc/containers/systemd/mios-forge.container
+After=mios-forge.service network-online.target
+Wants=mios-forge.service network-online.target
+ConditionPathExists=/etc/mios/install.env
+ConditionPathExists=!/var/lib/mios/forge/.firstboot-done
+ConditionVirtualization=!container
+
+[Service]
+Type=oneshot
+RemainAfterExit=yes
+EnvironmentFile=-/etc/mios/install.env
+ExecStart=/usr/libexec/mios/forge-firstboot.sh
+TimeoutStartSec=600s
+
+# Hardening: this service writes to a small set of paths, so we lock
+# everything else down. The script needs network for the readiness
+# probe and podman exec, plus write access to the password / sentinel
+# files declared in usr/lib/tmpfiles.d/mios-forge.conf.
+NoNewPrivileges=yes
+ProtectSystem=strict
+ProtectHome=yes
+ReadWritePaths=/etc/mios/forge /var/lib/mios/forge /var/log/mios/forge
+PrivateTmp=yes
+RestrictAddressFamilies=AF_UNIX AF_INET AF_INET6
+RestrictNamespaces=yes
+LockPersonality=yes
+RestrictRealtime=yes
+
+[Install]
+WantedBy=multi-user.target

usr/libexec/mios/forge-firstboot.sh

@@ -0,0 +1,114 @@
+#!/usr/bin/env bash
+# /usr/libexec/mios/forge-firstboot.sh
+#
+# First-boot admin-bootstrap for the mios-forge Quadlet (Forgejo).
+# Runs once via mios-forge-firstboot.service after mios-forge.service is
+# healthy. Creates the operator's admin user using values that
+# mios-bootstrap install.sh wrote to /etc/mios/install.env, which were
+# themselves resolved from mios-bootstrap.git/mios.toml at install time:
+#
+#   MIOS_FORGE_ADMIN_USER     defaults to MIOS_LINUX_USER ([identity].username)
+#   MIOS_FORGE_ADMIN_EMAIL    defaults to <user>@<hostname>.local
+#   MIOS_FORGE_ADMIN_PASSWORD if empty, a 24-byte URL-safe random
+#                             password is generated and written to
+#                             /etc/mios/forge/admin-password (root-owned,
+#                             mode 0600); operator reads it once and
+#                             changes it via the web UI on first login.
+#
+# Idempotent: marks completion via /var/lib/mios/forge/.firstboot-done
+# and short-circuits on every subsequent boot. To re-trigger (e.g. after
+# wiping the SQLite DB), delete that sentinel file and restart the
+# mios-forge-firstboot.service.
+
+set -euo pipefail
+
+SENTINEL=/var/lib/mios/forge/.firstboot-done
+ENV_FILE=/etc/mios/install.env
+PASSWORD_FILE=/etc/mios/forge/admin-password
+
+_log() {
+    logger -t mios-forge-firstboot "$*" 2>/dev/null || true
+    echo "[forge-firstboot] $*" >&2
+}
+
+if [[ -f "$SENTINEL" ]]; then
+    _log "sentinel present, nothing to do"
+    exit 0
+fi
+
+# Source install.env if present; tolerate absence (operator may run this
+# script manually with env-vars set inline).
+if [[ -r "$ENV_FILE" ]]; then
+    # shellcheck source=/dev/null
+    set -a; source "$ENV_FILE"; set +a
+fi
+
+# Resolution: explicit MIOS_FORGE_* wins; otherwise fall back to the
+# linux user identity that bootstrap captured. Final fallback to 'mios'.
+admin_user="${MIOS_FORGE_ADMIN_USER:-${MIOS_LINUX_USER:-${MIOS_USER:-mios}}}"
+admin_host="${MIOS_HOSTNAME:-mios}"
+admin_email="${MIOS_FORGE_ADMIN_EMAIL:-${admin_user}@${admin_host}.local}"
+admin_password="${MIOS_FORGE_ADMIN_PASSWORD:-}"
+
+# Wait for mios-forge to come up. The Quadlet sets TimeoutStartSec=300s;
+# we mirror that ceiling. Forgejo's HTTP listener is the canonical
+# readiness probe.
+http_port="${MIOS_FORGE_HTTP_PORT:-3000}"
+deadline=$(( $(date +%s) + 300 ))
+while (( $(date +%s) < deadline )); do
+    if curl -fsS -o /dev/null "http://localhost:${http_port}/api/v1/version"; then
+        _log "Forgejo is up on :${http_port}"
+        break
+    fi
+    sleep 2
+done
+
+if ! curl -fsS -o /dev/null "http://localhost:${http_port}/api/v1/version"; then
+    _log "ERROR: Forgejo did not become ready within 300s; aborting"
+    exit 1
+fi
+
+# Generate a password if none was supplied. 24 bytes -> 32 base64 chars.
+if [[ -z "$admin_password" ]]; then
+    admin_password="$(openssl rand -base64 24 | tr -d '\n')"
+    install -d -m 0750 -o root -g mios-forge /etc/mios/forge
+    umask 077
+    printf '%s\n' "$admin_password" > "$PASSWORD_FILE"
+    chmod 0600 "$PASSWORD_FILE"
+    chown root:root "$PASSWORD_FILE"
+    _log "generated initial admin password; wrote $PASSWORD_FILE (mode 0600, root-only)"
+fi
+
+# Create the admin via the in-container forgejo CLI. Idempotency: if the
+# user already exists (e.g. someone created one via the web UI before
+# this service ran), 'forgejo admin user create' returns non-zero and
+# we accept that as a soft success.
+if podman exec --user mios-forge mios-forge \
+        forgejo --config /data/gitea/conf/app.ini admin user create \
+        --admin --must-change-password=true \
+        --username "$admin_user" \
+        --email "$admin_email" \
+        --password "$admin_password" 2>&1 | tee -a /var/log/mios/forge/firstboot.log; then
+    _log "admin user '${admin_user}' (${admin_email}) created"
+else
+    rc=$?
+    _log "admin create returned ${rc}; treating as 'already exists' (set MIOS_FORGE_FORCE_FIRSTBOOT=1 to override)"
+    if [[ "${MIOS_FORGE_FORCE_FIRSTBOOT:-}" == "1" ]]; then
+        exit "$rc"
+    fi
+fi
+
+install -d -m 0755 -o root -g root "$(dirname "$SENTINEL")"
+date -u +%FT%TZ > "$SENTINEL"
+chmod 0644 "$SENTINEL"
+_log "firstboot complete; sentinel at $SENTINEL"
+
+# One-line operator hint, dropped into the system journal.
+_log "Forgejo URL: http://localhost:${http_port}/"
+_log "Admin user:  ${admin_user}"
+_log "Admin email: ${admin_email}"
+if [[ -f "$PASSWORD_FILE" ]]; then
+    _log "Initial password: 'sudo cat ${PASSWORD_FILE}' (must change on first login)"
+fi
+
+exit 0