Skip to content

Upgrade Notes

What an administrator has to do when upgrading Foundry Connect, newest release first. Read the notes for every version between the one you run and the one you are moving to. The Upgrade Notes tab in the app carries the short form of each entry; this page has the full reasoning.

Version 2.23.0

  • Saving or launching with an AWS assume-role credential is now refused when the Foundry Connect server's own AWS identity is itself a role session (an instance profile, ECS task role or IRSA), because such a chained session cannot last the 12 hours a run needs. Run the server with IAM user credentials before upgrading if any run environment uses an assume-role credential.

Version 2.22.0

  • Uploading a Google Cloud customer boundary by CSV now requires two more columns on every GCP row: gcpNetwork, the VPC each run attaches to (global/networks/<name> or the project qualified form projects/<project>/global/networks/<name>), and gcpMasterDowndir, the run download location (a gs:// URL). Both are required from the boundary form too. A CSV or a boundary written before this change is missing them; add the two columns, and optionally a third, gcpSubnetwork (regions/<region>/subnetworks/<name>, left blank on any row that does not use one), before uploading again, or the file is rejected at upload time naming the missing column and row. Boundaries already stored in the database are unaffected: a migration fills both fields with the value the platform used to assume, so nothing already provisioned needs hand editing. An AWS boundary gains an awsMasterDowndir column of its own (an s3:// URL); a separate change in this same release makes that column required, and carries its own entry describing it.

Version 2.21.0

  • The Foundry Status link in the profile menu no longer appears until STATUS_PAGE_URL is set. It previously pointed every installation at one hardcoded status page that reported on a single deployment rather than yours. Set STATUS_PAGE_URL to your own status page to bring the link back. Privacy Policy now resolves to your own installation's documentation site by default; that page describes the deployment it ships with, so review it and set PRIVACY_POLICY_URL to your own policy if your organization operates this installation.

Version 2.20.1

  • Application logs are now single line JSON instead of formatted text. Anything that parsed the old text layout, including greps, tails, and dashboards, needs updating. Set LOG_FORMAT=pretty for human readable output on stdout; the log file stays JSON either way.
  • The separate HTTP access log file (<LOG_FILE_NAME>.http.log) is gone. Request logging is now part of the main application log, carrying the same correlation identifier as every other line from that request.
  • LOG_LEVEL=audit now means info, audit, warning and error, and no longer includes debug. Under the old logger the levels ran the other way round, and audit sat below info. Set LOG_LEVEL=debug if you were relying on debug lines.
  • Reverting migration 2026-08-13-agent-transport-schema.js refuses while any run environment still uses agent transport. Its down() checks before touching the schema and throws Cannot revert: N run environment(s) still use agent transport (...), because reverting would silently return those environments to SSH, which they have no credentials for. Move them to an SSH environment first, then revert. This costs nothing until someone sets a run environment to agent transport; before that the check passes trivially.
  • That revert is also not re-runnable: its ALTER TABLE profile_cluster DROP COLUMN transport is unguarded, so a second attempt fails with Can't DROP 'transport'. It is deliberate that data_source.writable is not dropped on revert, so an administrator's demotion of a source is never discarded; re-applying the migration will not re-grant write access either, because the backfill only runs when the column is newly created.

Version 2.20.0

  • process.process_rev_uuid Unique! A revision uuid now identifies exactly one process revision per installation, enforced by the new uq_process_rev_uuid key added by migration 2026-07-31-unique-process-rev-uuid.js.
  • Rolling back across this release is not a tag flip. The migration only adds an index, so it looks additive, but the previous release binds the parent revision's uuid into the INSERT every time anyone saves a process revision, and the new key rejects that. An older image boots cleanly against the newer schema and then fails every process revision save, and every import that revises a process, with a duplicate-key error. ALLOW_SCHEMA_AHEAD=true does not help: it only checks that the applied migrations are a prefix of what the image knows, and the key is still there.
  • Before you start an image from before this release, the key has to go. Do not revert only as far as 2026-07-30-process-revision-origin.js. That clears the key, but it leaves 2026-07-29-run-status-vocabulary.js applied, which retypes run.run_status and rewrites its values, so every existing run row keeps the new vocabulary while the older code compares against the old one. Nothing throws and nothing is logged, so the breakage is silent. Revert the whole way to the tip you were on before the upgrade instead: for 2.19.7 that is pnpm migrate -t 2026-07-23-index-run-uuid-joins.js in the backend container, which needs no ALLOW_SCHEMA_AHEAD because the schema then matches the image exactly. If the container is already gone and you are restoring a pre-upgrade dump anyway, ALTER TABLE process DROP INDEX uq_process_rev_uuid; against the database clears the key on its own. Full procedure in deploy/prod/UPGRADING.md.
  • Run status API values renamed: NextSuc→Completed, NextErr→Failed, NextRun→Running, init→Initializing, Waiting→Submitted, Error→LaunchFailed, Aborted→Unreachable. Responses return the new values immediately; the previous values are still accepted in API filters for two releases, then removed.

Version 2.17.6

  • ENABLE_STRIPE Added! This variable controls whether Stripe integration is enabled. Default is false.

Version 2.12.0

  • WORKBENCH_ENABLE set it to true to enable workbench-related scheduler tasks. These background jobs periodically:
  • Fetch and sync VM instance status from GCP
  • Calculate and track workbench usage costs
  • Update workbench state in the database

Version 2.10.0

  • ENABLE_FF_WALKINS_WELCOME default has changed to true->false. We need to set to true for GCP production.
  • ENABLE_SIGNUP default has changed to true->false.

Version 2.9.0

Config Synchronization Issues Identified

  • ENABLE_SMTP: Removed! It was required for displaying "Forgot Password?". It has been replaced with ENABLE_EMAIL_NOTIFICATIONS.

Version 2.8.0-beta

  • ENABLE_SMTP: It is required to add ENABLE_SMTP=true to show "forgot password?" button to user on login page.
  • FOUNDRY_CLASSIC_BUTTON_URL: allows to configure FOUNDRY_CLASSIC_URL.
  • SAML_EMAIL_ATTRIBUTE_NAME: allows to change default SAML attribute for email.

Version 2.7.1-beta

SAML Callback Url is changed

Endpoint for SAML Callback is changed from /api/auth/v1/saml/redirect to /api/auth/v1/saml/callback. Make sure to update corresponding SAML IDP settings, especially Keycloak configurations.

Version 2.6.1-beta

Workbench Environment Variables Updated

WORKBENCH_WAIT_AFTER_INSTANCE_RESTART_IN_SECONDS has been renamed to WORKBENCH_WAIT_AFTER_INSTANCE_RESTART. You should now set the value in milliseconds instead of seconds.

WORKBENCH_WAIT_AFTER_INSTANCE_CREATED_IN_SECONDS has been renamed to WORKBENCH_WAIT_AFTER_INSTANCE_CREATED. You should now set the value in milliseconds instead of seconds.

Version 2.4.0-beta

For login and signups inactive and deleted users now will be unable to access the system. active and deleted fields in vpipe.user table are checked, so some users created may effected. If user's active field is NULL due to user created previously, they won't be able to login to the system.

Version 2.3.7-beta

Frontend Container: v1.0 Volume Unmounted

The v1.0 volume has been unmounted from the frontend container.

Version 2.3.1-beta

Workbench Environment Variables Updated

Workbench variables have been updated! Please check the env_changes file for the latest environment variable changes.

Version 2.2.0

Deprecation Notice: OUTPUT_DIR Environment Variable

The OUTPUT_DIR environment variable and the /output directory inside the container are now deprecated.

What Changed?

  • The container no longer uses /output for persistent files.
  • Instead, the container now exposes /var/log/viafoundry.

Required Action

Please update your docker-compose.yaml volume mapping:

Old configuration

volumes:
  - ./output:/output

New configuration:

volumes:
  - ./output:/var/log/viafoundry