Shuffle single server vs Docker Swarm vs Kubernetes

Shuffle runs executions on one Docker Compose server, on several hosts with Orborus in Docker Swarm mode, or on Kubernetes with the official Helm chart. This page explains when each model fits, what each one needs open and operated, and which scaling features require a paid license.

On this page

Shuffle single server, Swarm or Kubernetes: which deployment model fits your volume

For most starting volumes, the default single-server Docker Compose setup is the right answer. Docker Swarm suits a team that wants several Docker hosts for Shuffle executions without taking on Kubernetes, and Kubernetes suits a team that already runs and supports a cluster. The choice turns on three things: the platform skills your team already has, the scaling features you actually need, and how much operating work your team can absorb each month. The license tier matters too, because some scaling variables only work with a paid Shuffle license, and that applies in every deployment model, not just one of them.

Single-server Compose is the simplest path. The Shuffle configuration docs say the default docker-compose file works well to scale on one server, and Orborus, which receives jobs from the backend and manages the worker and app containers that run each execution, exposes no port. Your main work is backups, OpenSearch sizing and watching SHUFFLE_ORBORUS_EXECUTION_CONCURRENCY, which defaults to 10 concurrent executions. Swarm moves execution across hosts, but it requires ports 2377, 7946 and 4789 open between hosts, manager-level Docker API access for Orborus, and a SHUFFLE_SWARM_CONFIG=run setting. Before choosing Swarm, confirm with your platform team that these ports and Docker API permissions are acceptable under your network policy. Kubernetes uses the official Helm chart, with worker replicas set statically through SHUFFLE_SCALE_REPLICAS because the HPA option is still marked as coming soon. Ask Shuffle to confirm the current status of autoscaling before you plan around it.

How the three Shuffle deployment models compare on architecture, scaling and licensing

This table sets the single-server Docker Compose setup, Orborus in Docker Swarm mode and the official Helm chart on Kubernetes side by side on where Orborus runs, how workers scale, ports, static and licensed variables and required skills. Read each row as a question to answer for your own volume and team, then check the licensed items against your Shuffle license tier.

FactorSingle server (Docker Compose)Docker Swarm (Orborus swarm mode)Kubernetes (Helm chart)
Where Orborus runsOn the same server as the backend, frontend and OpenSearch, managing worker and app containersOn one or more Docker hosts, with Orborus able to manage executions across swarm nodes when SHUFFLE_SWARM_CONFIG=run is setConfigured through the RUNNING_MODE setting in the Helm deployment
How workers scaleScaling on one server, which the default docker-compose file is described as handling wellExecutions spread across swarm nodes, with SHUFFLE_MAX_SWARM_NODES capping the node countWorker replicas set statically with SHUFFLE_SCALE_REPLICAS, and HPA is labeled as coming soon
Concurrency controlSHUFFLE_ORBORUS_EXECUTION_CONCURRENCY, which defaults to 10 concurrent executionsSame concurrency setting, applied to executions across swarm nodesSame concurrency setting, with app settings applying to all apps so individual apps cannot be tuned separately
High availability guidanceSingle server offers no node-level failover, so the docs' HA guidance points to other modelsDocs recommend more than one Orborus node so workflows keep running if one fails, plus an OpenSearch cluster and NFS for shared filesDocs recommend an OpenSearch cluster, Memcached for a shared cache and multiple replicas, with the same shared-file and Orborus guidance applying
Ports and network accessOrborus exposes no port, and the backend listens on port 5001Ports 2377, 7946 and 4789 must be open between hosts, plus manager-level Docker API access for OrborusCluster networking and API access are governed by the Kubernetes setup, so confirm port rules with your platform team
Static or licensed scaling variablesCore settings are open source, with scaling variables that need a paid license depending on tierSwarm scaling is partly open source since September 2024, and some scaling variables require a paid licenseReplica settings are static, and some scaling variables only work with a paid Shuffle license, which also requires the licensed worker image
Skills the team needsDocker Compose, Linux administration and OpenSearch basicsDocker Swarm administration, overlay networking and Docker API securityKubernetes operations, Helm, RBAC, etcd backup and Secrets encryption at rest
Confirm before choosingExpected peak execution volume against the default concurrency settingWhether your license tier includes the swarm variables you plan to useCurrent HPA status and whether your license covers the replica variables you need

