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.

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).

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 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:

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:

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:

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

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.

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.

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:

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:

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:

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):

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:

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.