What upgrades and support involve for Shuffle
An upgrade to Shuffle is never a single image swap. The server side runs a frontend, a Go backend API on port 5001 and an OpenSearch document database. The runtime side runs Orborus, which polls the backend for jobs and starts a worker for each workflow execution, and workers start versioned app containers. Each of these can run a different tag, so the first task is an inventory of what runs where, including every Orborus node and every app image that your workflows depend on.
Four triggers usually start the work. The first is support: Shuffle stopped supporting versions older than v2.1.1 after January 31, 2026, so an installation on an earlier release needs to move forward. The second is a need for newer functionality, such as v2.3.0, which was published on September 28, 2026. The third is licensing: since v2.1.1 the limits between the open-source and enterprise editions are actively enforced, so confirm your edition and expected app-run volume before upgrading. The fourth is a need for a monitored support arrangement, which is a decision about who tracks releases and responds when something breaks.
Plan the upgrade around three checks. Back up OpenSearch and record the value of SHUFFLE_ENCRYPTION_MODIFIER before any change, because the docs warn that losing or changing it breaks every saved app authentication. Record the tag each component runs now and choose target tags deliberately. The docs recommend the latest Docker tag for stable releases and the nightly tag for experimental changes, so production teams should decide in writing whether a nightly image is ever acceptable. After the upgrade, test workflows that call apps, because app containers are versioned separately and may need their own updates.
For most teams the split between in-house and partner work is practical. Teams with container and SOAR operations experience can usually handle routine minor upgrades, testing them in a non-production environment first and then in production with a rollback plan. Partners are commonly brought in for the first upgrade on an installation nobody on the team has touched, for large app libraries where each app needs retesting, and for regulated change control that requires evidence of testing and approval. Ask any provider to explain how it will handle the encryption secret and workflow regression tests before work starts.
What the work includes and what you receive
Scope, deliverables and timelines are agreed in writing before work starts. The cards below cover the upgrade work and the support package that follows it.
Current-state inventory
We record the running frontend, backend and Orborus versions, image tags, the OpenSearch version, the number of Orborus nodes and the app container versions in use. This shows which releases are in service and whether any installation runs a version older than v2.1.1, which Shuffle no longer supports. Check that the inventory matches what the servers actually run.
Upgrade plan and rollback
The plan sets the target release, drawn from the Shuffle GitHub releases, and the order for frontend, backend, OpenSearch, Orborus and app images. It also defines rollback: retained image tags, OpenSearch snapshots and the steps to restore the prior state. Confirm who gives the go or no-go decision and how long the rollback option stays available.
Staging rehearsal
The full upgrade runs first on a staging copy built from production configuration, including the encryption secret, OpenSearch data and at least one Orborus node. Issues and timings from the rehearsal feed the production runbook. Check that staging uses the same deployment architecture as production, whether Docker Compose, Docker Swarm or Kubernetes, so the results carry over.
Production upgrade of every component
The change runs in the order set by the runbook, covering OpenSearch, backend, frontend, Orborus nodes and runtime images. Where the topology allows, we keep at least one Orborus node available so workflows continue during the change. The SHUFFLE_ENCRYPTION_MODIFIER value stays unchanged, because a changed value breaks all saved app authentications.
Verification and handover records
After cutover we run app and workflow checks against the agreed test set, confirm that executions reach workers and that saved app credentials still authenticate. The handover set includes the inventory, runbook, test results, change record and updated app inventory. Ask who will own each record once the engagement closes.
Support package
Monitored release tracking reports new Shuffle releases and which ones affect your installation. Scheduled patch windows apply updates using the same rehearsal and rollback steps, and incident response follows the scope agreed in writing. Periodic health reviews check OpenSearch, Orborus and app versions. Confirm response expectations and coverage hours in the agreement.
What drives upgrade and support effort
This table lists the factors that change how much work an upgrade or support period takes, why each one matters and how to keep it under control.
| Driver | Why it matters | How to keep it down |
|---|---|---|
| Installed and custom apps | Each app container has its own version to check, and custom apps built from OpenAPI specs or the Python SDK need retesting against new releases. | Keep a versioned app inventory and retire unused apps before each upgrade. |
| Workflows and business-critical workflows | Critical workflows need regression runs after each upgrade. The licensing metric, app runs, has no direct effect on effort, but test volume does. | Tag business-critical workflows, keep a test set for each and automate the regression runs. |
| Orborus nodes and runtime locations | Orborus polls the backend for jobs and starts workers, so every node and location must move to a matching release. | Standardize image tags across nodes and list each runtime location with its network zone. |
| Deployment architecture | Single Compose server, Docker Swarm, hybrid with local Orborus, or Kubernetes with Helm charts each change the upgrade steps and rollback options. | Write one runbook per architecture and keep each environment on the same pattern. |
| OpenSearch cluster size and data volume | Index changes and backups take longer as data grows, and a failed upgrade is harder to roll back. | Confirm cluster health and take and test snapshots before every upgrade. |
| Number of environments | Dev, staging and production each need the same upgrade run, so effort grows with every extra copy. | Keep staging close to production in version, apps and data, and promote the same image tags. |
| Change-control requirements | Approvals, change windows and evidence of testing add review time before and after each upgrade. | Agree a standard change template and reuse test evidence across upgrades. |
| Version gap | Each skipped release adds breaking changes to review. Versions older than v2.1.1 lost support after January 31, 2026 (Shuffle configuration docs). | Upgrade in planned steps on a regular cadence and read the release notes for each version passed. |
| Edition in use | Since v2.1.1 the open-source and enterprise limits are enforced, so an edition or tier change can alter what runs after an upgrade. | Confirm the edition and its limits in writing before the upgrade plan is set. |
Project phases and outputs
The sequence moves a Shuffle deployment to a supported target version through inventory, rehearsal and a controlled production change, then hands it to steady-state support with verified apps and workflows.
Inventory the current deployment
DeployOpen records the running Shuffle version, the frontend, backend and Orborus images, installed apps and their versions, workflows and their trigger types, and where the SHUFFLE_ENCRYPTION_MODIFIER secret is stored. The output is a written inventory that your team signs off, so every later step checks against the same baseline.
Select the target version
We confirm the target against the stable Docker tag the Shuffle docs recommend for stable releases and the version list on the Shuffle GitHub releases page. Nightly builds are considered only for experimental changes and are not used for production by default. The output is a version decision record with the reasons and any open risks.
Rebuild staging and rehearse the upgrade
A staging environment is rebuilt from the production inventory, including the same encryption secret, and the upgrade is run end to end. The rehearsal output is a timed runbook with each command, rollback point and failure found along the way. Production work does not start until the rehearsal runbook is accepted.
Run the change window and production upgrade
Your team approves a change window, and DeployOpen applies the rehearsed runbook to production, taking backups before the change and confirming service health after each component moves. The output is a change record showing the versions applied, the backup references and the rollback decision made at each checkpoint.
Verify apps, workflows and runtime execution
Each installed app is checked for authentication against its saved credentials, each production workflow is run or replayed against a safe test target, and Orborus is confirmed to start workers and app containers. The output is a verification log listing every app and workflow with its pass or fail result and any remediation.
Hand over to steady-state support
We document the final configuration, the upgrade procedure for the next release, and the support boundaries. Ongoing responsibilities are agreed in the written scope, including whether a support package or retainer covers upgrades, app updates and monitoring. Ask for the support schedule and response terms in that scope before work starts.
What stays in-house and what goes to a partner
This table compares which Shuffle upgrade and support activities your team usually keeps, which a partner usually runs, and the skills each side needs.
| Activity | Usually in-house | Usually outsourced | Skills needed |
|---|---|---|---|
| Workflow sign-off | Business owners name the workflows that must keep running and the acceptable pause for each upgrade window. | Partner drafts the workflow inventory and records sign-off decisions before the change starts. | Security operations leadership, SOC lead, process ownership |
| Playbook logic and acceptance tests | SOC engineers own workflow logic, test cases and the go or no-go decision after each upgrade. | Partner re-runs regression tests and fixes broken workflows or apps during the window. | Shuffle workflow design, test data, SIEM and EDR knowledge |
| Container images and registry | Platform team pins image tags, controls the internal registry and approves each image for use. | Partner pulls, scans and stages frontend, backend and worker images against the target release. | Docker, image scanning, registry administration |
| OpenSearch administration | Platform team owns the cluster, snapshots and index health throughout the upgrade. | Partner plans the upgrade order, checks compatibility and runs pre and post upgrade checks. | OpenSearch cluster operations, snapshot and restore, capacity planning |
| App rebuilds | Engineers keep custom apps in version control and approve rebuilt app containers before release. | Partner rebuilds apps that change with the platform and updates their OpenAPI or SDK code. | Python SDK, OpenAPI specifications, app container builds |
| Orborus node updates | Platform team schedules node updates and keeps at least one runtime node available at all times. | Partner updates each Orborus node in turn and verifies job pickup and worker start. | Linux and Docker operations, Orborus configuration, runtime monitoring |
| Encryption modifier custody | Named in-house custodians hold SHUFFLE_ENCRYPTION_MODIFIER in their secrets store and confirm it before and after each upgrade. | Partner never holds the only copy and only confirms the value is unchanged during the change. | Secrets management, key custody, change control. Changing or losing it breaks saved app authentications. |
| Backup and rollback proof | Platform team owns backup retention and makes the final rollback decision. | Partner takes pre-upgrade backups, rehearses a restore and documents the rollback steps. | Backup tooling, restore testing, OpenSearch snapshots |
| Ongoing patch calendar | Owner sets the release review cadence and approves each patch window against business sign-off. | Partner tracks upstream releases, prepares patch notes and runs each window under a support package. | Release monitoring, change management, Shuffle version knowledge |
What goes wrong in Shuffle upgrades
Most failed Shuffle upgrades trace back to a small set of preventable causes. Each card names the risk and the check to run before and after the change.
Mismatched component versions
The frontend, backend and worker images, and every Orborus node, should run the same release tag. A frontend on a newer tag than the backend, or one Orborus node still on an older image, causes failed jobs that are hard to trace. Keep a version matrix that lists each component's image tag per environment, and upgrade all nodes in one change window.
Stale apps and UI-only testing
A platform upgrade does not rebuild app containers, so apps can fail on their first run after the change. Workflows checked only in the UI miss runtime errors that appear during execution. Before upgrading, rebuild or recheck each app container, run a canary workflow for each runtime location in staging, and prepare a rollback image list.
Encryption modifier changed or lost
The SHUFFLE_ENCRYPTION_MODIFIER secret protects saved app credentials and API keys in OpenSearch. If it is changed or lost, every saved app authentication breaks and workflows fail until each credential is re-entered. Store the value in your secrets manager, confirm it matches across environments before upgrading, and back it up alongside the OpenSearch data.
Unsupported or unpinned builds
Shuffle stopped supporting versions older than v2.1.1 after January 31, 2026, so older installs have no supported upgrade path. Nightly builds are intended for experimental changes, not production. Pin production to a stable release tag, record it in the version matrix, and move any older install to a supported version in staging first.
OpenSearch changes without a backup
OpenSearch is the document database behind Shuffle, holding workflow and execution records and encrypted app credentials, so changes to it carry the most data risk. A change made without a verified backup leaves no clean restore point. Back up the OpenSearch data and the encryption secret, restore that backup to a test cluster, and confirm workflows load before changing production.
Edition limits enforced after upgrade
Since v2.1.1, the limits between the open-source and enterprise editions are actively enforced. An upgrade can therefore stop executions once a limit applies, even though the workflows themselves have not changed. Before upgrading, confirm your edition and its limits in the configuration docs, and compare expected app-run volume against those limits in staging.
How the work differs by starting point
Versions older than v2.1.1 have been outside support since January 31, 2026, so the plan starts with a wider gap and more checks. The app and data review usually takes the largest share of planning work.
- Inventory every installed app version and custom app, since apps built against older versions may need rebuilding or retesting.
- Review saved workflows and their app references for behavior that changed across the gap.
- Confirm the SHUFFLE_ENCRYPTION_MODIFIER value is recorded and that saved app credentials still decrypt after the move, because changing it breaks all saved app authentications.
- Plan a staged path through intermediate releases where the release notes require it, and test each step against a copy of production data.
- Confirm with the client team that a restorable backup of the OpenSearch data exists before the first step.
An upgrade within the 2.x line on a single server with Docker Compose is the most direct path. The main work is aligning image tags across the frontend, backend and worker images and checking the compose file against the release notes.
- Pin the target tag for the frontend, backend and worker images together. The docs recommend the latest tag for stable releases and the nightly tag for experimental changes, so confirm which one the client has approved.
- Compare environment variables and compose file settings between the current and target releases.
- Back up the OpenSearch volumes and configuration before stopping any containers.
- Confirm which Orborus and app image versions the runtime will pull after the change.
- Confirm the maintenance window and who approves a rollback decision.
With Docker Swarm, the upgrade spans several servers, and each Orborus node runs workflow jobs in parallel. The plan controls the order of changes so workflows keep running while nodes are updated.
- Upgrade Orborus nodes one at a time so at least one remaining node keeps picking up jobs. The configuration docs recommend more than one Orborus node so workflows keep running if one fails.
- Check that backends and frontends scaled across servers all move to the same release.
- Confirm that shared NFS storage and any Memcached instance stay reachable during the rolling change.
- Pause or wait out long-running executions before replacing the node that runs them.
- Confirm with the platform team the placement constraints and image registry access on every node.
Helm-based upgrades change the chart version and the image values together. The plan is written around the chart release, the values file used in the running release and the cluster's rollout controls.
- Compare the current and target chart versions, including default values, since chart defaults can change between releases.
- Keep a copy of the values file from the running release and review overrides for image tags, secrets and resource limits.
- Confirm the rollout strategy and disruption settings so backends and Orborus pods are not all replaced at the same time.
- Confirm the OpenSearch stateful set, storage class and snapshot process before the change.
- Confirm with the cluster team which namespace, registry and admission policies apply to the new images.
In a hybrid setup, Shuffle Cloud runs the control plane while a local Orborus runs inside the private network with no inbound firewall ports. In an air-gapped network, there is no path to external registries, so every image must be mirrored into the client's registry before any upgrade step.
- Hybrid: confirm the local Orborus release is compatible with the cloud side, and plan its update as a separate change from the cloud change.
- Hybrid: confirm the outbound connectivity rules the local Orborus needs and whether the environment team accepts any planned change to them.
- Air-gapped: mirror the frontend, backend, worker, Orborus and app images for the target tags into the internal registry, and verify each image before import.
- Air-gapped: confirm the transfer method, the approval steps and who can import artifacts into the restricted network.
- Confirm that app images used by workflows are mirrored too, including any versions pinned in custom apps.
What you need to provide
The upgrade starts with a current inventory of your Shuffle deployment. List the version and image tag for the frontend, the Go backend API, each Orborus node and each worker or app image in use, plus the OpenSearch version. Mixed tags across these components are the most common reason a planned upgrade stalls, so the inventory should be taken from the running hosts or cluster, not from memory or the original deployment files. You also need access to the host or Kubernetes cluster, the container registry where images are pulled, and the change records that show what was last deployed.
Some inputs carry data and security risk and need to be handled under your own secret policy. Provide a copy of the OpenSearch data taken from a backup, and the value of SHUFFLE_ENCRYPTION_MODIFIER used by the running environment. Losing or changing that secret breaks every saved app authentication, so confirm where it is stored, who may read it, and how it will be carried into the staging copy without being written into tickets or chat. Ask your security team to approve the transfer method before the copy is made.
Shuffle needs decisions from your side as well. Provide a ranked list of workflows by business criticality, with a named owner for each, and test cases or expected outcomes for the critical ones, since these define what a successful upgrade means. Name the maintenance window and the change approver who can accept the risk. Provide a staging environment that matches production as closely as possible, including the same deployment architecture, runtime locations and reachable integrations. Confirm the target release and edition, because the open-source and paid editions differ in enforced limits.
Owners must confirm which app versions are approved for the target release and who signs off the post-upgrade results. Approved app versions are a business decision, not a technical default, and a workflow that runs on an app version nobody has reviewed can fail quietly in production. Agree the sign-off in writing before the work starts, so a successful test run is recorded as an accepted outcome.
Common questions about Shuffle upgrades and support
Can our own team upgrade Shuffle without outside help?
Yes, if you have a tested runbook and a staging copy of your deployment. Start by reading the release notes for your target version and choosing the stable Docker tag that the Shuffle docs recommend, then confirm that tag against the release notes before you pin it. Keep the frontend, backend and Orborus worker images on aligned versions, and rehearse the upgrade on staging with a restored OpenSearch backup first. Teams usually need outside help when the version gap is large, when several runtime locations or hybrid Orborus nodes must move together, or when apps need rework. Shuffle stopped supporting versions older than v2.1.1 after January 31, 2026, so older installations usually need more planning.
What drives the cost of a Shuffle upgrade?
The main drivers are the size of your workflow and app inventory, the number of apps, where your runtime locations sit, the size of your OpenSearch data, how far behind your current version is, and how strict your change control must be. More workflows and apps mean more tests to rerun. Multiple Orborus nodes and hybrid runtimes add coordination work. A large version gap can add intermediate steps and extra app checks. Strict change control adds approvals, evidence and rollback rehearsal. Ask for a quote that lists each driver as its own line, and separate one-time upgrade work from any recurring support.
How long does a Shuffle upgrade take?
It depends on scope, so the duration should be stated in the written plan before work starts. Scope includes the number of environments, the version gap, how many apps and workflows need retesting, the volume of OpenSearch data to back up and restore, and the number of runtime locations. Ask for the plan to list each stage, the test gate between stages, and who is responsible for each one. Be cautious about any timeline offered before someone has inventoried your workflows and apps, because the inventory is what sets the schedule.
Do we need a paid Shuffle support package to stay current?
No. Shuffle states that all features are available in the open-source edition, so you can run and upgrade it yourself. Its paid tiers differ in feature limits, scaling and support, and since v2.1.1 those limits are actively enforced. A support package adds the vendor support level of the chosen tier and any higher limits or scaling you need. Licensing is based on app runs, meaning actions that execute in a workflow, while users, apps and workflows are unlimited. Confirm current terms with Shuffle. DeployOpen also offers retainers for ongoing support and upgrades, which is a separate decision from Shuffle's own tiers.
Why does the Shuffle encryption secret matter during upgrades?
Shuffle encrypts saved app credentials and API keys in OpenSearch with AES-256, using the SHUFFLE_ENCRYPTION_MODIFIER secret. If that value is lost or changed, every saved app authentication breaks. An upgrade must keep the same secret in the new configuration, and you should back it up in your secrets store before you change anything. After the upgrade, verify that a sample app authentication still works. Treat the secret as part of the same backup set as your OpenSearch data, because the encrypted credentials cannot be recovered without it.
What happens to apps after Shuffle is upgraded?
Apps run as versioned Docker containers, so each app keeps the version it was installed with until you change it. Plan for workflows to be retested after the platform changes, because a platform upgrade does not prove that every automation still works. Check each app's compatibility in the new release notes, rerun workflow tests in staging, and confirm that saved credentials still authenticate. Apps built from OpenAPI specifications or with the Python app SDK may need regeneration or code changes if the platform interface moves. Keep an inventory of apps and their versions so the upgrade plan covers each one.
How DeployOpen delivers Shuffle upgrades and support
DeployOpen plans, implements, hardens, documents and supports self-hosted open-source platforms inside your own infrastructure, including Shuffle. For upgrades and support, we scope the work in writing, test each change against your playbooks and apps, and hand over runbooks your team can follow.
How we scope
- The written scope lists which Shuffle components move: frontend, backend, OpenSearch, and each Orborus and worker image.
- Scope names the target release, the current versions in use, and the apps and workflows that must be re-checked afterward.
- Engagements are fixed-scope, and ongoing upgrades and support can be arranged as a retainer after the written scope is agreed.
How we build
- We align frontend, backend and worker image tags to one tested release, following the Docker tag guidance in the Shuffle docs.
- We test an upgrade in a non-production copy first, including OpenSearch data, saved app credentials and the encryption secret.
- Apps built from OpenAPI or Python are updated, retested and versioned as containers so each change can be traced and reversed.
How we hand over
- You receive an upgrade runbook with pre-checks, the ordered steps, rollback points and post-upgrade verification.
- Documentation records each deployed image tag, app version and configuration change, so your team knows what is running.
- Your staff are walked through the runbook and support boundaries, so routine upgrades can be repeated without us.
How we support
- Support covers the agreed scope, such as version reviews, planned upgrades, app updates and incident response on the Shuffle stack.
- Retainer terms define response expectations, which you should confirm in writing before the engagement starts.
- Recurring support is priced separately from one-time upgrade work, and the quote should list what each option includes.