How Shuffle Orborus and workers map to each deployment model

Shuffle splits into a server side that stores and serves workflows, a runtime side that executes them, and the app containers those executions start. The three deployment models differ mainly in where Orborus runs and who keeps it alive, so the cards below follow each component through single server, Swarm and Kubernetes.

Server side: frontend, backend and OpenSearch

The server side is the frontend, a Go backend API listening on port 5001, and an OpenSearch document database that holds workflows, app configuration and execution records. Under the single-server Docker Compose setup these all sit on one host, which the Shuffle configuration docs say works well to scale on one server. Under Swarm or Kubernetes you must decide how the backend and frontend are scaled, and the docs recommend an OpenSearch cluster and NFS for shared files when several backends run. Confirm your OpenSearch sizing and backup approach before you add hosts.

Orborus: the job poller

Orborus polls the backend for jobs and starts a worker for each workflow execution. It exposes no port, which is why the hybrid model needs no inbound firewall rules. In single-server mode it runs beside the backend. With SHUFFLE_SWARM_CONFIG=run it runs in Swarm mode across hosts, and on Kubernetes it is set through RUNNING_MODE. Your job is to keep it running, watch its health, and place it where it can reach both the backend and the Docker or Kubernetes API it needs.

Workers and app containers

For each execution, the worker starts app containers, and each app runs as a versioned Docker container. Apps are built either from OpenAPI specifications in the App Creator or written in Python with the Shuffle app SDK. Under Swarm, workers are scheduled across nodes, subject to SHUFFLE_MAX_SWARM_NODES. On Kubernetes with Helm, worker replicas are fixed with SHUFFLE_SCALE_REPLICAS, and app settings apply to every app, so you cannot tune individual apps separately. Plan image versions and app tests as part of each upgrade.

Three deployment shapes

The Shuffle architecture docs describe a single server with Docker Compose, distributed Docker Swarm, a hybrid model using Shuffle Cloud with a local Orborus, and Kubernetes with Helm charts. Each shape moves the same components. Single server is the simplest to operate but has one failure domain. Swarm adds hosts but requires ports 2377, 7946 and 4789 open between them and manager-level Docker API access. Kubernetes gives declarative control but adds cluster operations. Recommend more than one Orborus node in every shape, so workflows keep running if one fails.

Which scaling features need a paid Shuffle license in each model

On a single server, the default docker-compose file is the documented way to scale. Orborus receives jobs from the backend and starts the worker and app containers for each execution, so scaling on one host mostly means deciding how many executions the machine can run at once. The main control is the concurrency setting.

  • Concurrency setting: SHUFFLE_ORBORUS_EXECUTION_CONCURRENCY defaults to 10 concurrent executions. You size it against the CPU and memory of that one machine.
  • Swarm and Kubernetes knobs: SHUFFLE_MAX_SWARM_NODES and SHUFFLE_SCALE_REPLICAS apply to multi-node and Kubernetes models, so they do not change a single-host setup.
  • Partially open source scale work: The docs say scale has been partially open source since September 2024, and some scaling variables only work with a paid license. The supplied material does not list which single-server variables fall on each side.
  • Licensed worker image: Licensed customers load the licensed worker image, so check whether your tier requires it before you rely on a given setting.
  • Failover limits: The high availability guidance (an OpenSearch cluster, NFS, and more than one Orborus node) is a multi-server pattern, so one server does not provide failover for running workflows.

Ask Shuffle which single-server settings are in the open-source edition and which need a license key, and get the answer in writing for your version.

