Deploying a Speckle Enterprise licensed server

​

Prerequisites

1. License Acquisition: Acquired a commercial license for Speckle Enterprise Server from Speckle Systems.
2. Package Registry Token: Obtained a package registry token from Speckle Systems to access the private Helm charts & Docker images for Enterprise features.
3. Package Registry URL: Received the URL for the private package registry hosting the Enterprise Helm charts and Docker images.
4. Cluster and dependencies: A Kubernetes cluster with Postgres, a single-node Valkey or Redis cache, blob storage (S3-compatible or Azure), an ingress controller, a certificate manager, and the high-priority and low-priority priority classes the chart schedules with. The Kubernetes deployment guide walks through each of these on DigitalOcean; the same components are needed on any provider.

​

New deployments

bundle_migration:
  enabled: false

​

Configuration steps

​

Retrieving the Helm chart

helm registry login <PACKAGE_REGISTRY_HOST> --username <PACKAGE_REGISTRY_USERNAME> --password <PACKAGE_REGISTRY_TOKEN>

helm pull oci://<PACKAGE_REGISTRY_URL>/speckle-server-chart --version 2026.9.4 --untar

​

Image pull secrets

1. Create a Kubernetes Secret of type dockerconfigjson:
   kubectl create secret docker-registry speckle-enterprise-registry \
   --docker-server=<PACKAGE_REGISTRY_URL> \
   --docker-username=<PACKAGE_REGISTRY_USERNAME> \
   --docker-password=<PACKAGE_REGISTRY_TOKEN> \
   -n <NAMESPACE> \
   --dry-run=client \
   -o yaml | kubectl apply -f -
   
2. Confirm the secret is deployed successfully in the same namespace as your Speckle Server deployment.
   kubectl get secret speckle-enterprise-registry -n <NAMESPACE>
   
3. Update the Helm values.yaml file to reference the image pull secret:
   imagePullSecrets:
     - name: speckle-enterprise-registry
   

​

Deploying the Helm chart

helm upgrade --install speckle-server oci://<PACKAGE_REGISTRY_URL>/speckle-server-chart \
--version 2026.9.4 \
--namespace <NAMESPACE> \
-f values.yaml

helm test speckle-server --namespace <NAMESPACE>

​

License key

1. Obtain your Speckle Enterprise license key from Speckle.
2. Create a Kubernetes Secret to store the license key:
   kubectl create secret generic license \
   --from-literal=license_token=<YOUR_LICENSE_KEY> \
   -n <NAMESPACE> \
   --dry-run=client \
   -o yaml | kubectl apply -f -
   
3. Update the Helm values.yaml file to reference the license secret:
   server:
     licenseTokenSecret:
       secretName: 'license'
       secretKey: 'license_token'
   
4. Confirm the Gatekeeper module, which validates the license, is enabled. It is on by default since 2026.7; set it explicitly if your values file manages every flag:
   featureFlags:
     gatekeeperModuleEnabled: true
   
5. Upgrade your existing Helm deployment to apply the changes (see above for instructions on how to upgrade).
6. If making any further changes to the license, note that Kubernetes does not automatically restart deployments when changes are made to secrets. Restart the ‘speckle-server’ and ‘speckle-objects’ deployments to apply the changes.
   kubectl rollout restart deployment speckle-server -n <NAMESPACE>
   kubectl rollout restart deployment speckle-objects -n <NAMESPACE>
   

​

Enable Workspaces

1. If your values file manages every flag, set it explicitly:
   featureFlags:
     workspacesModuleEnabled: true
   
2. Upgrade your existing Helm deployment to apply the changes (see above for instructions on how to upgrade).

​

(Optional) Admin support mode

1. To enable Admin Support Mode, update the Helm values.yaml file to include the following feature flags:
   featureFlags:
     adminSupportModeEnabled: true
   
2. Upgrade your existing Helm deployment to apply the changes (see above for instructions on how to upgrade).
3. Verify that Admin Support Mode is available by navigating to Server Settings > Workspaces, selecting a workspace, and checking for the Support Access section. See the Admin Support Mode guide for usage details.

​

(Optional) Saved views

1. To enable Saved Views, update the Helm values.yaml file to include the following feature flag:
   featureFlags:
     savedViewsEnabled: true
   
2. Upgrade your existing Helm deployment to apply the changes (see above for instructions on how to upgrade).
3. Verify that the Saved Views feature is available by following our documentation.

