# Operations [Project overview](../README.md) | [Configuration](configuration.md) | [Payment API](payment-api.md) ## Build and run Run from the repository root on Windows with Go 1.23.2 or newer and access to the private Gitea modules. The entry point is `cmd/hardlink`, not the repository root. ```powershell go build -mod=readonly -o hardlink.exe ./cmd/hardlink go build -mod=readonly -o hardlink-preauth-release/preauth-release.exe ./hardlink-preauth-release ./hardlink.exe ``` `preauth-release.exe` is a separate task for releasing due CreditCall preauthorizations; the HTTP service does not run it automatically. Start Hardlink with the deployment directory as its working directory: ```text hardlink/ hardlink.exe config.yml TicketLayout.xml ChipDNAClient/ # Required for CreditCall ChipDnaClient.exe ... SDK dependencies and terminal configuration hardlink-preauth-release/ preauth-release.exe config.yml # Configuration for the separate release task logs/ ``` `config.yml` and the ChipDNA executable path are relative to the working directory. `TicketLayout.xml` is loaded beside the Hardlink executable. Configure the release task's working directory to contain its own `config.yml`. The HTTP server binds to `:` on all interfaces; the default port is `9091`. See [configuration](configuration.md) for local settings, the CMS payment field mapping and the room-ticket layout. ## Door cards `POST /issuedoorcard` accepts `Content-Type: application/json`: ```json { "roomField": "101", "checkinTime": "2026-10-23 15:00:00 +0100", "checkoutTime": "2026-10-24 11:00:00 +0100", "followStr": "0" } ``` Times use `2006-01-02 15:04:05 -0700`. Success returns: ```json {"code":200,"message":"Card issued successfully"} ``` Errors use the same `code`/`message` JSON structure with an HTTP error status. Exact physical empty (`0x38`) during preparation returns `503`; preparation exhaustion and encoding errors return `502`. The complete [K720 issuance contract](hardware/k720.md) covers worker ownership, preparation, uncertain-handoff recovery, delivery clearance, cancellation and idle maintenance. It includes the single `LockSequence`, shared three-shake budget, log-only delivery errors and best-effort next-card prestaging rules. Concurrent recovery with the actual dispenser and lock server still requires controlled physical validation. ## Room tickets `POST /printroomticket` accepts `Content-Type: application/xml`: ```xml John Doe 24/10/2026 11:00 am 103 map.png Follow the corridor... ``` Success returns HTTP `200` with: ```json {"code":200,"message":"Print job sent successfully"} ``` The printer package loads the ticket layout, renders ESC/POS text and raster images, and sends the output to the configured Windows printer. ## Additional endpoints | Endpoint | Purpose | | --- | --- | | `GET /dispenserstatus` | Cached stock/status in a `code`/`message` JSON response | | `POST /testissuedoorcard` | Operational diagnostic, available regardless of TestMode: encode and retain the card inside the dispenser; no guest delivery | | `GET /ping-pdq` | Read ChipDNA terminal status | | `POST /logerror` | Receive ChipDNA error notifications | `/testissuedoorcard` is an operational hardware diagnostic available regardless of TestMode. It prepares and encodes a card without FC0 guest delivery; the card remains inside the dispenser for reuse. Its registration and hardware sequence are separate from normal issuance and are not restricted to development kiosks. ## Native-only endpoint cleanup The modern `/api/payment/sale`, `/api/payment/preauth`, `/issuedoorcard` and `/printroomticket` endpoints serve native Fyne HTTP clients. They no longer emit browser CORS headers or accept OPTIONS preflight requests; non-POST methods receive the existing method-rejection format. Successful POST payloads, responses, payment execution and hardware sequences are unchanged. Keycard requests need only `roomField`, `checkinTime`, `checkoutTime` and `followStr`. `/dispenserstatus` and `/ping-pdq` are GET diagnostics (other methods return 405 with `Allow: GET`). The ChipDNA sidecar's asynchronous POST `/logerror`, error notifications and availability debounce remain operational. Background dispenser polling is unchanged. `/testissuedoorcard` is unconditionally registered on production kiosks and retains its encoded card for reuse. No TestMode gate or automatic ejection has been added. The deprecated XML `/takepayment` and `/takepreauth` handlers and their required response/redirect helpers remain for their explicitly retained contract. Do not remove the active sidecar or printer/lock-server protocols as browser legacy. ## Logging JSON logs are written to `/hardlink.log`. Weekly rotation uses local Monday midnight and retains `hardlink.1.log` through `hardlink.13.log`. The separate release task writes `preauth-release.log` with the same rotation policy. K720 logs include uncertain handoff, raw AP status/classification, RS/FC7 attempts, remaining shake budget, recovery stop reason and encoding duration. PREAUTH logs include processor result/type, transaction reference, approval/persistence decision, missing fields, and SQL/spool outcomes without card or receipt payloads. ## Verification Use repository-local build and temporary caches from PowerShell: ```powershell New-Item -ItemType Directory -Force .cache/go-build, .cache/tmp | Out-Null $env:GOCACHE = Join-Path $PWD '.cache/go-build' $env:GOTMPDIR = Join-Path $PWD '.cache/tmp' $env:TEMP = $env:GOTMPDIR $env:TMP = $env:GOTMPDIR go test -mod=readonly -count=1 ./internal/dispenser ./internal/handlers go test -mod=readonly -race -count=1 ./internal/dispenser ./internal/handlers go test -mod=readonly -count=1 -skip '^Test_SendMail$' ./... go vet -mod=readonly ./... go build -mod=readonly ./... git diff --check ``` `Test_SendMail` sends real email and is excluded from offline verification. Automated tests do not replace physical dispenser, encoder, terminal or printer validation. The existing `run_tests.sh` is not an offline verification entry point: it runs `go mod tidy` and unfiltered full tests, including the live-email test. Use the explicit commands above instead. Do not launch the service against hotel configuration as part of offline validation. ## Deployment Production deployment uses Salt. Build the intended revision and deploy the versioned Windows package through the Salt repository and Hardlink pillar. Where installed, local release tooling is invoked as `bash ./winbuild.sh ` from the `development` branch. It builds Hardlink and the release task, packages the existing `ChipDNAClient/` directory into `hardlink_windows_.zip`, and copies it to `salt/hardlink/files`. It also checks out/pulls the Salt and pillar repositories and commits/pushes the package in Salt; it does not create a Git tag. Ensure `ChipDNAClient/` contains the intended build before packaging. Update `pillar/hardlink/init.sls` to select the package version, then apply the Hardlink state to the intended hosts: ```bash salt '' state.apply hardlink ``` ## Coordinated application releases Deploy compatible ChipDNAClientCLI, Hardlink and native Fyne versions together. The module path is `gitea.futuresens.co.uk/futuresens/hardlink/v2`; internal and public package imports include `/v2`. The application `buildVersion` does not publish a module tag automatically. The owner must commit and publish the intended v2 release before the Fyne applications pin its actual tag with `go get` and regenerate sums with `go mod tidy`. Until publication, their zero pseudo-version marker is local-only and resolves through ignored alternate modfiles replacing the `/v2` module with the sibling checkout. Do not commit that replacement or invent remote checksums. The existing Fyne/CMS/translate dependency replacements are independent. Hardlink itself builds and tests from this checkout using its tracked module files. Release history is recorded in [releases](releases.md).