OUI Web UI

OUI_XFAB documentation

Releasing OUI

Before creating a tag

  1. Update package.json, package-lock.json, public/version.json, and the first entry of src/modules/version/model/versionNotes.ts to the same X.Y.Z version.
  2. Put the newest version-note entry first, include its releaseDate, keep newFeatures, bugFixes, and otherChanges present, and provide both en and de for every item.
  3. Run npm ci and npm ci --prefix services/oui-access-service.
  4. Run npm run validate:dependencies, npm run validate:env, and npm run validate:workflows.
  5. Run both root audits and both npm audit --prefix services/oui-access-service variants; all must report zero vulnerabilities.
  6. Run npm run lint, npm run type-check, npm run test:coverage, and npm run build.
  7. Run npm run test:e2e after installing Chromium with npm run test:e2e:install when needed.
  8. Run node scripts/validate-release.mjs vX.Y.Z.
  9. Commit the four version sources together.

These pre-tag checks are required because a published release tag is immutable. The release workflow checks out the tag's resolved commit and re-runs release metadata validation, lint, type-check, coverage, and the production build before packaging; it does not replace the pre-tag dependency audits or browser suites.

Production release

Create and push an annotated tag only after the release commit is on the intended branch:

git tag -a vX.Y.Z -m "Release vX.Y.Z"
git push origin vX.Y.Z

The tag starts Release Production; approval is required through the GitHub production environment.

The Windows/IIS ZIP includes the built application, web.config, and a self-contained oui-access-service/ directory with its production dependency graph. Production builds explicitly select VITE_WORKSTATION_IDENTITY_ENABLED=1 to report and bind workstation identity. Development and staging select 0 to omit that diagnostic integration; neither setting changes the command gates of connected transport, ready synchronization, EAP action state, and applicable authorization. Apply and verify EAPWebManager migrations 007, 008, 009, and 010, deploy explicit WorkstationAccessCheckEnabled = 0 or 1 under [Main config], and configure the restricted service environment. For a one-time explicitly chosen first administrator, stop the service, populate the deployed InitialAdmin* App.ini values, and start node .\oui-access-service\server.js. After the service creates that SQL administrator and exits, clear InitialAdminPassword, set InitialAdminBootstrapEnabled = 0, and restart it. With that temporary bootstrap disabled, an otherwise administrator-empty SQL database instead provisions the built-in admin account with source-defined OUIXFAB during normal service startup; change that account password after first sign-in. Then verify /healthz plus /readyz on 127.0.0.1:8010, one workstation ticket redemption, and the expected footer access state. IIS administrators must allow both HTTP_X_REAL_IP and HTTP_X_FORWARDED_PROTO, keep IIS as the direct peer, and require HTTPS; HTTP ticket/account routes are rejected by IIS and the service. The release does not install a Windows Service, assign credentials, expose port 8010, or configure process recovery; operations own supervision and secret storage.

Staging host deployment

GitHub-hosted runners build the short-lived staging artifact but cannot reach the private staging server. From a Windows workstation with SSH access and passwordless remote sudo, set the target outside Git and run:

$env:OUI_STAGING_SSH_TARGET = 'user@staging-host'
npm run deploy:staging

For a one-off target override, run npm run deploy:staging -- -SshTarget user@staging-host. The command requires a clean working tree and records the package version, Git commit, and UTC timestamp in an immutable release directory. It runs the repository gates, builds in staging mode, verifies nginx and the EAP backend, atomically updates /var/www/oui, and verifies HTTP plus direct and proxied WebSocket behavior. If verification fails after activation, it restores the previous symlink. It does not restart the EAP backend or delete prior releases.

Tag immutability protection

Repository administrators must configure a GitHub tag ruleset targeting v* that prevents tag updates and deletions. Do not grant routine bypass access for those restrictions. The release workflow resolves the requested tag to a commit before production approval, checks out that exact SHA, and verifies the tag still resolves to the same SHA immediately before publication. This verification narrows the race window, but the repository ruleset is required to make release tags immutable.

Manual recovery

Dispatch Release Production with the existing immutable vX.Y.Z tag. Never delete, recreate, or force-move a published version tag. If metadata is wrong, fix it in a new version and create a new tag.

Artifact retention

Testing and staging Actions artifacts expire after 3 days. Production ZIP files, proxy configs, and their .sha256 checksum files live only on the GitHub Release. If Actions reports a quota error, delete expired or obsolete non-production artifacts in repository Actions settings; do not remove published release assets.