​

(Optional) Issues

1. To enable Issues, update the Helm values.yaml file to include the following feature flag:
   featureFlags:
     issuesModuleEnabled: true
   
2. Upgrade your existing Helm deployment to apply the changes (see above for instructions on how to upgrade).
3. Verify that the Issues feature is available by following our documentation.

​

(Optional) Multi-regional deployment

​

Pre-requisites

​

Configuration

1. Create a json file containing the connection details for your existing ‘main’ region, as follows:
   {
     "defaultProjectRegionKey": null,
     "main": {
       "blobStorage": {
         "protocol": "<s3 or azure>",
         "accessKey": "<YOUR_BLOB_STORAGE_ACCESS_KEY>",
         "bucket": "<YOUR_BLOB_STORAGE_BUCKET>",
         "createBucketIfNotExists": true,
         "endpoint": "<YOUR_BLOB_STORAGE_ENDPOINT>",
         "publicEndpoint": "<YOUR_BLOB_STORAGE_PUBLIC_ENDPOINT>",
         "s3Region": "<YOUR_BLOB_STORAGE_REGION>",
         "secretKey": "<YOUR_BLOB_STORAGE_SECRET_KEY>"
       },
       "postgres": {
         "connectionUri": "<YOUR_POSTGRES_CONNECTION_URI>",
         "databaseName": "<YOUR_DATABASE_NAME>",
         "publicTlsCertificate": "<YOUR_PUBLIC_TLS_CERTIFICATE>"
       }
     },
     "regions": {}
   }
   
   These details should match the connection details you provided when deploying your existing open source Speckle server instance. The main region is a required region. The connectionUri for Postgres should be in the following format:
   postgresql://<DB_USER>:<DB_PASSWORD>@<DB_HOST>:<DB_PORT>/<DB_NAME>?sslmode=require
   
   The null value for the default project region key means that the main region will be used as the default region for new projects. This can be updated later as we add support for additional regions.
2. Update the same json file with the connection details for each additional region you wish to support. Each region should be given a unique region id. Each region is appended to the regions object as follows:
   "regions": {
     "<REGION_ID>": {
       "blobStorage": {
         "accessKey": "<YOUR_BLOB_STORAGE_ACCESS_KEY>",
         "bucket": "<YOUR_BLOB_STORAGE_BUCKET>",
         "createBucketIfNotExists": true,
         "endpoint": "<YOUR_BLOB_STORAGE_ENDPOINT>",
         "s3Region": "<YOUR_BLOB_STORAGE_REGION>",
         "secretKey": "<YOUR_BLOB_STORAGE_SECRET_KEY>"
       },
       "postgres": {
         "connectionUri": "<YOUR_POSTGRES_CONNECTION_URI>",
         "databaseName": "<YOUR_DATABASE_NAME>",
         "publicTlsCertificate": "<YOUR_PUBLIC_TLS_CERTIFICATE>"
       }
     }
   }
   
   If you wish to set a different default region, update the defaultProjectRegionKey value to match the region id of the region you wish to set as default.
3. Create a Kubernetes secret to store the multi-region configuration:
   kubectl create secret generic multi-region-config \
   --from-file=multi-region-config.json=<PATH_TO_JSON_FILE> \
   -n <NAMESPACE> \
   --dry-run=client \
   -o yaml | kubectl apply -f -
   
4. Update the Helm values.yaml file to reference the multi-regional configuration secret:
   multiRegion:
     config:
       secretName: 'multi-region-config'
       secretKey: 'multi-region-config.json'
   
5. To enable multi-regional support, update the Helm values.yaml file to include the following feature flag:
   featureFlags:
     workspacesMultiRegionEnabled: true
   
6. Upgrade your existing Helm deployment to apply the changes (see above for instructions on how to upgrade).
7. If adding further regions, note that Kubernetes does not automatically restart deployments when changes are made to secrets. Restart the ‘speckle-server’ and ‘speckle-objects’ deployments to apply the changes.
   kubectl rollout restart deployment speckle-server -n <NAMESPACE>
   kubectl rollout restart deployment speckle-objects -n <NAMESPACE>
   

​

Giving access to regions in Speckle Server UI