What Docker Swarm needs open between hosts and who gets Docker API access

Orborus runs in Docker Swarm mode when the SHUFFLE_SWARM_CONFIG setting is set to run. According to the Shuffle configuration docs, this makes executions faster and less resource-intensive than running them on a single host, which is the main reason to take on Swarm's extra moving parts. Before you enable it, confirm that your team actually needs more than one execution host. If one server with a healthy Orborus node covers your peak execution volume, the default single-server Docker Compose setup avoids Swarm's network and access work entirely. The configuration docs also describe SHUFFLE_MAX_SWARM_NODES as a cap on the number of swarm nodes, so plan the node count with that limit in view.

Swarm needs TCP port 2377 for cluster management, and ports 7946 and 4789 for node-to-node communication and overlay networking, open between the hosts. The Shuffle configuration docs list these three ports, but they do not describe the full traffic pattern for your environment, so have your network team confirm which subnets and hosts must reach each port and which must not. Keep these ports closed to the internet and to user networks. Orborus also needs manager-level Docker API access to start and manage the worker and app containers. That access is effectively control of the cluster, so the Swarm manager becomes a high-value trust boundary. Restrict it to the Orborus host and to named administrator networks, and document who can reach the Docker API and by which path.

Before go-live, your team must confirm network segmentation and Docker API exposure in its own environment. Test that the required ports are reachable only from the intended hosts, that the Docker API does not listen on an address reachable from workstations or other application tiers, and that the Shuffle encryption secret and Swarm join tokens are stored and rotated under your existing controls. Record the result in your change record so auditors and incident responders can trace who could reach the cluster. Treat any gap you find as a blocker for Swarm mode, since a compromised manager exposes every app credential Shuffle stores.

How to move a running Shuffle install from one server to a larger model

This sequence takes a working single-server Shuffle install to a multi-host or cluster runtime with backups, a tested encryption key, a staging rehearsal and a controlled cutover, so the production workflows keep running throughout.

  1. Confirm release and license tier

    Record the Shuffle version currently running and compare it with the supplied current release, 2.3.0, published on September 28, 2026. Note whether your deployment uses the open-source edition or a Business or Enterprise license, because scaling variables and some runtime options depend on the license tier. If you plan a hybrid Kubernetes runtime, confirm you will run Shuffle 2.3.0 or newer, since that is a hard requirement. Ask your vendor or Shuffle to confirm in writing which scaling features your license covers. The step is done when the version, tier and target runtime are written down in the change record.

  2. Back up OpenSearch and the encryption modifier

    Take a full backup of the OpenSearch data that holds workflows, app configurations and saved credentials, and store it outside the host you are migrating from. Record the exact value of SHUFFLE_ENCRYPTION_MODIFIER in your secrets store with restricted access. Shuffle encrypts saved app credentials and API keys with AES-256 using this value, and the configuration docs warn that losing or changing it breaks all saved app authentications. The step is done when a restore of the backup has been tested on a separate host and the same modifier value is confirmed in the secrets store.

  3. Stand up the target runtime in staging

    Build the new runtime in a staging environment that mirrors production as closely as your team can manage. For Docker Swarm, that means the Swarm manager and worker hosts, with ports 2377, 7946 and 4789 open between hosts and manager-level Docker API access for Orborus. For Kubernetes, it means the official Helm chart, a RUNNING_MODE setting for Orborus and a static SHUFFLE_SCALE_REPLICAS value for workers, since HPA is not yet available. Restore the OpenSearch backup and start the same Shuffle version used in production. The step is done when the staging stack starts cleanly and the restored data is visible in the backend.

  4. Add a second Orborus node

    Add a second Orborus node in the target runtime so that workflow executions can continue if one node fails. The Shuffle high availability guidance also calls for an OpenSearch cluster, optional Memcached for a shared cache and NFS for shared files when several backends run, so confirm each of those components with your architect before this step. Check that both Orborus nodes register with the backend and that jobs are distributed between them. Review SHUFFLE_ORBORUS_EXECUTION_CONCURRENCY, which defaults to 10 concurrent executions, against your expected load. The step is done when a test execution runs on each node and a stopped node does not stop a new execution from running on the other.

  5. Test a representative set of workflows

    Select a set of production workflows that covers your most important apps, your longest-running playbooks and any that use saved credentials. Run them in staging and compare the outputs, timings and error logs with the production results from the same inputs. Pay attention to apps that authenticate with saved keys, since a changed encryption modifier will fail here first. With Helm-managed workers, app settings apply to every app, so note any app that needs different tuning and confirm the approach with your vendor. The step is done when every selected workflow produces the expected result and each exception has a recorded owner and fix.

  6. Schedule the cutover and freeze changes

    Agree a cutover window with the teams that own the workflows, the on-call rota and the apps that depend on Shuffle. Pause new workflow edits on the source server for the window, and confirm that in-flight executions have finished or are documented for a rerun. Repeat the OpenSearch backup immediately before the cutover so the most recent state is preserved. The step is done when the change record names the owner of each action, the rollback trigger and the person who signs off the window.

  7. Cut over and verify production

    Point the production hostname at the new runtime, restore the latest OpenSearch backup if it was not already in place, and confirm the same encryption modifier is in use. Run the smoke tests from staging, check that Orborus nodes are healthy and that saved app authentications work. Keep the source server running in read-only mode until the owners confirm that the new runtime is operating as expected. The step is done when the smoke tests pass, the owners sign off, and the old server has a dated decommission note with its backup retained according to your retention policy.

