# Fleet User Standard PRD

**Status:** Draft — Pending Commander Bobby Review
**Author:** Artemis
**Date:** 2026-06-03

---

## 1. Purpose & Scope

This PRD defines the **canonical user account standard** for all Iron Legion fleet nodes. It eliminates UID/GID mismatches that cause permission failures in bind-mounted containers (VS Code: Server, Paperclip, etc.) and ensures every node behaves identically for automation.

**In scope:**
- Canonical user `jarvis` — UID/GID, groups, home directory
- Container `PUID`/`PGID` mapping rules
- Provisioning enforcement (MAAS autoinstall, Ansible, manual install)
- Migration path for non-compliant nodes (MK7, Nebuchadnezzar)

**Out of scope:**
- Service-specific runtime users inside containers
- TrueNAS / external appliance user models (already documented separately)

---

## 2. Success Criteria

| # | Criterion | How Verified |
|---|-----------|-------------|
| 1 | Every fleet node has `jarvis` at UID 1000 / GID 1000 | `id jarvis` returns `uid=1000` |
| 2 | No node has a competing UID 1000 user (e.g. "ubuntu") | `awk -F: '$3==1000 {print $1}' /etc/passwd` returns only "jarvis" |
| 3 | Container compose files use `PUID=1000` / `PGID=1000` without node-specific overrides | `grep -r 'PUID' /opt/iron-legion/docker-swarm/` |
| 4 | MAAS/cloud-init autoinstall scripts create jarvis FIRST at UID 1000 | Inspect autoinstall user-data |
| 5 | Nebuchadnezzar + MK7 migrated to compliant state | Re-run audit script |

---

## 3. The Standard

### 3.1 Canonical User: `jarvis`

```yaml
username: jarvis
uid: 1000
gid: 1000
home: /home/jarvis
shell: /bin/bash
groups: [sudo, docker]  # node-local groups added post-provision
ssh_key_source: ~/.ssh/artemis_key.pub  # deployed at provision time
```

### 3.2 Container Mapping Rule

All LinuxServer.io and similar images MUST use:
```yaml
environment:
  - PUID=1000
  - PGID=1000
```

**No exceptions.** If a node cannot satisfy this, the node is non-compliant and must be migrated — not the compose.

### 3.3 Provisioning Enforcement

| Provision Method | Enforcement |
|----------------|-------------|
| **Manual install** | `useradd -m -u 1000 -s /bin/bash jarvis` before any other human user |
| **MAAS autoinstall** | Subiquity `identity` section MUST target `jarvis:1000` **before** cloud-init creates "ubuntu" |
| **Ansible playbook** | `ansible.builtin.user:` with `uid: 1000`, `name: jarvis` |
| **Docker host (Nebuchadnezzar)** | Base image or `useradd` in Dockerfile prior to app user creation |

---

## 4. Fleet Audit Results (Current State)

| Node | jarvis UID | Competing UID 1000 | Status |
|------|-----------|-------------------|--------|
| artemis | 1000 | None | ✅ Compliant |
| mark44 | 1000 | None | ✅ Compliant |
| mark5 | 1000 | None | ✅ Compliant |
| mk42 | 1000 | None | ✅ Compliant |
| shield | 1000 | None | ✅ Compliant |
| igor | 1000 | None | ✅ Compliant |
| truenas | 1000 | None | ✅ Compliant |
| **mk7** | **1001** | **ubuntu 1000** | ⚠️ **Non-compliant** |
| **nebuchadnezzar** | **1002** | **ubuntu 1000, caddy 1001** | ⚠️ **Non-compliant** |

**Root cause:** MK7 and Nebuchadnezzar were provisioned via cloud-init/MAAS, which created "ubuntu" at UID 1000 before jarvis was added. All manually-built nodes are clean.

---

## 5. Remediation Plan

### 5.1 MK7
1. Remove or reassign `ubuntu` user (UID 1000 → 65534 or delete)
2. Change `jarvis` UID from 1001 → 1000
3. `chown -R jarvis:jarvis /home/jarvis`
4. Update VS Code: Server container ownership: `chown -R jarvis:jarvis /home/jarvis/.vscode-ssh`
5. Verify compose still works with `PUID=1000`

### 5.2 Nebuchadnezzar
1. Remove or reassign `ubuntu` user
2. Remove or reassign `caddy` user (or shift to UID > 2000)
3. Change `jarvis` UID from 1002 → 1000
4. `chown -R jarvis:jarvis /home/jarvis`
5. Audit any container bind mounts for ownership drift

---

## 6. Open Questions

1. **Should we document this in the MAAS curtin preseed** so new PXE-built nodes are auto-compliant?
2. **Should we add a fleet-wide Ansible user-enforcement task** that fails the playbook if UID 1000 ≠ jarvis?
3. **Is TrueNAS user model** (jarvis=1000, jumpbox=3000, bobby=3001) the exception we keep, or do we align TrueNAS too?

---

## 7. Gitea Branch Protection Setup (For Draft → Canon Workflow)

To enforce peer review for PRDs and all documentation:

1. **Gitea UI** → Iron-Legion/documentation → Settings → Branches → `main` → **Add Protection Rule**
2. Enable:
   - ✅ **Enable branch protection**
   - ✅ **Require pull request reviews** → Minimum approvers: **1**
   - ✅ **Dismiss stale approvals when new commits are pushed**
   - ✅ **Block merge if required reviewers not approved**
3. This forces every PR to have at least one human review before merge.

Once enabled:
- Draft PRDs go to `PRD Drafts/` via fork + PR
- Approved PRDs get moved to `PRDs/` (canonical) in the approval commit
- All operational docs follow the same fork → PR → review → merge flow