Sixth pass

docs/gitea-runner.md

@@ -1,7 +1,7 @@
 # Gitea Actions Runner Configuration for j3270
 
 This repository includes Gitea Actions workflows in `.gitea/workflows/build.yaml` to automatically:
-1. Compile and run unit tests.
+1. Compile and run the JUnit 5 test suite via `test_all.sh`.
 2. Build the standalone `j3270.jar` executable via `build_all.sh`.
 3. Upload `j3270.jar` as a downloadable artifact.
 4. Report test results and diagnostics.
@@ -12,23 +12,42 @@ This repository includes Gitea Actions workflows in `.gitea/workflows/build.yaml
 
 To run CI workflows on your Gitea instance:
 
-### Step 1: Download `act_runner`
+### Step 1: Download & Generate Config
 Download the `act_runner` binary for your platform from the [Gitea act_runner releases](https://gitea.com/gitea/act_runner/releases).
 
-### Step 2: Register the Runner
+Generate a default runner config file:
-Obtain a runner registration token from **Repository Settings -> Actions -> Runners** or **Admin -> Actions -> Runners**, then register:
+```bash
+./act_runner generate-config > config.yaml
+```
+
+### Step 2: Configure Network & DNS in `config.yaml`
+If your Gitea instance is hosted on a custom or internal domain (e.g., `git.hugfreevikings.wtf`), configure the container network mode or DNS resolution in `config.yaml`:
+
+```yaml
+container:
+  # Option A (Recommended): Use host network mode so job containers share the host's DNS and network:
+  network: "host"
+
+  # Option B (Bridge mode): If using bridge network, add extra host mapping:
+  extra_hosts:
+    - "git.hugfreevikings.wtf:host-gateway"
+```
+
+### Step 3: Register the Runner
+Obtain a runner registration token from **Repository Settings -> Actions -> Runners** or **Site Administration -> Actions -> Runners**, then register:
 
 ```bash
 ./act_runner register \
-  --instance https://your-gitea-instance.com \
+  --config config.yaml \
+  --instance https://git.hugfreevikings.wtf \
   --token <YOUR_REGISTRATION_TOKEN> \
   --name "j3270-runner" \
   --labels "ubuntu-latest:docker://node:18-bullseye,ubuntu-22.04:docker://node:18-bullseye"
 ```
 
-### Step 3: Run the Runner Daemon
+### Step 4: Run the Runner Daemon
 ```bash
-./act_runner daemon
+./act_runner daemon --config config.yaml
 ```
 
 Or using Docker Compose:
@@ -39,21 +58,52 @@ services:
     image: gitea/act_runner:latest
     restart: always
     environment:
-      - GITEA_INSTANCE_URL=https://your-gitea-instance.com
+      - GITEA_INSTANCE_URL=https://git.hugfreevikings.wtf
       - GITEA_RUNNER_REGISTRATION_TOKEN=<YOUR_REGISTRATION_TOKEN>
       - GITEA_RUNNER_NAME=j3270-runner
       - GITEA_RUNNER_LABELS=ubuntu-latest:docker://node:18-bullseye
+    extra_hosts:
+      - "git.hugfreevikings.wtf:host-gateway"
     volumes:
       - /var/run/docker.sock:/var/run/docker.sock
       - ./data:/data
+      - ./config.yaml:/config.yaml
 ```
 
 ---
 
-## 2. CI/CD Workflow Summary
+## 2. Troubleshooting "Could not resolve host"
 
-- **Trigger**: Pushes to `master`/`main`/`develop`, pull requests, and manual triggers via `workflow_dispatch`.
+If job containers fail during checkout with:
-- **Artifacts**:
+```
-  - `j3270-executable-jar`: Ready-to-run desktop terminal emulator jar (`java -jar j3270.jar`).
+fatal: unable to access 'https://git.hugfreevikings.wtf/...': Could not resolve host: git.hugfreevikings.wtf
-  - `test-reports`: Full JUnit test reports and XML/HTML summaries.
+```
-- **Reporting**: On failure, automated diagnostic reports are generated and attached to the run summary.
+This means Docker's bridge network inside the runner container cannot resolve the host domain.
+
+**Fix**:
+1. Edit `config.yaml` on the runner machine and set `network: "host"` under `container:`:
+   ```yaml
+   container:
+     network: "host"
+   ```
+2. Restart the `act_runner` daemon:
+   ```bash
+   ./act_runner daemon --config config.yaml
+   ```
+
+---
+
+## 3. Local Build & Test Verification
+
+You can verify the entire build and test suite locally at any time without external tools:
+
+```bash
+# Compile and run all 25 unit tests (130ms):
+sh ./test_all.sh
+
+# Build executable standalone JAR:
+sh ./build_all.sh
+
+# Run the emulator:
+sh ./run.sh
+```