How Shuffle deployment upgrades, backups and monitoring differ by model

This table compares what the team must upgrade, back up and watch under a single Docker Compose server, Orborus on Docker Swarm and the official Helm chart on Kubernetes. Read each row as the operating work that stays with your team after go-live, and confirm every upgrade in staging first.

Operating areaSingle server (Docker Compose)Docker Swarm (Orborus across hosts)Kubernetes (official Helm chart)
Upgrade pathPull the tag you choose: the docs recommend the latest Docker tag for stable releases and nightly for experimental changesSame image tags across the backend, frontend and Orborus, plus Swarm node changes; test each swap in stagingHelm chart upgrade with the matching image values; confirm chart and Shuffle versions, since hybrid Kubernetes runtime needs Shuffle 2.3.0 or newer
Backup scopeOpenSearch data, the SHUFFLE_ENCRYPTION_MODIFIER secret and configuration filesOpenSearch data, the encryption modifier, and shared NFS files if several backends runOpenSearch data, the encryption modifier, NFS shared files if used, and etcd snapshots for the cluster
Encryption modifierStore it outside the host; changing or losing it breaks all saved app authenticationsSame rule; keep one authoritative copy shared by every backendKeep in a Kubernetes Secret with restricted access; Secrets are unencrypted in etcd by default unless you enable encryption at rest
Monitoring pointsBackend API on port 5001, Orborus process, worker and app containers, OpenSearch healthBackend, Orborus nodes, Swarm node status and workers, OpenSearch health, and inter-host ports 2377, 7946 and 4789Backend and frontend pods, Orborus, worker replicas set by SHUFFLE_SCALE_REPLICAS, OpenSearch, and control plane and etcd health
Failure recoveryRestore from backup onto the same host; downtime is the time to rebuildMore than one Orborus node keeps workflows running if one fails, per the HA guidanceControl plane and etcd need at least three control plane nodes and an odd-member etcd cluster for quorum
Core operating skillsDocker Compose, Linux administration, OpenSearch basicsDocker Swarm administration, overlay networking, firewall rules and Docker API access controlKubernetes administration, Helm, RBAC, etcd snapshots with etcdctl and restores with etcdutl, and the version skew policy
Confirm before go-liveAsk the vendor how the encryption modifier is rotated and which OpenSearch version your release expectsConfirm the Swarm port and API access model with your security team and test a node lossConfirm your Kubernetes version support window and whether your distribution is CNCF certified

