smartpark-app/docs/CH3-HANDOFF.md

# SmartPark Chapter 3: local preparation and Gitea handoff

Prepared October 9, 2026. This kit is a draft implementation, not proof that
Gitea Actions is working. The original documentation was reported to compile
successfully in Vincent's Ubuntu VM. The new build script and edited manual
must be tested there. Registration, checkout in Actions, metadata, artifact
upload, retention, and required demonstrations remain pending.

## 1. Apply to Vincent's clean feature branch

Copy this ZIP into Ubuntu's Downloads folder and extract it there. The folder
must contain apply_to_repo.py and payload/. Hidden .gitea files are included
by the installer; do not copy the payload manually.

```bash
cd ~/smartpark-ch3-work/smartpark-app
python3 ~/Downloads/smartpark-ch3-kit/apply_to_repo.py "$PWD"
git diff --stat
git status --short
python3 ci/build_manual.py
```

The installer expects branch chapter3-build-automation, a clean checkout,
and the original version 1.8 source. It refuses changed layouts or existing
target files rather than overwriting them. If it refuses, preserve your work
and inspect the message. It is intended to run once.

Open build/manual/SmartPark-Manual.pdf. Check the new build identification
page, all original chapters, the new eight-section chapter, references,
glossary and index. A first local build should say local and dirty because
your new edits are not committed. It must not show a fabricated Actions run.
The new chapter number follows the existing manual; it addresses assignment
Chapter 3 even if it becomes Chapter 7 in your team's document.

The script removes only its two fixed prior deliverables and builds in a
fresh temporary directory. TeX failures return nonzero, leaving no prior
successful PDF in the publish directory. Console output includes the error;
temporary TeX files are removed after the attempt. Preserve terminal output
if troubleshooting is needed. Do not fix an error by ignoring its exit code.

## 2. Commit locally

Review all new files, including the workflow, before committing. If Git asks
for your identity, set your real name and your chosen Git commit email with
git config user.name and git config user.email (repository-local settings).

```bash
git diff --check
git add .gitignore .gitea/workflows/manual.yml ci docs/ch3-evidence.md docs/CH3-HANDOFF.md latex-manual/devopsAssignment.tex latex-manual/devopsDocumentHistory.tex latex-manual/devopsAutomatedManualBuild.tex
git commit -m "Prepare automated manual build and Chapter 3 draft"
python3 ci/build_manual.py
git status --short
```

After committing, the local PDF should identify that commit without dirty.
git status should be empty. The PDF remains local evidence only.
If using a log with tee, preserve failures with `set -o pipefail` first.

## 3. Prepare a runner (optional now; can be done by Nica later)

This installer targets only the dedicated Ubuntu x86_64 VM. It does not
configure the shared DigitalOcean Droplet. It downloads Node 22 from the
official release server, verifies its listed checksum, and records its exact
version in terminal output. It installs Gitea Runner 2.3.0 with its official
checksum. It creates an unprivileged service account, host-mode label
smartpark-latex:host, capacity one, and a system service. It neither registers
nor starts the runner. Node remains at /opt/smartpark-node/bin/node, not on
your normal user's PATH; the service PATH includes it.

Read ci/setup_runner.sh, then run:

```bash
bash ci/setup_runner.sh
df -h /
```

No Docker, exposed runner port, or Droplet login is needed. If setup fails,
stop at the actual error. It deliberately refuses to replace existing
accounts/configurations, so a partial installation must be inspected before
retrying. Do not blindly delete an existing service account or registration.

The source build tools installed by Vincent are:

```bash
sudo apt-get update
sudo apt-get install --no-install-recommends git python3 latexmk texlive-latex-extra texlive-fonts-recommended lmodern python3-pygments
```

Nica needs those packages if reproducing on her own dedicated Ubuntu host.
Record the actual installed package versions from build-info.txt. A fresh
apt installation may differ from Vincent's; rebuild and verify accordingly.

## 4. Registration: only after authorized Gitea admin help

Have the repository administrator confirm Actions is enabled and provide a
new repository-scoped registration token securely, or assist interactively.
Do not use a personal access token in place of a runner registration token.
Do not share the old Droplet's .runner identity. Registration is performed
on the machine that will execute jobs, with its own new identity.

Run in the Ubuntu VM:

