Self-Hosted Overview

What a self-hosted install is

A self-hosted (on-premises) install runs the same API you call at api.transmute.403fin.io, inside your own network. It consists of three things:

You also provide a PostgreSQL 16+ database. It holds metadata only (tenants, API key hashes, usage counters, batch job state), never message bodies. The API applies its own schema migrations at startup; there is no separate migration step. Redis is optional and only needed when you run more than one API replica (Scale out).

Always pin a release tag. Never deploy latest.

Licence mode

Setting TRANSMUTE_LICENSE switches the server into licence mode. The licence is an Ed25519-signed token, verified at startup against a public key built into the release image. Verification is entirely offline: the server makes no network call to check it, and no binary in the image reports usage, phones home or checks for updates. Air-gapped installs are fully supported.

TRANSMUTE_LICENSE accepts either the token itself or, when the value starts with /, the path to a file containing it. Mount the file read-only and point the variable at it; the token string is never logged (only its id, organisation, plan, features and expiry are).

What licence mode changes compared with the hosted service:

Expiry

The check runs at startup. A process that crosses the grace end while running keeps serving until its next restart, then refuses. Renew before expiry: replace the licence file and restart. A malformed or tampered licence also stops the server at startup; it never falls back to unlicensed behaviour. There is no remote revocation, so treat the licence file as confidential.

Feature gates

Core conversion, normalization, validation (syntax, schema) and GET /v1/formats are never gated. A licence issued without a feature list enables everything; a licence with a list enables exactly the listed features:

404 versus 503

The two status codes tell you different things, so you can tell a licensing gap from a configuration gap:

• Not licensed → 404. A feature that is not in your licence does not exist in the deployment: its routes are never mounted and answer not-found. An unlicensed validation level is rejected like any unknown level, with invalid-input 400, and GET /v1/formats lists only the levels your deployment serves.
• Licensed but misconfigured → 503. A feature you are licensed for that is missing its configuration answers 503. For example, batch without TRANSMUTE_JOB_KEY answers batch-unavailable, and connections without a job key answer 503 as well. The synchronous API keeps working.

Images

Every release publishes two images from the same commit:

The default engine checks well-formedness, required elements, key enumerations, length limits and value patterns. The -xsd flavour validates MX messages against the full ISO 20022 schemas, including element order and cardinality, at the schema level of POST /v1/validate (and at cbpr, which runs schema first). Conversion output is identical on both images; only validation differs. GET /v1/version reports schemaEngine, and validation responses report meta.schemaEngine.

Trade-offs of the -xsd image:

• It is larger (around 200 MB) and carries libxml2, a C library with its own CVE history. Stay current with releases to receive patched builds. Documents are pre-screened in Go before libxml2 sees them: DTDs are rejected, and network access and external entities are off.
• Schema validation runs one document at a time per replica. Single validations take milliseconds, but a validation-heavy workload needs more replicas rather than more CPU per pod.

Both images run as uid/gid 65532 with the same entrypoint, port (8080) and binary paths.

Install with Helm

Create the licence and database Secrets, then install with a minimal values file. Secret values never go in the values file: the chart references existing Secrets by name.

kubectl create namespace transmute
kubectl -n transmute create secret generic transmute-license \
  --from-file=license=./your-org.license
kubectl -n transmute create secret generic transmute-db \
  --from-file=DATABASE_URL=./database-url.txt

# values.yaml
image:
  repository: ghcr.io/403ent/transmute
  tag: <release>          # pinned; never latest
  flavor: default         # or xsd for the full-XSD image
license:
  existingSecret: transmute-license
  secretKey: license      # mounted as a file; TRANSMUTE_LICENSE points at it
externalDatabase:
  existingSecret: transmute-db
  secretKey: DATABASE_URL

helm install transmute ./transmute -n transmute -f values.yaml

Then create a tenant and an API key with the admin CLI inside the API pod. The full key is printed once; only its hash is stored.

kubectl -n transmute exec deploy/transmute -- /admin create-tenant --name "Example Org"
kubectl -n transmute exec deploy/transmute -- /admin create-key --tenant <tenant-uuid> --name ops

Other chart values worth knowing: jobKey.existingSecret (enables batch, webhooks and connections), oauth.existingSecret (OAuth client credentials), redis.enabled and replicaCount (Scale out), worker.enabled (Standalone worker), connector.* (File-drop connector), mappingPack.* (Mapping packs), ingress.mtls.* (Mutual TLS), trustedProxies, enrich.* and extraEnv. The chart's liveness and readiness probes call GET /v1/health; GET /v1/ready additionally checks the database.

Docker Compose works the same way: run the image with the variables below in an env_file (mode 600, never committed) and the licence bind-mounted read-only.

Environment variables

Set secrets through the environment (from a Kubernetes Secret or a protected env file), never in config files or chart values. Every variable below is read by the API process.

GET /metrics serves a Prometheus exposition of request metadata (no message content) without authentication, so keep it off any public listener.

Variables used only by the hosted service (billing, the customer portal, its email and bot-check providers and its edge infrastructure) do nothing on a self-hosted install; leave them unset. The vendor-side licence signing key is never set on, or needed by, your systems.

Health endpoints