What running Shuffle on Kubernetes adds to the cluster work

The official Helm chart places Shuffle's components inside a Kubernetes cluster that your team must already run, so the operating load includes everything beneath Shuffle. Before choosing this path, confirm who owns the control plane, how it is upgraded and who gets paged when it fails. A single Shuffle namespace does not remove the need for a cluster that someone patches, monitors and backs up. If you build the control plane yourself with kubeadm, the kubeadm high availability guide describes two topologies: a stacked control plane with etcd on the same nodes, and an external etcd cluster. Both call for at least three control plane nodes and a TCP load balancer in front of kube-apiserver on port 6443. etcd should run with an odd number of members, and the project recommends five members in production. Plan a backup routine from day one: take snapshots with etcdctl snapshot save and rehearse restores with etcdutl, because etcd holds the state that Shuffle's deployment depends on. Upgrades add a recurring cost. Kubernetes maintains the three most recent minor releases, and as of September 2026 the project listed 1.37 as supported until October 28, 2027. The version skew policy requires kube-apiserver to be upgraded one minor version at a time, ahead of the controller manager, scheduler and kubelets. Secrets are also stored unencrypted in etcd by default, so Shuffle's Kubernetes deployment needs encryption at rest configured deliberately, with least-privilege RBAC limiting who can list or watch Secrets. Confirm both settings with your cluster team before go-live.

How much effort and skill does Shuffle deployment at scale need?

Is the default single-server Shuffle setup enough for our volume?

For many teams it is the right starting point, because the Shuffle configuration docs say the default docker-compose file works well to scale on a single server. The deciding factors are how many workflow executions run at once, how much headroom the host has, and whether a single host failure would stop your automation. Concurrency is controlled by SHUFFLE_ORBORUS_EXECUTION_CONCURRENCY, which defaults to 10 concurrent executions. If you need more than one Orborus node so workflows keep running after a failure, the high availability guidance in the configuration docs (an OpenSearch cluster, shared files and more than one Orborus node) is when multi-host work starts. Ask your team who can restart and restore the stack at 2 a.m. before deciding.

What does Docker Swarm add in ports and API access?

Swarm mode adds cross-host networking and a second set of operating decisions. The Shuffle configuration docs say Orborus can run in Swarm mode when SHUFFLE_SWARM_CONFIG=run is set, and that Swarm needs ports 2377, 7946 and 4789 open between hosts. Orborus also needs manager-level Docker API access, which is a sensitive privilege, so your security team should review who can reach that API and how it is firewalled. Plan for the Docker node lifecycle, certificate handling and patching across every host, and cap cluster size with SHUFFLE_MAX_SWARM_NODES. Confirm the network rules with your platform team against your own segmentation policy before you commit to this path.

Do we need Kubernetes to scale Shuffle?

No, but Kubernetes is the path when your organization already runs and staffs a cluster. The Shuffle configuration docs describe an official Helm chart, with Orborus set by RUNNING_MODE and worker replicas set statically with SHUFFLE_SCALE_REPLICAS, and they label HPA as coming soon, so autoscaling is not something to assume. A hybrid Kubernetes runtime requires Shuffle 2.3.0 or newer. Kubernetes adds control plane, etcd and upgrade work that your team must own. The Kubernetes version skew policy requires the API server to be upgraded one minor version at a time, and the kubeadm guide describes at least three control plane nodes for high availability. Count those skills before choosing this path.

Which Shuffle scaling features require a paid license?

Some scaling variables work only with a paid Shuffle license, and licensed customers load the licensed worker image. The Shuffle configuration docs say scale has been partially open source since September 2024, so confirm the exact variables you plan to use against the current configuration docs and your license terms before the design is final. Shuffle says all features are available in the open-source edition, and its paid tiers differ in feature limits, scaling and support. Since v2.1.1, those limits are enforced. Ask the vendor in writing which variables your design depends on and which tier each one requires.

