Wise Foundry Alloy is the central manager of Wise Foundry: one place to enroll and operate many Wise Foundry Iron hosts, with its own services running as containers on Wise Foundry Steel.
  • TypeScript 87.4%
  • Shell 9.7%
  • JavaScript 0.9%
  • PLpgSQL 0.5%
  • Makefile 0.5%
  • Other 1%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
Michael J. Manley 8b045296f8 Ignore .DS_Store
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-17 10:40:29 -08:00
api API: DELETE /jobs clears finished tasks 2026-11-16 23:33:55 -08:00
db Host management, inventory, tasks and events, secrets and upgrades for CTP 2026-09-26 20:45:48 -07:00
deploy Forget deleted workloads, Sites and Hosts, discard saved state, menus 2026-11-01 18:29:09 -08:00
docs docs: cluster network and router settings edited in place 2026-11-17 00:34:19 -08:00
locales/en web: a welcome page with the downloads and a datastore browser; fix nginx 2026-11-16 15:40:59 -08:00
scripts web: a welcome page with the downloads and a datastore browser; fix nginx 2026-11-16 15:40:59 -08:00
sdk Remove the web console for the Wise Foundry Client 2026-11-15 23:16:17 -08:00
test Remove the web console from the docs and the build 2026-11-16 12:43:45 -08:00
web web: a welcome page with the downloads and a datastore browser; fix nginx 2026-11-16 15:40:59 -08:00
.containerignore Updates by build, a deployed signing key, Iron-style builds 2026-09-15 23:19:52 -07:00
.env.example Installer ISO with Install, Upgrade and Restore; images carried once, in the pack; port 443 2026-09-27 18:04:09 -07:00
.gitignore Ignore .DS_Store 2026-11-17 10:40:29 -08:00
alloy-icon.png Version by build date, use Alloy's icon, show Iron's VLAN trunks 2026-09-24 08:23:46 -07:00
alloy-product-logo-white.png Version by build date, use Alloy's icon, show Iron's VLAN trunks 2026-09-24 08:23:46 -07:00
alloy-product-logo.png Version by build date, use Alloy's icon, show Iron's VLAN trunks 2026-09-24 08:23:46 -07:00
CHANGELOG.md API: DELETE /jobs clears finished tasks 2026-11-16 23:33:55 -08:00
CLAUDE.md web: a welcome page with the downloads and a datastore browser; fix nginx 2026-11-16 15:40:59 -08:00
compose.yaml Wise Foundry Alloy 0.1.0 2026-09-15 22:32:11 -07:00
LICENSE.md Wise Foundry Alloy 0.1.0 2026-09-15 22:32:11 -07:00
Makefile Remove the web console from the docs and the build 2026-11-16 12:43:45 -08:00
NOTICE.md Identity: TOTP two-factor sign-in, OpenID Connect, LDAP, break-glass accounts 2026-09-27 21:23:57 -07:00
README.md web: a welcome page with the downloads and a datastore browser; fix nginx 2026-11-16 15:40:59 -08:00

Wise Foundry Alloy

Wise Foundry Alloy is the central manager of Wise Foundry: one place to enroll and operate many Wise Foundry Iron hosts, with its own services running as containers on Wise Foundry Steel.

