Quickstart

This is the fastest path from zero to a published service. You will stand up the standalone Docker Compose stack on a single host, open the admin UI, import a…

This is the fastest path from zero to a published service. You will stand up the standalone Docker Compose stack on a single host, open the admin UI, import a WSDL, point it at a backend, review the generated OpenAPI v3, publish, and make a test call.

Since v1.0 the standalone Docker Compose stack is a supported deployment target. For production, see Installation (GCP, Kubernetes / OpenShift Helm).

This Quickstart uses the Publish direction (REST facade over a SOAP backend). For the Consume direction (SOAP facade over a REST backend), see Onboarding → Consume direction.

Before you start, skim Core concepts so the UI labels — service, operation, mapping version, direction — read cleanly, and confirm your host meets the System requirements.

What you'll need

A host with Docker Engine 24+ and Docker Compose v2 (docker compose version).
~2 GB free RAM and ~2 GB free disk for images and the data volume.
Network reachability from the host to your SOAP backend endpoint.
A WSDL for the SOAP service you want to expose (file, URL, or pasted XML).
Outbound HTTPS to the Specaria platform for licensing (see Licensing → Egress allow-list). A 14-day offline grace period covers transient loss.

All values below in <angle-brackets> are placeholders — substitute your own.

Step 1 — Bring up the stack

# 1. Get the code
git clone <repo-url> soap-to-rest && cd soap-to-rest

# 2. Configure secrets
cp docker-compose.env.example .env

Edit .env and set the two required secrets:

S2R_DB_PASSWORD=<value-from: openssl rand -base64 24>
S2R_CREDENTIAL_KEY=<value-from: openssl rand -base64 32>   # 32-byte AES key

S2R_CREDENTIAL_KEY is the AES key used to encrypt backend-profile credentials at rest. Keep it stable — regenerating it invalidates every existing encrypted credential. If it is unset or blank, the services refuse to start (S2R-ADM-0419 / S2R-RUN-0419).

For a single-host evaluation behind your own reverse proxy / load balancer, use the standalone compose file (it exposes the admin UI on a plain HTTP host port; TLS terminates at your proxy):

# build images, then start
docker compose -f docker-compose.standalone.yml build
docker compose -f docker-compose.standalone.yml up -d

The stack is PostgreSQL + admin-api + runtime + worker + admin-ui. The first request triggers Flyway migrations, so initial start can take 30–60 s longer than steady state.

Check status and tail boot logs:

docker compose -f docker-compose.standalone.yml ps
docker compose -f docker-compose.standalone.yml logs -f admin-api   # Flyway + boot

After ~60 s the admin UI answers on http://<host>:8080/ (the S2R_ADMIN_UI_HOST_PORT, default 8080). Put a TLS-terminating reverse proxy in front for any reachable deployment — see the Docker Compose installation guide.

Step 2 — Open the admin UI

Browse to http://<host>:8080/ (or your proxy hostname). For an evaluation stack you can run without SSO; for any real deployment, gate the UI with your identity provider (IAP / Azure AD / SAML / OIDC) and bind operators to roles. See Security → Authentication and Security → RBAC & roles.

You land on the Dashboard. For onboarding a single service, go to WSDL Onboarding.

Step 3 — Import a WSDL

In WSDL Onboarding, import your contract by file, URL, or pasted XML. The platform parses every operation and produces an onboarding review:

a suggested backend endpoint, SOAP version, and auth hints inferred from the WSDL,
a suggested REST method + path per operation (e.g. GET /customers/{id}), editable,
generated sample request/response payloads per operation,
a zero-touch readiness summary and complexity hints (choice, wildcards, polymorphism).

If the WSDL has missing/broken namespace declarations, use namespace repair before continuing. If you re-import a changed contract later, you get a change report (added / removed operations, breaking changes, per-operation deltas) instead of an in-place edit.

Tip: zero-touch autopilot can generate the draft service, operations, and mappings in one step and return a per-operation readiness score — useful for large WSDLs. See Onboarding → Zero-touch autopilot.

Step 4 — Configure the backend

Set the backend connection for the service's environment (e.g. dev):

Endpoint URL — your SOAP service address, e.g. https://<soap-host>/services/<Service>.
SOAP version — 1.1 or 1.2 (pre-filled from the WSDL where detectable).
Auth profile — backend credentials as required. Credentials are stored encrypted (pgcrypto) and are never logged or returned in plaintext. See Security → Backend credential encryption.

Run the built-in connection / auth diagnostic (including a WSDL pull check) to confirm the host is reachable and authentication succeeds before publishing.

Backend endpoint and credentials are environment-scoped — you can carry distinct values per environment. Mapping versions are environment-agnostic, so the same versioned mapping can be promoted across dev → test → prod. See Core concepts → Environment.

Step 5 — Review the generated OpenAPI v3

The platform generates a deterministic, full-field mapping from the WSDL/XSD and a standards-compliant OpenAPI v3 document for the service. Review it before publishing:

The emitted schema reflects your conversion options — field casing, null handling, array collapsing, envelope shape, error/fault shape, and xsi:type handling.
Each operation is assessed for auto-mapping readiness (auto-ready / auto-ready-with-warnings / manual-required), so you know what is fully automated before you publish.
WSDL-declared faults are emitted as per-operation fault schemas.
If a field needs to deviate from the generated default, apply a field-level override in the UI — no code, no transformation language.

See Onboarding → Generate & review the OpenAPI.

Step 6 — Publish & version

When the publish-readiness gate is satisfied (backend reachable, test passing, mapping complete, no blocking WSDL drift), save the service as a version (v1) and set it active.

Versions are immutable — publishing creates a snapshot that never changes.
To evolve the service later, re-import the contract → a new version (v2) is produced with a change report; activate it when ready, or roll back to a prior version with one click.

See Onboarding → Publish & version a service.

Step 7 — Make a test call

A published Publish-direction service is reachable on the runtime under a direction-segmented path:

POST /publish/<env>/<serviceKey>/<operation-path>

For example, calling a GetCustomer operation published as GET /customers/{id} in the dev environment:

curl -sS \
  "https://<your-host>/publish/dev/<serviceKey>/customers/12345" \
  -H "Accept: application/json"

The runtime converts your REST request to SOAP, calls the backend, and converts the SOAP response back to JSON shaped by your conversion options. A few things to know:

The direction segment (publish / consume) is required. A path that omits it returns S2R-RUN-0405 (HTTP 400). See Error codes.
Default per-operation timeout is 100 ms and 2 retries (both configurable).
Synchronous payloads above 30 MB are rejected with S2R-RUN-0413 (HTTP 413).
Every call gets a correlation ID carried through logs and audit — use it to trace a single call in Observability → Logs & tracing.

You can also drive operations from the in-app test harness during onboarding without leaving the UI.

Step 8 — Watch it in Observability

Open Observability to confirm the call:

The live traffic log shows the request/response payloads and headers for drill-down.
Searchable runtime logs are keyed by correlation ID, result code, environment, service, and operation.
Dashboards and per-service rollups read from pre-computed aggregation tables, so they stay sub-second.

See Observability.

You're up — what next

Turn on discovery so you don't have to onboard from WSDLs by hand — Discovery & connectors. Point a connector (or the generic-HTTP receiver) at your gateway edge and the inventory populates from live traffic.
Tune conversion platform-wide and per service/operation/field — Conversion options reference.
Go to production — Installation covers GCP-native (Cloud Run
- Cloud SQL + Cloud Storage + IAP) and Kubernetes / OpenShift (Helm).
Get help — Support.

All Specaria SOAP to REST docs

Loading…