chore: bootstrap lean sysadmin-chronicles repo
Import the runnable game code, content, docs, scripts, and repo guidance while leaving local agent state, dependency installs, build output, and backup copies out of the published tree.
This commit is contained in:
@@ -0,0 +1,103 @@
|
||||
# SYSADMIN CHRONICLES — SNAPSHOT CHAIN
|
||||
> Version 1.0
|
||||
>
|
||||
> This document defines what each named baseline snapshot represents,
|
||||
> how the snapshot chain is built, and what assumptions quest authors
|
||||
> can make about VM state at each snapshot.
|
||||
|
||||
---
|
||||
|
||||
## POLICY
|
||||
|
||||
Each `baseline.post-qXXX` snapshot represents the **canonical clean-branch
|
||||
outcome** of quest QXXX — meaning all prior quests were resolved via their
|
||||
highest-priority (best) solution branch.
|
||||
|
||||
Player state diverges from the baseline during play. The baseline is always
|
||||
the authored "good state" for that point in the arc, built independently of
|
||||
any player's actual save.
|
||||
|
||||
**A baseline snapshot is never built from a bad or partial branch outcome.**
|
||||
If a player took the wrong branch, their VM state differs from the baseline
|
||||
for all subsequent quests. That divergence is intentional and is the game.
|
||||
|
||||
---
|
||||
|
||||
## SNAPSHOT CHAIN TABLE
|
||||
|
||||
| Snapshot Name | VM(s) | Built After | Represents |
|
||||
|---------------|-------|-------------|------------|
|
||||
| `baseline.day-one` | workstation | fresh image | Brand new ares workstation. No player account SSH key. Provisioning script ran but authorized_keys absent. |
|
||||
| `baseline.clean` | web_server | fresh image | Fresh hermes. nginx installed, no config errors, logrotate present, web root owned by www-data. Ready for Q002 to break it. |
|
||||
| `baseline.clean` | build_machine | fresh image | Fresh vulcan. NTP disabled (for Q006 scenario). Arch base install, pacman configured to use internal repo. |
|
||||
| `baseline.post-q001` | workstation | Q001 clean branch | Player SSH key in authorized_keys with correct permissions (0600 file, 0700 dir). Used as the implied state for all subsequent quests requiring SSH access. Not an explicit snapshot — workstation just stays live from Q001 onward. |
|
||||
| `baseline.post-q004` | web_server | Q004 clean branch | hermes with: nginx stable+enabled, logrotate configured, web root owned by www-data recursively. All of Q002–Q004 resolved cleanly. Used as starting state for Q005 and Q007. |
|
||||
| `baseline.post-q006` | build_machine | Q006 clean branch | vulcan with NTP enabled and healthy, archlinux-keyring refreshed, builds working. Used as starting state for Q008. |
|
||||
|
||||
---
|
||||
|
||||
## HOW SNAPSHOTS ARE BUILT
|
||||
|
||||
Snapshots are produced by `tools/vm/seed-vms.sh` in sequence:
|
||||
|
||||
```
|
||||
1. Build base VM images from cloud-init or preseed
|
||||
2. Run base configuration (hostname, users, packages, game helpers)
|
||||
3. Run suppress-maintenance-noise.sh
|
||||
4. Take baseline.clean snapshot
|
||||
5. Run Q001-prep.sh → take no snapshot (workstation stays live)
|
||||
6. Run Q002-prep.sh through Q004-prep.sh sequentially on web_server
|
||||
7. Apply clean-branch outcome state manually or via a post-quest-state script
|
||||
8. Take baseline.post-q004 snapshot on web_server
|
||||
9. Run Q006-prep.sh on build_machine
|
||||
10. Apply clean-branch outcome state on build_machine
|
||||
11. Take baseline.post-q006 snapshot on build_machine
|
||||
```
|
||||
|
||||
Step 7 and 10 ("apply clean-branch outcome state") are done via dedicated
|
||||
scripts in `tools/vm/quest-prep/`:
|
||||
|
||||
```
|
||||
Q004-post-clean.sh — sets web root ownership, confirms logrotate, enables nginx
|
||||
Q006-post-clean.sh — enables systemd-timesyncd, refreshes archlinux-keyring
|
||||
```
|
||||
|
||||
These post-clean scripts are the authoritative definition of what "clean
|
||||
branch" means for snapshot purposes.
|
||||
|
||||
---
|
||||
|
||||
## WHAT QUEST AUTHORS CAN ASSUME
|
||||
|
||||
When authoring a quest against `baseline.post-q004`, you can assume:
|
||||
- nginx is active and enabled on hermes
|
||||
- /etc/logrotate.d/nginx exists and is correct
|
||||
- /var/www/axiomworks is owned by www-data recursively
|
||||
- The deploy service runs as www-data and can write to /var/www/axiomworks
|
||||
- No Q002/Q003/Q004 broken state exists
|
||||
- Q005 and Q007 both build on this clean hermes state
|
||||
|
||||
When authoring a quest against `baseline.post-q006`, you can assume:
|
||||
- Everything in post-q004 (hermes state)
|
||||
- systemd-timesyncd is active and enabled on vulcan
|
||||
- archlinux-keyring is up to date
|
||||
- pacman -Syu works without signature errors
|
||||
- Q008 uses this as its clean starting baseline
|
||||
|
||||
If your quest needs to break something that was fixed in a prior quest,
|
||||
your prep script must re-break it after the post-clean baseline is applied.
|
||||
Document this explicitly in your prep script's header comment.
|
||||
|
||||
---
|
||||
|
||||
## DEVELOPER RESET
|
||||
|
||||
To rebuild all baselines from scratch:
|
||||
|
||||
```bash
|
||||
bash tools/vm/snapshot-all.sh --revert-to baseline.clean
|
||||
bash tools/vm/seed-vms.sh
|
||||
```
|
||||
|
||||
This is destructive and should only be run during authoring or CI.
|
||||
It is not available in the shipped game.
|
||||
Reference in New Issue
Block a user