@fortytwoservices/ai-universe-setup

@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.

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