1. Ensure you are logged in to the Speckle server with an account that has server admin privileges.
2. Navigate to Server Settings > Regions.
3. Select Create to add a new region.
4. Select the region id that corresponds to the region details you added in the multi-regional configuration json file.
5. Fill in the required details for the new region, including the region name. This is the name that will be displayed to users.
6. Save the new region.
7. Once the region is created, users can select it when creating a new workspace. Please refer to the workspace guide for further details.

​

(Optional) Automate

​

(Optional) Intelligence

1. To enable Intelligence features, update the Helm values.yaml file to include the following feature flag:
   featureFlags:
     dashboardsModuleEnabled: true
   
2. Upgrade your existing Helm deployment to apply the changes (see above for instructions on how to upgrade).

​

(Optional) ACC integration

​

What the integration needs from you

• Credentials issued by Speckle. The client ID and client secret belong to Speckle’s Autodesk application. You do not create an application in the Autodesk developer portal. Speckle issues both when it enables the integration for your deployment.
• Your public origin, registered by Speckle. After a user signs in, Autodesk redirects them to https://<DOMAIN>/api/v1/acc/auth/callback, and it accepts that redirect only if Speckle has registered it on the application. <DOMAIN> is the domain value of your chart.
• A server that Autodesk can reach. Syncs are webhook-driven: Autodesk posts to https://<DOMAIN>/api/v1/acc/webhook/callback when a new file version is published. A deployment reachable only from inside your network lets users sign in but never picks up new versions.
• The client secret in a Kubernetes Secret, named in accIntegration.clientSecret. The client ID is a plain chart value.

​

Enable the integration

kubectl create secret generic acc-integration \
--from-literal=clientSecret=<ACC_CLIENT_SECRET> \
-n <NAMESPACE> \
--dry-run=client \
-o yaml | kubectl apply -f -

featureFlags:
  jobRunnerEnabled: true
  accIntegrationEnabled: true

accIntegration:
  clientId: '<ACC_CLIENT_ID>'
  clientSecret:
    secretName: 'acc-integration'
    secretKey: 'clientSecret'
  enableNwd: true
  enableDwg: true

​

File imports (conversion runner)

​

What the runner needs from you

• A node pool for conversion Jobs, labeled purpose=conversion (the value of conversionRunner.nodePool). Conversions are bursty, memory-hungry batch Jobs; a dedicated pool keeps them off your serving nodes. Jobs default to 4Gi base memory and may grow to the configured maximum (64Gi default ceiling) for large files; each Job has a two hour deadline by default. The node pool contract below is what the pool must satisfy.
• A namespace and RBAC for the Jobs. The chart creates them when you set conversionRunner.createNamespace: true and conversionRunner.createResources: true (both off by default so clusters that manage these objects elsewhere do not collide). The RBAC lets the server and objects service accounts launch and watch Jobs.
• Registry credentials in the conversion namespace. The Job pods pull the converter image from the same private registry as the chart, but from their own namespace, so the image pull secret you created for the server does not reach them. Create the same docker-registry Secret in the conversion namespace and name it in conversionRunner.imagePullSecrets. The Secret itself is always operator-created.
  kubectl create secret docker-registry speckle-enterprise-registry \
  --docker-server=<PACKAGE_REGISTRY_URL> \
  --docker-username=<PACKAGE_REGISTRY_USERNAME> \
  --docker-password=<PACKAGE_REGISTRY_TOKEN> \
  -n <CONVERSION_NAMESPACE> \
  --dry-run=client \
  -o yaml | kubectl apply -f -
  
  <CONVERSION_NAMESPACE> is the value of conversionRunner.namespace, conversion by default.
• The exact converter image pin: conversionRunner.converterImage: ghcr.io/specklesystems/speckle-converters:2026.9.0. Mirroring is optional: if you would rather serve images from your own registry, copy that image into it, point converterImage at the mirrored path, and create the pull Secret above with your registry’s credentials instead. Run the same YYYY.M converter and server line and upgrade both together: they must reference the same bundle format version. Never run the runner on a mutable latest tag, which silently breaks that pairing on the next push.

​

Node pool contract

• Label and taint. The purpose label is mandatory. A taint is optional and must use the PreferNoSchedule effect: Jobs carry no tolerations, so a NoSchedule or NoExecute taint strands every Job, including the helm test canary, in Pending.
• Three chart values must match the pool. The chart does not validate any of them.
  • The pool’s purpose label equals conversionRunner.nodePool.
  • The namespace the Jobs run in equals conversionRunner.namespace.
  • conversionRunner.maxMemoryMib stays under node allocatable memory. The 64Gi default ceiling pairs with 128 GB nodes; raise it only on larger nodes.
