Hub / Topics / Cloud hosting

Hosting an SDK Integration in Your Own Cloud

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.

Topic Running SDK-based services Grounded in The hosted demo on AWS, the gateway's Azure reference, vendor docs Audience Members and developers hosting on AWS, Azure or Google Cloud Updated 2026-11-17

First question

Which of Four Things You Are Hosting

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 runBuilt fromNeeds inbound HTTPS?Keeps on diskReads from the environment
Your own JVM service embedding connect-library
the 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.
Gateway-class adapters are the same shape. The Connect Gateway engine embeds 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

Six Things Every Cloud Has to Give It

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.

Your cloud account TSANet side Secret store SSM · Key Vault Secret Manager Your service + connect-library JDK 21 · Spring Boot 4.1 · one replica SQLite cache on local disk TLS ingress, optional load balancer at the edge Your object store (receiver only) S3 · Azure Blob or Files · GCS TSANet Connect API connect2.tsanet.org · Beta on .net Entra token endpoint token for client-credentials mode secrets as env outbound HTTPS signed webhook deliveries inbound POST, raw body receiver writes files
The whole deployment. The solid blue edges are the only mandatory traffic: outbound HTTPS to the Connect API, plus the Entra token endpoint when the account authenticates with client credentials. The ingress, the webhook path and the object store exist only for the shapes that need them.
  1. 1
    A JDK 21 container that you built. The runtime line is JDK 21, Spring Boot 4.1 and Jackson 3, unchanged from 1.0.0 through 5.0.0. The repository's 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.
  2. 2
    One replica, one SQLite file, on local disk. The library requires a 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.
  3. 3
    Outbound HTTPS, and nothing else, for an outbound-only service. Egress goes to the Connect API host for the environment (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.
  4. 4
    Secrets in through the environment, read once. Every app binds ${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.
  5. 5
    A TLS-terminated public URL only when something comes in. Three things come in: webhook deliveries, the demo's browser traffic, and a receiver's 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.
  6. 6
    An identity for the object store, where there is one. The attachment receiver's S3 adapter uses the AWS default credential chain when no key pair is configured, and its GCS adapter uses Application Default Credentials when no service-account JSON is: a task role, an instance profile or a runtime service account carries the access and no key sits anywhere. The Azure Files and Azure Blob adapters take a SAS URL or a connection string only, with no managed-identity path at 5.0.0, so on Azure that SAS is a secret like the rest. One identity that cannot help anywhere: a managed identity in your tenant does not stand in for the Entra client secret TSANet issued, because the token is minted in TSANet's tenant.

Amazon Web Services

AWS: Express Mode Is the Path That Has Been Run

runthe SDK web demo on Amazon ECS Express Mode since 2026-10-29, moved there from App Runner documentedplain ECS, EKS and the storage and secrets rules, read from AWS documentation on 2026-11-06

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.

What the runbook learned the hard way

Storage, and the two things that are not ECS Express

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, with the One Failure Already Found for You

runthe Connect Gateway engine, which embeds this SDK, on Azure Container Apps as the member-hosting reference written, not runthe SDK demo's Container Apps procedure, taken from Microsoft Learn on 2026-08-04 with no subscription to execute it documentedApp Service, AKS, billing, secrets and storage, read from Microsoft Learn on 2026-11-06

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.

The recipe, and the gotcha on line one

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.

Scaling and what it costs

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, and the revision that does not happen

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.

Storage: the finding

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.

App Service and AKS

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

Google Cloud: Cloud Run Fits, with Two Settings That Decide It

documentednothing SDK-side has been run on Google Cloud by TSANet; everything here is read from Google's documentation on 2026-11-06 spec-readThe API specification describes Google Cloud Storage as a direct-delivery receiver store but says it is not available in the current release; the SDK's registration facade covers S3 and Azure Blob only, while the receiver library does ship a GCS adapter

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.

Setting one: CPU allocation

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.

Setting two: maximum instances

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

Filesystem, secrets, identity

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 Same Six Concerns on Three Managed Container Services

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.

ConcernAWS · ECS Express ModeAzure · Container AppsGoogle Cloud · Cloud Run
Managed HTTPS URLYes, <name>.ecs.<region>.on.aws, minted per serviceYes, the ingress FQDNYes, a run.app hostname
Scale to zeroNot established: the minimum defaults to 1 and the API reference gives it no valid range; there is no pause; the demo runs 1/1Yes, --min-replicas 0; no compute charge at zeroYes, the default; idle instances end within 15 minutes
Where the cache livesTask ephemeral storage, 20 GiB default, encrypted, gone with the taskThe container filesystem, 1 to 8 GiB by vCPU, gone with the containerAn 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 fileAmazon EFS (NFS)Azure Files, SMB or NFS: SQLITE_BUSY recordedCloud Storage FUSE (no locking), Filestore (NFS)
Secrets into the environmentSSM or Secrets Manager through secrets[].valueFromApp secrets or Key Vault references, secretref:Secret Manager, as variables or files
RotationUpdate the service or force a new deploymentNew revision or restart; automatic for an unversioned Key Vault referenceNew version, then a new revision
Identity to the object storeTask role, no keys (default credential chain)SAS URL or connection string onlyRuntime service account, no keys (ADC)
Work between requestsAlways has CPUAlways has CPU while a replica is upOnly with instance-based CPU allocation
Run for TSANetThe SDK demo, since 2026-10-29The gateway engine (reference); the demo's procedure written, not runNothing yet

Sharp edges

The Go-Live List, in the Order It Bites

Cloud Run is the gap: nothing SDK-based has been run there and reported back. If you host on Google Cloud, or on anything not listed, say so in Community with what you had to change; the platform rows above are only as good as the deployments behind them. The deployment skill carries the runbook knowledge in a form a coding assistant can apply while it plans your deployment.

Verified against

Sources, with the Dates That Were Read

Read onSourceUsed for
2026-11-06Connect_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, DatabaseInitializerThe 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-06Connect_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-06AWS 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 changeWhat 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-06Microsoft 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 policyScale-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-17Re-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 readEphemeral 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-06Google Cloud documentation: Container runtime contract, Configure secrets, CPU allocation, Cloud Storage volume mountsThe 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 probedminTaskCount: 0 on Express Mode; any SDK component on Google Cloud; the SDK demo on Container AppsEach is marked where it appears