The Connect SDK is a library, so "hosting an SDK solution" means hosting whatever you wrapped around it: your own service, the console app, or the web demo. All of them share one runtime shape — a JDK 21 process that talks outbound HTTPS to the Connect API, keeps a SQLite cache on local disk, and reads its secrets from the environment — and that shape, not the cloud, decides what a correct deployment looks like. This page maps it onto AWS, Azure and Google Cloud, says what TSANet has actually run on each, and tags everything else as read from the vendor's documentation.
First question
Nobody deploys connect-library. They deploy something that embeds it, and the four things that do have different needs from a host. Settle which one you are before you open a cloud console, because the answer decides whether you need a public URL at all, what you would lose if the filesystem vanished, and which secrets have to reach the process.
| What you run | Built from | Needs inbound HTTPS? | Keeps on disk | Reads from the environment |
|---|---|---|---|---|
Your own JVM service embedding connect-librarythe common case | The artifact from GitHub Packages. No source build, no access to the private specification (how). | Only if it receives webhooks. | One SQLite file per account at the sqlitePath you configure: every read and successful write upserts into it. | The member password, or the Entra client id and secret in client-credentials mode, through your own configuration (both modes). |
| The console app TSANet-integration-app | A source build (needs the private specification sibling on its beta branch) or a jar from TSANet. | Yes when tsanet.webhook.enabled is on, which it is by default: port 8090, path /webhooks/tsanet. | SQLite under tsanet.storage.sqlite-path, including each webhook subscription's HMAC secret and every inbound event it received. | Accounts, through an untracked profile or SPRING_APPLICATION_JSON; the public base URL it registers as its callback. |
| The web demo demo-ui | A source build plus the repository's runtime-only Dockerfile. No image is published anywhere; you build and push your own. | Yes: it is a website on port 8090, with /healthz open for probes and everything else behind its login. | Per-environment member credentials, SQLite caches and the E2EE partner-key table under TSANET_DEMO_DATA_DIR, ephemeral by design on a hosted container. | The auth gate, optional seeds and lock, the Entra tenant and audiences, the private JWKS (runbook). |
| A direct-delivery attachment receiver attachment-receiver | A library with no main class. The HTTPS half that accepts the push is being built in the gateway's attachments-only profile; nothing standalone ships yet. | Yes: a PUT endpoint in front of your own store (the contract). | Encrypted per-tenant configuration files. | Storage credentials where the cloud cannot supply an identity: S3 and GCS fall back to the platform's own credential chain; Azure takes a SAS URL or connection string only. |
connect-library and keeps the same SQLite cache, so a self-hosted Fin / Intercom adapter is everything on this page plus the gateway's own member-hosting guide. TSANet runs its Azure reference environment from that guide's assets, though the guide itself says its member path has not been run end to end as written; its findings are cited below where they apply to any SDK-based service.The shape
Whichever service you pick on whichever cloud, the deployment is correct when these six hold. They come from the SDK's own source and runbook and from the gateway's reference deployment, not from any cloud's marketing, which is why the cloud sections below are mostly about how each platform satisfies or violates them.
Dockerfile is runtime-only, on eclipse-temurin:21-jre-alpine as a non-root user, and copies in a jar you built outside Docker, because the code generation needs the private specification sibling that no build context carries. No image is published to any registry, for the demo or anything else: you build, you push to your own registry, and you deploy by digest. Build for linux/amd64 on Apple silicon or the container fails at start with an exec-format error.sqlitePath and upserts into it on every remote read. Two processes on one file is undefined; the gateway's deploy rule is exactly one replica per store. "Local" means the container's own filesystem or a block volume attached to one instance. It does not mean a network share: SQLite in WAL mode on an SMB mount fails at the first connection with SQLITE_BUSY, as the gateway's member-hosting guide records from its Azure deployment, and NFS (EFS, Filestore, Azure Files over NFS) and FUSE object mounts have the same class of problem. Treat the file as a cache you can afford to lose: syncAllDetails() rebuilds it from the API. What it holds that you cannot rebuild is under go-live. Nothing runs CacheRetention.sweep for you; schedule it.connect2.tsanet.org is Production, connect2.tsanet.net Beta; the demo also carries a Development host), to login.microsoftonline.com for the token in client-credentials mode, and to your package registry at build time. Every shipped app refuses a plain-http base URL at startup. Through a corporate proxy the JDK's https.proxyHost and javax.net.ssl.* settings apply, but a default Authenticator for an authenticating proxy does not, because the library moved to java.net.http.HttpClient in 3.0.0; redirects are not followed either. A service that only sends needs no load balancer and no public IP: a private subnet with a NAT route is a complete deployment.${VAR} placeholders at startup, so the source of truth is your cloud's secret store and the delivery mechanism is an injected environment variable (or a mounted file you read yourself). Three consequences hold on all three clouds: rotation is a new value plus a restart, a new revision or a forced deployment, never a live reload; a value must not contain ${, because Spring resolves it inside a bound value; and a value set from a file carries its trailing newline, so set it from an argument. Never in the image, never in a committed file.PUT. Terminate TLS at the cloud's edge and let the container speak plain HTTP on 8090 inside. For webhooks the edge must hand over the body byte-for-byte: every delivery is signed X-Hub-Signature-256: sha256=<hex>, HMAC-SHA256 over the raw payload, and anything that re-serializes JSON on the way in makes every signature fail. The console app registers tsanet.webhook.public-base-url as its callback, so that value is the public https URL, not localhost. For the demo the gate is mandatory and /healthz and /.well-known/jwks.json are the only paths outside it.Amazon Web Services
TSANet's own hosted demo runs on Amazon ECS Express Mode: one Fargate task behind a managed Application Load Balancer with TLS, created from the image the repository's Dockerfile builds, with the procedure in the SDK runbook's section 6. It replaced an App Runner service because App Runner stopped accepting new customers (on 2026-04-30, by AWS's original notice; the current page gives no date); existing customers can still create services, AWS plans no new features, and it names Express Mode as the successor. One difference matters to the build: App Runner could build from source, Express Mode takes an image only, which for this SDK was already the only option.
What Express Mode gives a single container is close to what a demo or a small integration service needs and nothing more: a URL of the form https://<name>.ecs.<region>.on.aws with TLS terminated, a target-group health check on the path you name (/healthz for the demo), CloudWatch logging, and canary deployments with 5XX rollback alarms on every update. Express Mode itself is free; you pay for the Fargate task, the load balancer and the logs for as long as the service exists. The demo runs at 0.25 vCPU and 512 MiB.
ecs-tasks.amazonaws.com, with AmazonECSTaskExecutionRolePolicy plus permission to read your parameters) and an infrastructure role (trusting ecs.amazonaws.com, with AmazonECSInfrastructureRoleforExpressGatewayServices). A create that runs within a minute of making them fails with a permissions message; the first create on a new account can also fail with "Unable to assume the service linked role" and succeed on a retry, because that call creates the role.secrets[].valueFrom. SSM Parameter Store SecureStrings (or Secrets Manager ARNs) named in the container definition arrive as environment variables, resolved when the task starts. AWS states the rule plainly: if the secret changes, force a new deployment or launch a new task. The runbook observed that an update-express-gateway-service with an identical container block still starts a new deployment, which is the rotation mechanism.latest. The container definition names <registry>/connect-sdk-demo:<sha> so describe-express-gateway-service always says which build is running. The first deployment takes about twelve minutes while the load balancer and alarms are provisioned; a redeploy is a canary.minTaskCount and maxTaskCount both at 1; the console defaults are 1 and 20. The ExpressGatewayScalingTarget reference gives no valid range for the minimum, so whether Express Mode accepts a floor of 0 is not stated and has not been tried needs probe.linux/amd64. Match the two or the task exits on start.A Fargate task gets 20 GiB of ephemeral storage by default (up to 200), encrypted, and deleted with the task. That is the right home for the SQLite cache: the demo's data directory lives there and is re-seeded from SSM on every start, and a service of your own can rebuild its cache with one call. Amazon EFS is NFS, so it is not where the live file goes; if a file must survive, copy it to S3 on a schedule from a sidecar, which is the pattern the gateway's guide prescribes (its AWS section is written but has not been run).
Express Mode covers more than its one-call form suggests. It takes a task role directly (the receiver's S3 adapter picks it up with no keys configured), your own subnets and security groups, and a bring-your-own task definition, which is how you add a sidecar container; that task definition must name its container Main with one port mapping and be Fargate-compatible. Plain ECS on Fargate is the step up when you need what Express Mode always provisions around you to be gone or yours: no load balancer at all for an outbound-only service, or your own load balancer and scaling resources.
Amazon EKS is for members who already run Kubernetes. The rules translate directly: a Deployment with one replica and the Recreate strategy, not RollingUpdate, so two pods never overlap on one volume; an emptyDir or a single-attach gp3 volume through the EBS CSI driver for the cache, never EFS; secrets into environment variables through the Secrets Store CSI driver or External Secrets; IAM roles for service accounts for S3. AWS Lambda is the wrong shape: a Spring Boot process with a local database, a renewed bearer token and a webhook secret on disk is a long-lived service, not a function.
Microsoft Azure
Azure Container Apps is the analogue of Express Mode: an image in, a managed HTTPS hostname out, and a replica count that can reach zero. Two TSANet documents cover it from opposite directions. The SDK repository's docs/azure-deployment.md walks the demo onto it command by command and is honest that nobody has executed it; the gateway's member-hosting guide was executed, on the engine that embeds this same library, and is where the hard finding below comes from.
A registry (az acr create), a user-assigned managed identity with AcrPull so no registry password lives in the app, a Container Apps environment, and then one create with --target-port 8090 --ingress external --min-replicas 0 --max-replicas 1, the gate password in --secrets and referenced from the environment as secretref:. The gotcha is the registry hostname: ACR's domain-name-label feature appends a hash, so a registry named connectsdkdemo answers at something like connectsdkdemo-e7gg….azurecr.io, the scope is immutable after creation, and a script that assumes <name>.azurecr.io fails with an image-pull error that reads like a permissions problem. Read loginServer from the create output.
On the Consumption plan a revision scaled to zero incurs no resource-consumption charge; a revision kept at a minimum above zero is billed at an idle rate while it sits idle. An environment with only Consumption workload profiles carries no plan-management fee; a Dedicated profile does, and so do private endpoints and planned maintenance, whatever the plan. So a demo can sit at zero between calls and pay a JVM cold start on the first request, and a service that works between requests (webhook post-processing, a scheduled sync or sweep) keeps one replica at the idle rate. Send one warm-up request before a demo.
Secrets live in the app's own secret store or as Key Vault references (keyvaultref: plus a managed identity holding the Key Vault Secrets User role). Microsoft's rule, which bites exactly where you would expect: adding, removing or changing a secret does not create a revision, and an updated secret does not affect a running revision until you deploy a new revision or restart the existing one. The one case the platform handles for you is a Key Vault reference without a version: the app picks up a new version within 30 minutes and active revisions that use it in an environment variable are restarted automatically, which for a single-replica service is the rotation restart done on your behalf.
A container app has its own filesystem (1 GiB at a quarter vCPU, rising to 8 GiB above one vCPU, shared with any replica-scoped EmptyDir volume) that disappears with the container, and Azure Files over SMB or NFS as the only durable mount, shared across replicas. The live SQLite file goes on the first, never the second: the gateway's member-hosting guide records that on an Azure Files SMB mount the database fails at the first connection with SQLITE_BUSY, which is why its reference spec keeps the files local. The pattern that shipped is the database on local disk plus a backup sidecar that copies the files to an Azure Files share every five minutes and keeps hourly snapshots for 48 hours, restored on start. One more reason the live file is local: in single-revision mode Container Apps starts the new revision before stopping the old one, so for a short window two replicas run, and a shared file would have two writers.
Deploy by digest. az containerapp update --image creates and activates a revision, and the pull policy is always always, but an update whose template is unchanged (the same tag string after you pushed new code under it) is not a configuration change and rolls nothing; the gateway page records that exact no-op on this platform. The receiver's Blob and Files adapters want a SAS URL or connection string, so that value goes in Key Vault with the rest, with rw (or rcw) on the container.
Azure App Service (Java SE on Linux) is for teams that already run it: you deploy the executable jar with az webapp deploy --type jar and there is no container to build, and Java 21 is a supported runtime. Two things to set deliberately. The built-in image starts the jar on port 80, so the demo's and the console's 8090 have to be overridden in the startup command. And /home is persisted, shared storage, which is a network share (the platform's own JAVA_COPY_ALL setting exists "to address file-locking issues" on it), so the SQLite path belongs outside /home, where it is per-instance and gone on restart, exactly as on a container. App Service does not scale to zero; run one instance with Always On.
AKS follows the EKS rules: one replica, Recreate, an Azure Disk (block) volume or emptyDir for the cache and never an Azure Files volume, Key Vault through the Secrets Store CSI driver. Workload identity is welcome for everything except the two things it cannot replace: the receiver's SAS, and the Entra client secret for the Connect API, which TSANet's tenant issues.
Google Cloud
Cloud Run takes the same image from Artifact Registry, gives it an HTTPS run.app URL, and scales to zero by default: minimum instances is 0 unless you raise it, and an idle instance is kept at most 15 minutes. Set the service's container port to 8090 and the demo listens where Cloud Run sends. The container must be listening within four minutes of start (startup CPU boost shortens a JVM boot), gets SIGTERM and ten seconds at shutdown, and must answer every request inside the configured request timeout, which for the demo means a timeout long enough for the largest attachment you will push through one request.
Cloud Run's default is request-based billing, where "CPU is only allocated during request processing". Everything an SDK service does between requests runs without CPU in that mode: the console's cache sync after it has answered a webhook, a scheduled syncAllDetails or CacheRetention.sweep, the library's token renewal ahead of expiry. Any shape that works outside a request needs instance-based billing (formerly "CPU always allocated"), where "CPU is allocated for the entire container instance lifecycle" and billed for it, together with a minimum of one instance so there is a process to do the work. A pure request-and-response wrapper around the library can stay request-based.
Cloud Run scales out on load. Two instances are two SQLite caches, and with v1 webhooks they are worse than that: the subscription's HMAC secret exists only in the cache of the instance that created it, so the other instance reports every delivery as unsigned. Set maximum instances to 1. Google's Cloud Run instances, in preview since 2026-08-25, are a closer fit: a single, individually addressable, non-autoscaled runtime meant for long-lived workloads. It is preview, and nothing SDK-based has been run on it. preview
The writable filesystem is in memory: "writing to it uses the instance's memory", and "data written to the file system doesn't persist when the instance stops". By default the SQLite cache therefore sits inside the memory limit, which makes the retention sweep a sizing matter rather than housekeeping, and it is lost on every instance replacement, not only on every deploy. Since 2026-11-04 an ephemeral disk is generally available as the alternative: an ext4 volume of 1 to 100 GiB per instance, encrypted, not shared with other instances or revisions, deleted when the instance shuts down, billed for its full size, and only on the second-generation execution environment. It takes the cache out of the memory budget; it does not make it survive a replacement. documented The demo's seeds and lock were built for precisely this (credentials and partner keys re-created at start from secrets). Cloud Storage FUSE volumes are durable but "do not provide concurrency control for multiple writes (file locking) to the same file" and "the last write wins", so they are a backup target, never the live database.
Secrets come from Secret Manager as environment variables (resolved at instance startup; Google recommends pinning a version rather than latest) or as mounted files (the latest version is fetched on each read). The runtime service account needs the Secret Manager Secret Accessor role. Since every shipped app reads its configuration at startup, rotation is a new version plus a new revision either way. The receiver's GCS adapter uses Application Default Credentials when no credentialsJson is configured, so the same runtime service account, granted object write on the bucket, carries storage access with no key file in any configuration.
GKE Autopilot for Kubernetes shops: one replica, Recreate, a Persistent Disk (block) volume or emptyDir and never Filestore, Workload Identity Federation for GCS, Secret Manager through the add-on or External Secrets.
Side by side
The three services below are each cloud's shortest path to "an image in, an HTTPS URL out". The rows are the invariants from the shape, plus what each platform has actually run for TSANet.
| Concern | AWS · ECS Express Mode | Azure · Container Apps | Google Cloud · Cloud Run |
|---|---|---|---|
| Managed HTTPS URL | Yes, <name>.ecs.<region>.on.aws, minted per service | Yes, the ingress FQDN | Yes, a run.app hostname |
| Scale to zero | Not established: the minimum defaults to 1 and the API reference gives it no valid range; there is no pause; the demo runs 1/1 | Yes, --min-replicas 0; no compute charge at zero | Yes, the default; idle instances end within 15 minutes |
| Where the cache lives | Task ephemeral storage, 20 GiB default, encrypted, gone with the task | The container filesystem, 1 to 8 GiB by vCPU, gone with the container | An in-memory filesystem that counts against the memory limit, or an ephemeral disk of 1 to 100 GiB on the second-generation environment; either is gone with the instance |
| Not for the live file | Amazon EFS (NFS) | Azure Files, SMB or NFS: SQLITE_BUSY recorded | Cloud Storage FUSE (no locking), Filestore (NFS) |
| Secrets into the environment | SSM or Secrets Manager through secrets[].valueFrom | App secrets or Key Vault references, secretref: | Secret Manager, as variables or files |
| Rotation | Update the service or force a new deployment | New revision or restart; automatic for an unversioned Key Vault reference | New version, then a new revision |
| Identity to the object store | Task role, no keys (default credential chain) | SAS URL or connection string only | Runtime service account, no keys (ADC) |
| Work between requests | Always has CPU | Always has CPU while a replica is up | Only with instance-based CPU allocation |
| Run for TSANet | The SDK demo, since 2026-10-29 | The gateway engine (reference); the demo's procedure written, not run | Nothing yet |
Sharp edges
TSANET_DEMO_AUTH_PASSWORD unset it runs open; behind it sit live member credentials and the ability to page a partner's engineer with a real case. A guest login (TSANET_DEMO_AUTH_GUEST_*) gives members a second password with a lower upload limit. The demo will not talk to Production at all; a service of your own will, so keep Production credentials in the production deployment only.Recreate. Container Apps: single-revision mode overlaps old and new, harmless on local files and fatal on a shared one. Cloud Run: maximum instances 1. Express Mode: a canary briefly runs two tasks, each with its own ephemeral disk, so two caches and never two writers.webhook_subscription row; and the demo's per-environment credentials and partner-key table, which you seed instead (TSANET_DEMO_SEED_*, TSANET_DEMO_E2EE_PARTNERS_*, with TSANET_DEMO_CREDENTIALS_LOCKED so visitors cannot change them). For the secret, either back the file up to object storage on a schedule or plan to create a new subscription after a loss and delete the old one, which keeps delivering until you do.receiveInbound has a clock on it whatever cloud it runs in. The v2 CloudEvents contract, including OAUTH2_CLIENT_CREDENTIALS callback auth, which means your edge also fronts a token endpoint, is on the API page. Hosting does not change this; it just makes the endpoint real.X-Hub-Signature-256. An API gateway that pretty-prints JSON, or a framework that re-serializes before your handler, breaks every verification silently: the library records signatureValid=false on each event and nothing errors.${ in any value; set values from arguments, not files.https.proxyHost; an authenticating proxy needs something in front of the process, since the JDK client the library uses ignores a default Authenticator.ConnectApiException messages carry no URL, header or token, the receiver's storage errors carry no credential, and the demo's key generator prints the private JWKS once to standard output and nowhere else. Don't undo that with a docker inspect pasted into a ticket; AWS's own guidance prefers file-mounted secrets to environment variables for the same reason.CacheRetention.sweep evicts closed and rejected cases by age and never touches an open one, and nothing calls it for you. On Cloud Run without an ephemeral disk it is your memory budget.sha256: digest for the same reason.Verified against
| Read on | Source | Used for |
|---|---|---|
| 2026-11-06 | Connect_SDK main at b565e5e (2026-11-01; v5.0.0 released 2026-10-31): the root Dockerfile, demo-ui and TSANet-integration-app application.yml, docs/RUNBOOK.md §6, docs/aws-hosting-options.md, docs/azure-deployment.md, RegisteringStorageFactory, WebhookSignatureVerifier, DatabaseInitializer | The four shapes, the image, the environment surface, the ECS procedure and what it observed, the Azure procedure and its status, the credential fallback of each storage adapter, the signature contract, what the cache stores |
| 2026-11-06 | Connect_Gateway v5.0.0 docs/member-hosting.md (private repository) | SQLite on an Azure Files SMB mount (SQLITE_BUSY), the backup sidecar, single-revision overlap, deploy by digest, rotation by restart, the AWS section's unrun status |
| 2026-11-06 | AWS documentation: Create your first Express Mode service, Create your first Express Mode service in the console, ExpressGatewayScalingTarget, Pass sensitive data to a container, Fargate task ephemeral storage, App Runner availability change | What Express Mode provisions and its URL form, the roles, the console scaling defaults and the unstated scaling floor, secret injection and the rotation rule, ephemeral storage size and lifetime, the App Runner cutoff |
| 2026-11-06 | Microsoft Learn: Billing in Azure Container Apps (2025-12-09), Manage secrets (2026-09-04), Use storage mounts (2026-10-13), Deploy and configure Java apps (2026-10-08), App Service language support policy | Scale-to-zero and idle billing, secrets and the no-revision rule, Key Vault auto-refresh, storage types and sizes, App Service deployment and /home, Java 21 support |
| 2026-11-17 | Re-read: Cloud Run release notes, ephemeral disk, billing settings; AWS create-express-gateway-service and the App Runner availability change; Container Apps billing (2025-12-09); Connect_SDK main and Connect_Gateway main, both unchanged since the 2026-11-06 read | Ephemeral disk GA and its limits, Cloud Run instances in preview, the billing wording, what Express Mode accepts directly, App Runner's current wording, the plan-management exceptions |
| 2026-11-06 | Google Cloud documentation: Container runtime contract, Configure secrets, CPU allocation, Cloud Storage volume mounts | The in-memory filesystem, ports, startup and shutdown, request-based versus instance-based CPU, secret delivery and the Secret Accessor role, the FUSE locking limitation |
| not probed | minTaskCount: 0 on Express Mode; any SDK component on Google Cloud; the SDK demo on Container Apps | Each is marked where it appears |