• Machine shape. Memory-optimized nodes with at least 8 GB of RAM per core. The reference shape is 16 vCPU / 128 GB, which is what Speckle’s hosted service runs. Give each node at least 200 GB of disk: Jobs declare no ephemeral-storage request, so nothing stops a large source file from filling a small node disk.
• Autoscaling. Minimum node count of at least 1, so the first upload does not wait on a scale-up and the autoscaler can see the label. Maximum roughly the number of large conversions you expect to run at once, plus 2.

​

Enable the runner

featureFlags:
  jobRunnerEnabled: true

conversionRunner:
  converterImage: ghcr.io/specklesystems/speckle-converters:2026.9.0
  createNamespace: true
  createResources: true
  nodePool: 'conversion'
  imagePullSecrets:
    - name: speckle-enterprise-registry

​

Rhino conversion for 3dm and obj

kubectl create secret generic rhino-token \
--from-literal=rhino_token=<YOUR_RHINO_TOKEN> \
-n <NAMESPACE> \
--dry-run=client \
-o yaml | kubectl apply -f -

featureFlags:
  rhinoConversionEnabled: true

conversionRunner:
  rhinoToken:
    secretName: 'rhino-token'
    secretKey: 'rhino_token'

​

Blob storage reachable by clients

1. Endpoint reachability. Pre-signed URLs are generated against s3.publicEndpoint when set, otherwise s3.endpoint. If your storage is reached through a private or in-cluster address, set s3.publicEndpoint to an HTTPS URL your clients can reach, and keep s3.endpoint on the private address for server-side traffic. Browsers must also trust the certificate on that public endpoint.
2. Bucket CORS (S3-compatible storage only). Browsers call the pre-signed URLs cross-origin. The bucket must allow GET, PUT, and POST from your users’ origins, and allow all request headers. Expose at least the ETag, Content-Encoding, and Content-Length response headers. ETag is required: the upload flow reports it back to the server to complete a publish. Azure Blob Storage needs no manual setup; the server configures the service’s CORS rules at startup.

​

Preview rendering

• Use passthrough NVIDIA GPUs only (never vGPU), driver 515.48.07 or newer, with nvidia-drm modeset=1.
• Set preview_service.webgpu.requireHardwareAdapter: true and reserve the GPU via the preview pod resources. With the flag on, a pod that cannot see a hardware adapter fails readiness loudly instead of silently falling back to slow CPU rendering.

​

(Optional) Microsoft Azure Blob Storage support

# for legacy backwards-compatibility reasons, the blob storage configuration is still nested under an 's3' key, but the provider can be set to 'azure' to use Azure Blob Storage instead of S3 compatible storage
s3:
  protocol: 'azure' # defaults to 's3', which is the only option for open source deployments, and can be set to 'azure' to use Azure Blob Storage
  endpoint: https://<YOUR_AZURE_STORAGE_ACCOUNT_NAME>.blob.core.windows.net # required when provider is set to 'azure', this should be the endpoint URL for your Azure Blob Storage account and must be reachable by the Speckle server.
  publicEndpoint: https://<YOUR_AZURE_FRONT_DOOR_HOSTNAME> # optional, if not provided will default to the same value as endpoint. This must be a domain that is reachable by both your end users and the Speckle server. When configuring Azure Front Door in front of your Azure Blob Storage, the origin header must not be rewritten and must match the publicEndpoint hostname.
  bucket: <YOUR_AZURE_BLOB_CONTAINER_NAME> # required when provider is set to 'azure', this should be the name of the blob container you wish to use for Speckle
  access_key: <YOUR_AZURE_STORAGE_ACCOUNT_KEY> # required when provider is set to 'azure', this should be the access key for your Azure Blob Storage account
  secret_key:
    secretName: 'server-vars' # The secret access key for Azure Blob Storage should be stored in a Kubernetes secret, named `server-vars` with the property `s3_secret_key`
    secretKey: 's3_secret_key'

​

Upgrade notes

​

Upgrading to 3.0.21

• If you have enabled the Ingress, you will first need to delete all Ingress resources in your namespace before upgrading to version 3.0.21. This is because we have changed the Ingress controller in a way which does not allow for in-place patching during the upgrade process.