@fortytwoservices/ai-universe-setup

Setup and upgrade CLI for Fortytwo AI Universe customer portals.

Usage

Initial setup

Provisions a new portal on Azure (Container Apps, PostgreSQL, Key Vault, ACR, App Insights):

npx @fortytwoservices/ai-universe-setup

Run with no flags for the interactive wizard. The recommended Azure region is swedencentral (broadest GA Azure OpenAI / Foundry model coverage); all regions remain selectable.

Unattended / non-interactive setup

Every prompt value can be supplied as a CLI flag or an environment variable, so the whole install runs from a single command an operator can hand off. With --non-interactive the CLI never prompts: it requires all mandatory values and fails fast (before any Azure work) listing exactly which are missing and how to supply them.

| Flag | Environment variable | Required | | -------------------- | --------------------------- | -------------------------------------------- | | --portal-name | FORTYTWO_PORTAL_NAME | yes | | --resource-group | FORTYTWO_RESOURCE_GROUP | yes | | --region | FORTYTWO_REGION | yes | | --image-version | FORTYTWO_IMAGE_VERSION | no (defaults to the latest published kernel) | | --license-username | FORTYTWO_LICENSE_USERNAME | yes | | --license-token | FORTYTWO_LICENSE_TOKEN | yes |

Resolution precedence per field is CLI flag > environment variable > interactive prompt (the prompt only when a TTY is attached and --non-interactive was not given). Pass the license token via the env var so it never lands on the process command line:

FORTYTWO_LICENSE_TOKEN=*** \
  npx @fortytwoservices/ai-universe-setup \
    --portal-name acme \
    --resource-group rg-acme \
    --region swedencentral \
    --license-username customer-acme \
    --non-interactive

--help lists every flag with its env equivalent; --version prints the scaffolder version.

Upgrade an existing portal

Re-imports kernel images into the customer ACR and updates the backend and control-galaxy container apps to the new version. Does not re-run Bicep — safe to run on a live portal.

npx @fortytwoservices/ai-universe-setup --upgrade

Prompts for: Azure resource group name, target kernel version (latest or a pinned semver like 1.2.0), and Fortytwo license credentials. Portal name is derived from the resource group (strips -rg suffix). Pin a version for a reproducible, rollback-able upgrade; choose latest to track the newest published kernel.

Uninstall a portal

Tears a deployment down completely: it empties the WORM audit-archive storage, deletes the Azure resource group (all container apps, APIM, Postgres, Key Vault, storage, ACR, identity, and the rest), then purges the soft-deleted name reservations (Foundry, Content Safety, APIM, Key Vault) so the portal name can be reused. Safe by default: it refuses a resource group that does not carry the installer's fortytwo-install:* tags, previews everything that will be removed, and requires you to type the portal name to confirm.

# Discover deployments and pick one (auto-selects if there is exactly one):
npx @fortytwoservices/ai-universe-setup --uninstall

# Or target one explicitly:
npx @fortytwoservices/ai-universe-setup --uninstall --resource-group <rg>

With no --resource-group, it enumerates the deployments in the current subscription (via the fortytwo-install:* RG tags and the local ~/.fortytwo/install-*.json files) and, when several exist, shows a picker.

By default everything is purged so a same-name redeploy is clean. The Entra app registration is kept (it is operator-created and may be shared across deployments), and Postgres' name stays reserved (Azure has no purge for Flexible Server — wait or use a new name). Flags:

• --keep-vault keeps the Key Vault soft-deleted (recoverable ~7 days) instead of purging it.
• --delete-entra-app also deletes the Entra app registration (irreversible; skip if it is shared).
• --yes skips the typed confirmation for scripting; it then needs an unambiguous target (--resource-group, or exactly one discovered deployment).

Not cleaned up (the final summary reminds you): this tears down Azure resources only. Galaxy GitHub repositories and the org GitHub App remain, and Entra artifacts remain — the platform app registration + its Enterprise Application (service principal), and any per-galaxy app registrations galaxies created. Remove those manually if the deployment is fully retired. How to find them in Entra:

• Platform / Universe — operator-created, so no fixed name; find it by its Application (client) ID (shown in the summary, and stored in ~/.fortytwo/install-*.json / the RG fortytwo-install:* tags): az ad app show --id <clientId> and az ad sp list --filter "appId eq '<clientId>'" (its client secret is labelled galaxy-platform).
• Galaxies — each is named galaxy-<galaxyId> (…), so filter by the galaxy- prefix: az ad app list --filter "startswith(displayName,'galaxy-')" and az ad sp list --filter "startswith(displayName,'galaxy-')".

If the audit-archive storage carries a locked immutability policy or a legal hold, that is real WORM: the run stops without deleting anything — wait out the retention window, then re-run.

The same two-phase procedure also ships as a standalone script — the manual fallback if you need to tear down from a bare shell or debug a half-deleted RG:

packages/setup/scripts/teardown-deployment.sh <resource-group> <portal-name> <region>

Full reference and stuck-teardown diagnostics: docs/concepts/deployment-teardown.md.

Region viability

Some Azure regions cannot host the platform for a given subscription, and the cause only surfaces at resource CREATE time. Three failure modes have been observed live on the same subscription:

• norwayeast — storage accounts stuck in provisioningState: Creating for 30+ min and never completing (an Azure storage-backend hang).
• westeurope — Postgres LocationIsOfferRestricted (the subscription is barred from the region) and Container Apps ManagedEnvironmentCapacityHeavyUsageError / AKSCapacityHeavyUsage (regional capacity exhausted).

az deployment group what-if/validate do NOT catch any of these (they are offer restrictions, live capacity, and a backend hang), so the installer guards against them in three layers:

1. Queryable pre-check (always on). During preflight, az postgres flexible-server list-skus -l <region> confirms the region offers Postgres Flexible Server at all. Reported as a PASS/FAIL line. Catches "region offers no Postgres" but not the subscription-level offer restriction or live capacity.
2. Fail-fast with guidance (always on). During the deploy, when a resource reaches Failed the installer reads the leaf error code; for the known region-viability codes it aborts immediately with actionable guidance (resource + region + reason + "re-run with --region swedencentral") instead of a generic 20-min failure. A storage account stuck in Creating past a threshold is surfaced the same way.
3. Real region probe (opt-in). --probe-region creates throwaway capacity/offer-sensitive resources (smallest Burstable Postgres, a Container Apps managed environment, a storage account) in a throwaway resource group, with short timeouts, before the main deploy. If any hits a viability code or times out, the install aborts with the region-switch guidance. The probe resource group is always deleted afterward. This is the only 100%-reliable pre-check; it is off by default because it costs ~5 min.

# pin the region (skips the interactive picker)
npx @fortytwoservices/ai-universe-setup --region swedencentral

# additionally run the real ~5-min probe before deploying
npx @fortytwoservices/ai-universe-setup --region swedencentral --probe-region

Local development

Starts the platform locally using Docker or Podman:

npx @fortytwoservices/ai-universe-setup --local