What drives the cost of scaling Shuffle, and what recurs?

Cost comes from three places: the license tier, the engineering time to build and operate the hosts or cluster, and the infrastructure underneath. Licensing is priced on app runs, which are actions that actually execute in a workflow, while users, apps and workflows are unlimited according to the Shuffle pricing article, so execution volume is the main license driver. Recurring costs include the license renewal, hosting, patching, upgrades and monitoring. One-time costs include the initial build, network and identity integration, and backup design. Scale in the design and the infrastructure line rises with each Orborus node, backend replica and OpenSearch node you add. Ask for a written scope that separates these lines.

What should a quote for Shuffle at scale include?

A useful quote lists the deployment path, the number of hosts or clusters, and the operating model in writing before work starts. It should name each item: architecture decision, Orborus configuration, OpenSearch sizing and high availability, shared file storage, backup and restore of OpenSearch, and the handling of SHUFFLE_ENCRYPTION_MODIFIER, since losing or changing it breaks saved app authentications. It should also state which licensed features and limits apply, how upgrades are tested, what documentation and handover you receive, and what ongoing support costs. DeployOpen does not publish prices and quotes follow from the written scope, so ask for each deliverable and its exclusions to appear in that scope.

Can our team run Shuffle at scale without outside help?

A team can run it without outside help if it already has container, networking and backup skills for the path it picks. Single-server Compose needs the least specialized work. Swarm adds Docker cluster administration and firewall rules for 2377, 7946 and 4789. Kubernetes adds cluster and etcd operations, and Kubernetes Secrets are stored unencrypted in etcd by default, so the team must configure encryption at rest and least-privilege RBAC. Upgrade cadence matters too: Kubernetes ships about three minor releases a year and patches each for a limited window. Assess these skills honestly, and consider a fixed-scope engagement or a retainer for upgrades and testing if gaps remain. DeployOpen implements and supports self-hosted platforms inside your infrastructure, and scope and deliverables are agreed in writing first.

How DeployOpen scopes, delivers and supports Shuffle deployments

DeployOpen plans, implements, integrates, hardens, backs up, documents and supports self-hosted open-source platforms inside your own infrastructure, so the choice between a single server, Docker Swarm and Kubernetes is settled against your environment before any build starts. Engagements are fixed-scope, with scope, deliverables and timelines agreed in writing first.

How we scope

  • Written scope names the expected execution volume, hosts or clusters, and where Orborus and workers will run.
  • Scope records which Shuffle license tier, if any, your scaling plan requires, confirmed with Shuffle.
  • Scope lists the network ports, firewall rules and Docker API access each target runtime needs.

How we build

  • Build covers the chosen runtime: Docker Compose on one server, Swarm across hosts, or the official Helm chart.
  • Secrets handling includes protecting the encryption modifier used for saved app credentials.
  • Integrations, app configuration and test workflows are built and checked against your identity and data sources.

How we hand over

  • Handover documents the deployed architecture, scaling settings and the steps to add or remove workers.
  • Backup and restore procedures for OpenSearch and the encryption secret are written and tested with your team.
  • Runbooks cover upgrades between Shuffle releases, so your team knows what changes before a rollout.

How we support

  • Ongoing support, upgrades and continuous testing are available as a retainer after handover.
  • Retainers can cover monitoring of Orborus nodes, worker health and execution failures on your runtime.
  • Ask for the support scope, response expectations and upgrade cadence in writing before committing.

Sources and further reading

Talk to our team.

Tell us what you're working on, whether it's a deployment, an audit, a security test or a cyber range. You'll speak with an engineer who can help you scope it.

  • 30-minute call: free, with no obligation.
  • NDA on request: we can sign before you share details.
  • Clear next steps: a scope and plan after the call.