Skip to main content

Upgrading Organisations

For the cloud engineer who installed Organisations, with the same AWS credentials: run the newer bundle's installer from a fresh directory in the same account and region; it re-runs the steps a release changes and leaves your administrators and single sign-on as they are.

Before you start: download the latest release from the AlphaAgent Console's Organisation page (Console: licences, usage and billing); the installer does not fetch releases. Requirements are those of the install (Install Organisations).

Upgrade​

  1. Unzip the new bundle into its own directory.
  2. Copy the installer's state file, .alphaagent-org-install.json, from the previous bundle's directory into the new one; it carries the step record and your answers.
  3. Run python3 orgctl.py install with the same --region and credentials. The installer finds the existing Organisation, prints its six stacks and reads the running version from the deployed application stack itself. If it is older than the bundle it says "this bundle is <new>; the running install is <old>." and offers the Resume menu: Resume (default: continue from the first incomplete step and update the running install), Redo (every step again; idempotent, slower) or Delete and reinstall (destroy everything, then start fresh). --yes always resumes.
  4. Confirm. The installer prints "Upgrading from <old> to <new>." and "Re-running org-auth, foundation, push-image, seed-config, spa, app, settle, doctor to apply <new>": the sign-in stack (updated in place), the foundation and data stacks, the container image, the configuration secrets, the console web application, the application stack, the settle wait and the doctor. saml, console-credential and bootstrap-admin do not re-run and are not asked again.
  5. Wait for the Done banner with your console address and the version installed.

A stack change that would replace a data-holding resource (a table, secret, bucket, file system, cache, the user pool, a repository, queue, topic or database) stops and asks; only --allow-data-loss skips the question, never --yes or --config. Progress is saved after each step; Ctrl-C stops before the next and the same command resumes. Finally the installer re-reads the running version; a run that leaves the old one in place exits with "This run did not update the running install (still <old>). Run python3 orgctl.py install --redo or report this." instead of Done.

Run doctor​

python3 orgctl.py doctor, the last step, checks the configuration secrets, fail-closed configuration, the tables, the administrator roster, the image repositories, the two services, the account-registration template, the web application's CORS rule, the SAML wiring, the sign-out address and the Console credential. Before checking the services it waits for any rolling restart the preceding steps started. It prints "N passed, N warning(s), N failed, N skipped", exits 2 on a failure, and --json prints data. After an upgrade: sign-out fails if the signed-out address is missing (run python3 orgctl.py org-auth); console-credential warns if the Console is unreachable and fails if the credential was rotated or revoked there (run python3 orgctl.py console-credential, or bundle downloads fail).

Re-run a single step​

Every step has its own command: preflight, org-auth, foundation, push-image, seed-config, spa, app, settle, console-credential, saml, bootstrap-admin and doctor; a single step skips the requirements block and the confirmation. saml re-asks for the metadata file when your identity provider's certificate rotates; console-credential follows a rotation in the Console.

status, reset and teardown​

  • python3 orgctl.py status prints the installed state (steps, single sign-on values, hostname, load balancer, stack statuses) and never prompts; a "stuck" stack cannot be updated: delete it, then python3 orgctl.py install --restart-from <step>.
  • python3 orgctl.py reset empties the state file when it was confirmed against another account or region.
  • python3 orgctl.py teardown deletes the Organisation in this account and region; the full resource list and flags are on Install Organisations.

What you should see​

  • The Done banner with "Console: https://<your hostname>"; doctor printing "N passed, 0 failed" (warnings are explained in the table).
  • The Organisations console offering Reload to anyone signed in; its footer shows the new version. On the live walk the upgrade took 7 minutes.

Notes​

  • python3 orgctl.py with no command prints the guided welcome ("No install recorded on this machine…", "An install is already under way here: N/12 steps done. Next step: …", or complete) and offers to start or resume.
  • Same account and region only. One installer per directory at a time; status is never blocked.
  • Without the copied state file the installer recovers the installation from the live stacks and still applies the release, but may re-ask answers it cannot read back. An interrupted first install finished with single-step commands also upgrades correctly.
  • Teardown never touches the registration stacks in your Studio accounts (Accounts).