This repository is currently a proof of concept that sets up the product's shape for the main project:

  • Three container images, each with its own Compose file: PostgreSQL (db/), the Node.js API and manager (api/), and nginx (web/), which terminates TLS, proxies the API and serves a welcome page, a datastore browser and the API reference at /api/docs. The root compose.yaml includes all three as one project.

  • Managed with the Wise Foundry Client: Alloy has no web console. Its GUI is the native desktop client in ../wxclient/ (wxclient/README.md), the same one that manages an Iron host directly; automation uses the API, the PowerShell module (../pwsh/) or alloyctl (docs/cli.md).

  • Sessions like Steel's: an HttpOnly session cookie, a CSRF header, login back-off, three roles and an audit log, stored in PostgreSQL.

  • An installer for Iron: an Electron wizard (deploy/) on one ISO — a Linux Electron in linux/, a Windows one in windows/, and the Steel OVA and update bundle and Alloy's images and pack in payload/ — that installs Alloy (imports Steel on a Wise Foundry Iron host, finds its address, deploys Alloy on it as a Compose stack), upgrades a running Alloy through Alloy's own upgrade (and its Steel appliance, when the ISO's Steel is newer), or restores one from a Steel backup onto a new appliance. See docs/deploy.md.

  • Host enrollment as specified by Iron (iron/docs/alloy.md):

    • single-use enrollment codes;
    • enrollment, signed confirmation and heartbeats, and leaving;
    • Alloy's signed, certificate-pinned calls to hosts: a live query and removal.

    See docs/enrollment.md.

  • Sections: the client opens an Alloy connection on Home, which gathers Alloy's sections into groups — Settings (this Alloy: users, roles, tasks, monitoring, policy and plugins), Iron Control (Sites and Hosts, Virtual Machines, vApps, Templates, Backup, Storage and Networking) and Updates (Update Management) — each with its own Navigator (wxclient/src/specs_alloy.cpp).

  • Virtual Machines: a tree of every enrolled host's virtual machines, LXC and Docker containers, read from the hosts with Alloy's signed calls, viewed by folder, by host or by kind. Operators sort them into global folders and subfolders — one folder holds workloads of any host — with Move to; folders and placement are kept in PostgreSQL. Through the same API they create, start, stop, snapshot, clone, edit and delete those workloads: Alloy asks the host's own API and follows the job it starts. Consoles open here too: graphical (noVNC) or serial for a virtual machine, Console, TTY or Shell for an LXC container, and an exec session for a Docker container. Alloy signs the WebSocket upgrade and passes the frames to the host untouched. See docs/vms.md.

  • Storage: every enrolled host's datastores in one table, and the datastore browser Iron has — folders and files, upload, download, new folder, move and delete — with the host in the address. New datastore puts one datastore on the hosts an operator chooses, which is what an NFS export is for; mounting and removing offer every host that has one of that name, and removing never erases data. Uploads stream from the client through Alloy to the host and are never written to Alloy's disk. See docs/datastores.md.

  • Networking: every enrolled host's networking, gathered around the one part of it that is a cluster matter — the port group name. A machine's spec names its port group, so it only migrates to a host that has that name: the first tab is one row per name across the cluster, saying which hosts have it, which do not, and where their VLANs or subnets disagree, which is a machine that would come up on the wrong network after a move. Port groups and oSwitches are created, edited and removed on the hosts an operator chooses, as datastores are. Virtual routers are managed per host, with their uplink, the port groups they serve, DHCP with reservations, NAT, port forwards, floating addresses, static routes and DNS, plus their leases and Restart. kSwitches, kernel adapters and physical NICs are shown read-only: changing one can move the address Alloy reaches the host on, and that keep-or-revert countdown belongs to the host itself. There is no per-host view — every tab is the whole cluster, and the hosts appear where they decide something: a port group's change lists the hosts that have it, what each one has it as, and the hosts that do not have it, which it can create it on. See docs/networking.md.

  • Update Management: upload a signed image pack (alloy-<VERSION>.alloyupd, what make image writes) and apply it. Alloy verifies its signature and checksums as the hosts verify theirs, hands the images to the Alloy Steel Appliance it runs on, and Steel updates Alloy's stack. Iron hosts take an .ironupd bundle: Alloy serves it on its own plain-HTTP port, each host downloads it and checks the Wise Global Solutions signature itself, and Alloy has the host verify and apply it, and restart when asked. The Alloy Steel Appliance takes a .steelupd bundle over the appliance's API token. See docs/updates.md.

  • Support bundles. POST /support/bundles (the client's Collect a bundle) collects one gzip tar of Alloy's settings, its database and the tail of its own log, for Wise Global Solutions support, the way iron-support and steel-support collect theirs. Passwords, session and enrollment tokens and Alloy's signing private key are never in one. See docs/support-bundles.md.

What is still open is under "Roadmap" in docs/architecture.md. The API is described in docs/api.md, and served as OpenAPI 3.1 at /api/v1/openapi.json, which /api/docs draws as an API reference. docs/README.md indexes every document.

Components

Part Directory Image Role
db db/ postgres:17.11-alpine3.24 PostgreSQL 17; the schema belongs to the API (api/migrations)
api api/ wisegs/alloy-api Node.js 22 (Fastify) API and manager on port 3000, on the Compose network only
web web/ wisegs/alloy-web nginx over HTTPS (host port 443; 9443 for the development stack): proxies /api/ to the API, and serves a welcome page, a read-only datastore browser (/datastores) and the API reference (/api/docs)
deploy deploy/ - Electron wizard that imports Steel on Iron and deploys the three above onto it

Running

Requirements: Podman with podman compose (or Docker with docker compose), make and openssl. Node.js is not needed on the host. podman compose must run Docker Compose, not podman-compose, which resolves the build contexts of compose.yaml's included files against alloy/; make checks (compose-check). Install docker-compose beside it, with the rootless socket on (systemctl --user enable --now podman.socket), or use the devcontainer.

make env        # .env from .env.example, with random database and admin passwords
make up         # build the images and start the stack; waits until it is healthy

Connect the Wise Foundry Client to localhost:9443 (the certificate is self-signed; the development .env publishes 9443, because rootless Podman cannot bind 443) and log in as admin with the password in ALLOY_ADMIN_PASSWORD in .env. That password is used only on the first start, while the database has no users. Change it from the client's user menu afterwards. https://localhost:9443/api/docs is the API reference.

Adding hosts

  1. Set Alloy's address. Hosts reach Alloy at ALLOY_URL, which defaults to https://ALLOY_HOSTNAME:ALLOY_HTTPS_PORT. Before enrolling real hosts, set ALLOY_HOSTNAME in .env to a name or address the hosts can reach, and run make reset up. The certificate is created for that name on the first start, and enrolled hosts pin it.
  2. Create a code for a cluster: POST /api/v1/enrollment-codes, the client's New enrollment codes... (docs/enrollment.md).
  3. Enroll the host. Connect the client to the Iron host and use Enroll on its Alloy page, or run iron-agent alloy enroll CODE from a shell; paste the code and confirm.
  4. Check the host. It appears under Sites and Hosts when it has confirmed its enrollment. Open it to see its heartbeats, query it, or remove it.

Make targets

<VERSION> below is YY.MM.PATCH (scripts/version.sh): YY.MM is this repository's branch when it is release/YY.MM, else (dev, any other branch, a detached HEAD, no git) the year and month of the build (UTC); PATCH is 0 unless given (make image PATCH=1); VERSION=YY.MM.PATCH overrides both. It reaches compose and the images as ALLOY_VERSION. The installer's package metadata spells it as semver, without the month's leading zero; the wizard still shows YY.MM.PATCH.

A bare make builds nothing: it prints make help, every target grouped by cost with the variables that matter. The build variants are dev (the debug build, whose depots go to PREREL) and release (PRODUCTION); VARIANT defaults to dev.

Target Does
make / make help Lists the targets and variables; builds nothing
make env Creates .env (never overwrites it)
make keys Creates the development signing key set in keys/ (docs/release-keys.md)
make image Builds the api and web images, exports all three to out/images/alloy-images-<VERSION>.tar.gz for Steel, and signs out/images/alloy-<VERSION>.alloyupd. make build is the same target
make release / make debug The images and then the installer, for the release and dev (debug) variants
make depot out/depot/alloy (or DEPOT_DIR) from this build's pack, with a signed format-2 depot.xml that also lists the installer ISO and the plugin SDK kit when built (docs/depots.md)
make depot-pwsh MODULE_PKG=… / make depot-offline OUT=… / make depot-index The rest of a channel directory DEPOT_DIR, for the root Makefile: the pwsh depot listing the PowerShell module's .nupkg; the offline bundle (scripts/mkoffline.sh) with the offline depot listing it; and the channel's index $(DEPOT_DIR).xml (+ .sig) beside the directory (scripts/mkdepotindex.sh). Each signed with this key set (docs/depots.md "Building a depot")
make plugins Builds and signs every Alloy plugin in plugins/ (its service's image; plugins are API-only) into out/plugins/<VARIANT>/<id>-<VERSION>.alloyplug, with this key set; Alloy ships none today, so it builds nothing (docs/alloy-plugins.md "Building a plugin")
make test-plugins The test fixture plugin hello into out/test/plugins/hello-<VERSION>.alloyplug, signed with the development or a test key set only, for make test-steel; never in a release or a depot (docs/alloy-plugins.md "The test fixture")
make plugin-run ID=… / make plugin-stop ID=… Starts / stops an enabled plugin's service beside the development stack, which has no appliance for Alloy to run it on (docs/alloy-plugins.md "Without an appliance")
make sdk The Alloy plugin SDK kit, out/alloy-plugin-sdk-<VERSION>[-dev].tar.zst, checking with this key set and carrying the sample plugins (node, go, service); make release builds it, make depot lists it in the depot (docs/plugin-sdk.md)
make test-kit The kit as a vendor uses it: every sample made with new, built and inspected (after make sdk; docs/plugin-sdk.md "Testing")
make vendor-cert VENDOR_ID=… VENDOR_NAME=… VENDOR_PUBKEY=… PLUGIN_IDS=… A third-party vendor's certificate for Alloy plugins, Iron's format, signed with this key set, in out/vendor-certs/<id>/ (docs/release-keys.md "Certifying vendors")
make keyguard Checks that the signing key set fits VARIANT, without building
make export-images Exports that archive and pack again without building
make payload Puts the Steel OVA and the same build's update bundle, the signed pack (which holds the image archive) and the update public key in out/payload
make installer Builds, then the Linux and Windows wizards and the ISO with them and the payload: out/alloy-installer-<VERSION>.iso
make up / make down Starts / stops the stack; data is kept
make logs / make ps Follows the logs / lists the containers
make restore FILE=… Restores an Alloy backup into the stack: stops web and api, restores the database, puts the certificate and keys back, starts the stack (FORCE=1 over a database that is not empty; docs/backup.md)
make reset Stops the stack and deletes its data directory: database, certificate, image packs and scheduled backups
make test API and wizard typecheck, lint and unit tests, in a Node.js container; the release scripts, vendor certificates and the SDK's Go helper
make deploy-wizard Opens the wizard from a container, with out/payload
make test-enroll Host enrollment end to end against the running stack, with a fake host built from ../iron
make test-e2e A stack of its own against two real Iron test VMs from ../iron/out/test in one cluster: enrollment, placement, bulk power, VM (cold and live), LXC and Docker moves, evacuation and maintenance mode, templates, sealed secrets, backup and restore, and a baseline update; about nine minutes, E2E_ONLY= for some steps (docs/architecture.md "Tests")
make clean Removes node_modules and build outputs

Without make: copy .env.example to .env, set both passwords and ALLOY_DATA_DIR (an absolute path), then podman compose up -d --build (or docker compose).

Deploying to Iron

The development stack above builds its images locally and runs wherever you are. Alloy belongs on a Wise Foundry Alloy Steel Appliance, which runs as a VM on a Wise Foundry Iron host. The installer does both:

make installer    # builds the images, takes ../steel/out/steel-<version>.ova (STEEL_OVA)
                  # and the .steelupd beside it (STEEL_BUNDLE),
                  # and writes out/alloy-installer-<VERSION>.iso

Mount or burn the ISO and run linux/alloy-installer or windows/alloy-installer.exe on a desktop that can reach Iron; its first page offers Install, Upgrade and Restore. For Install it connects to Iron, asks where Steel goes (VM name, datastore, port group, OS disk of at least 64 GB, memory) and how Steel gets its address (DHCP or static), checks Iron, then uploads and imports Steel, starts it, reads its DHCP address from Iron when there is one, and deploys Alloy on it from the images it carries. No registry is needed.

Without packaging, make payload deploy-wizard runs the same wizard from a container (Podman and a desktop session; no Node.js on the host). See deploy/README.md and docs/deploy.md.

Updating Alloy

Build the new version with make image. Then, in the Wise Foundry Client, open Update Management (or use the API, docs/updates.md):

  1. Connect Alloy Steel Appliance once: its address, its certificate (compare the fingerprint with Steel's console) and a Steel API token.
  2. Upload image pack: out/images/alloy-<VERSION>.alloyupd, the signed pack.
  3. Apply to Alloy: Alloy runs its checks, then hands the pack to Steel, which recreates Alloy's containers (POST /updates/packs/{id}/apply). Connect again when the new version answers.

See docs/updates.md.

Developing

  • API: api/src (TypeScript, compiled to dist/). Schema changes are new files in api/migrations/ (NNN_name.sql); never edit an applied migration.
  • Deployment wizard: deploy/, an Electron app; deploy/src/main holds everything that touches the network or a secret. It runs from its own container image (deploy/Containerfile), so a host needs only Podman; with Node.js 22.12 or later, npm ci && npm start in deploy/ runs it directly.
  • Web: web/html/, three static pages (the welcome page, the datastore browser and the API reference) with no build step, their strings in locales/<lang>/web.json (scripts/stage-locales.sh). The CSP allows nothing inline. The GUI is the Wise Foundry Client: a route or field change here needs the matching change in ../wxclient/src/specs_alloy.cpp.

Layout

compose.yaml         the alloy project: includes the three parts below
.env.example         settings; `make env` creates .env
data/                the stack's data: db/, tls/, alloy/ and keys/ (not committed)
keys/                the development signing key set, `make keys` (never committed)
db/compose.yaml      PostgreSQL
api/                 alloy-api: Dockerfile, compose.yaml, src/, migrations/
web/                 alloy-web: Dockerfile, compose.yaml, nginx/, html/
deploy/              the Electron installer that deploys Steel on Iron and Alloy on Steel,
                     with the Containerfile and launcher that run it from Podman
scripts/             keys.sh and keyguard.sh (make keys), export-images.sh (make image),
                     make-payload.sh (make payload) and make-iso.sh (make installer)
out/images/          the image archive, the signed pack and their .sha256 (not committed)
out/payload/         what the installer carries: steel/, images/ and keys/ (not committed)
out/*.iso            the installer ISO and its .sha256 (not committed)
test/enroll/         enrollment end to end with Iron's Alloy client code
test/e2e/            make test-e2e: a stack of its own against two real Iron test VMs
docs/                the design documents, indexed in docs/README.md

License

Apache License 2.0 (LICENSE.md); third-party components are listed in NOTICE.md.