```bash
sudo -u smartpark-runner sh -c 'umask 077; cd /var/lib/smartpark-runner && /usr/local/bin/gitea-runner --config /etc/smartpark-runner/config.yaml register'
```

Interactive answers:

- Instance URL: https://git.137-184-97-250.nip.io (not the repository URL).
- Token: enter it privately at the prompt; do not include it in screenshots.
- Name: vincent-ubuntu-manual (or the actual replacement owner's name).
- Labels: smartpark-latex:host. The supplied config already specifies it.

After successful registration:

```bash
sudo chmod 600 /var/lib/smartpark-runner/.runner
sudo systemctl enable --now smartpark-runner
sudo systemctl status smartpark-runner --no-pager
```

The administrator should confirm the runner appears online and is scoped to
smartpark-app. Review all workflows that may target this runner: push-only
triggers in this file do not prevent another workflow from using its label.
Host-mode jobs are not mutually isolated and can read the service account's
runner identity. Restrict workflow authors to trusted teammates. The service
account has no sudo or Docker group. Do not grant either just to fix a build.

NoNewPrivileges and other service restrictions help limit the account but
are not a sandbox against hostile jobs. Use a dedicated VM without personal
shared folders/keys. Workflow job tokens also require suitable permissions.

## 5. Push the prepared branch

```bash
cd ~/smartpark-ch3-work/smartpark-app
git push -u origin chapter3-build-automation
```

This requires branch write access, not repository Settings access. If denied,
use the handoff in section 9. If a push happened while Actions was disabled,
make a real source correction and push again once enabled. A push-triggered
build is the required evidence, not merely pressing a rerun button.

The workflow must be present on the branch that receives the push. If the
Actions page opens on main, select the branch/run list for your feature
branch. Do not assume an empty main view proves feature workflows are absent.
PR #8 does not have to be merged first. Coordinate eventual merge order so
the documentation and automation are both retained.

In the Actions run, verify checkout SHA, successful compile, and successful
artifact upload. Download the artifact, extract its PDF, and inspect the
visible run number and short SHA against the run and commit. The workflow
requests 30-day retention; ask the administrator what was actually applied.
If upload fails, the assignment is not complete even if the compile is green.

The workflow records checkout v4.2.2 and upload-artifact v3.1.3 as exact tags.
Tags are not immutable commit-SHA pins. The upload action uses the legacy
artifact protocol; its compatibility with this server still needs an actual
test. Do not change blindly to GitHub upload-artifact v4 to fix an error:
check the server's supported protocol/action and preserve the failure log.

## 6. Required success, failure and repair sequence

Use only the dedicated test branch. Start with a clean working tree and a
committed successful preparation. The following changes are intentional,
reviewable source changes. Record each run BEFORE the next push.

```bash
git switch -c chapter3-build-test
printf '\nFirst automated source-change demonstration.\\par\n' >> latex-manual/devopsAutomatedManualBuild.tex
git add latex-manual/devopsAutomatedManualBuild.tex
git commit -m "Document first manual build demonstration"
git push -u origin chapter3-build-test
```

Wait for success. Download PDF #1 and record the commit/run/version/artifact.

```bash
printf '\nSecond automated source-change demonstration.\\par\n' >> latex-manual/devopsAutomatedManualBuild.tex
git add latex-manual/devopsAutomatedManualBuild.tex
git commit -m "Document second manual build demonstration"
git push
```

Wait for success. Download PDF #2 and record matching evidence. Now create
the controlled error on this test branch:

```bash
printf '\n\\SmartParkIntentionalBuildFailure\n' >> latex-manual/devopsAutomatedManualBuild.tex
git add latex-manual/devopsAutomatedManualBuild.tex
git commit -m "Demonstrate controlled LaTeX compilation failure"
git push
```

Wait for the failed compile, preserve the error/run/commit and confirm the
upload step did not publish a successful PDF. Then repair by reverting only
that latest failure commit. Run the following ONLY while that failure commit
is still HEAD and the working tree is clean:

```bash
git log -1 --oneline
git status --short
git revert --no-edit HEAD
git push
```

Capture the repaired successful run and PDF. Fill docs/ch3-evidence.md with
real results and transfer them into the manual chapter. Replace demonstration
sentences with the actual findings in a later editorial commit.

## 7. Complete the manual

The eight sections are skeletons. Keep earlier chapters and fill actual
runner, network and security details, source/run/artifact links, dated
screenshots, expected/actual outcomes, and failed-build troubleshooting.
Update Hosts and Passwords-hints tables and explicitly record their changes.
Review document version, date, title and assignment number (the older title
and assignment number were deliberately preserved for team decision), add
bibliography/glossary entries, and log AI assistance per team conventions.
The added history row is a draft with human review pending.

Arrange peer review and merge through the normal process. Do not bypass
Jenkins required checks or branch protections. After integration into main,
confirm its push-triggered run and download the final artifact. Submit only
the PDF extracted from that successful Actions artifact, not this kit or a
local PDF. The source/script preparation alone is not submission-ready.

## 8. Availability and troubleshooting

- A user service terminal is not needed: systemd starts the runner when Ubuntu
  boots. The VM and Windows computer must still be awake and connected.
- Disable automatic suspend in Ubuntu's Power settings while running jobs;
  keep Windows awake during agreed build/grading periods. A laptop is not
  an always-on server unless you actually keep it available.
- Reboot the VM after initial success, check service status and online state,
  and push a harmless source correction to verify recovery.
- Queued: check online status, repository scope and exact smartpark-latex label.
- Checkout: check network/TLS and job-token repository permissions. Do not
  disable certificate checks or insert a personal token into the workflow.
- JavaScript/action error: confirm the service's /opt/smartpark-node/bin/node
  exists; inspect the action's compatibility and runner logs.
- TeX: fix the first real error. Undefined references may be inherited source
  problems; resolve them rather than remove the quality check.
- Artifact: inspect the separate upload step, server protocol and access.
- Logs: sudo journalctl -u smartpark-runner -n 80 --no-pager (review/redact
  before sharing). Never dump all environment variables or the .runner file.
- Stop: sudo systemctl stop smartpark-runner. Retire: disable service and ask
  an administrator to remove the registration; never send identity files.

## 9. Handoff to Nica if access is unavailable

Commit the prepared files before packaging. Use the branch containing the
latest completed, repaired work. This archives tracked source only and
excludes runner credentials, build output and your Git login settings:

```bash
git status --short
git log -1 --oneline
git archive --format=zip --output="$HOME/Downloads/smartpark-ch3-source-handoff.zip" HEAD
```

Also create a Git bundle of the current branch so Nica can retain commit
identity (the build script requires a Git checkout):

```bash
git bundle create "$HOME/Downloads/smartpark-ch3.git.bundle" HEAD
git bundle verify "$HOME/Downloads/smartpark-ch3.git.bundle"
```

Send that ZIP and Git bundle plus a short factual status: commit ID, actual local test
result, who will host the runner, what needs registration, and which Gitea
checks remain pending. The ZIP includes docs/CH3-HANDOFF.md and the evidence
worksheet. If Nica will host it, she follows the same setup and registers a
new identity on her host; do not copy /var/lib/smartpark-runner/.runner.
If branch access works, prefer a pushed branch and PR link for review.

If Nica receives only these files, she can start a NEW checkout (destination
must not already exist) from the bundle without depending on your laptop:

```bash
git clone ~/Downloads/smartpark-ch3.git.bundle ~/smartpark-ch3-takeover
cd ~/smartpark-ch3-takeover
git switch -c chapter3-nica-takeover
git remote set-url origin https://git.137-184-97-250.nip.io/stevens-smartpark/smartpark-app.git
```

This already includes the applied changes; do not run the kit installer again.
She must add chapter3-nica-takeover to the workflow's push branch list if
testing pushes on that branch. She should inspect the bundle/source contents
before running scripts. The source ZIP is for browsing/import only; a plain
unpacked ZIP does not provide the Git commit information the build requires.

## Official references and verification limits

- https://docs.gitea.com/runner/2/installation/binary/
- https://docs.gitea.com/runner/2/registration/
- https://docs.gitea.com/runner/2/labels/
- https://docs.gitea.com/usage/actions/artifacts/
- https://nodejs.org/dist/latest-v22.x/

The local Ubuntu VM is separate from the assistant's Windows workspace.
This kit was prepared there; actual TeX compilation, Linux installation,
service operation and Gitea behavior must be verified in the real environment.