Install — Docker Compose (standalone)

The fastest way to stand up the full platform. Runs on any host with Docker — a cloud VM (AWS EC2, Azure VM, Oracle Cloud Compute) or on-prem (KVM, VMware,…

The fastest way to stand up the full platform. Runs on any host with Docker — a cloud VM (AWS EC2, Azure VM, Oracle Cloud Compute) or on-prem (KVM, VMware, Hyper-V). No cloud account is required in this mode.

Since v1.0 the standalone Compose stack ships with the release and is covered by an automated CI smoke test.

What you get

A single-host stack of: postgres, admin-api, runtime, worker, and admin-ui. The stack speaks plain HTTP internally; you terminate TLS in front of it.

Two compose files are provided:

docker-compose.yml — includes a built-in TLS-terminating proxy (Traefik) and self-signed certificate generation. Good for a self-contained host with no external LB.
docker-compose.standalone.yml — no built-in proxy; admin-ui is exposed on a plain HTTP host port (default 8080) so an external load balancer or reverse proxy (F5 BIG-IP, Citrix ADC, nginx, HAProxy, a cloud application gateway, etc.) handles TLS termination.

Use docker-compose.standalone.yml when you already have an edge load balancer; use docker-compose.yml when you want the stack to terminate TLS itself.

Prerequisites

Docker Engine 24+ and Docker Compose v2 (docker compose version)
~2 GB RAM headroom and ~2 GB disk for images plus the data volume
Pre-built images from your registry, or the build toolchain (Java 25 + Maven 3.9) if you build locally

1. Configure secrets

cp docker-compose.env.example .env

Edit .env and set, at minimum:

# Postgres password for the bundled database. Any strong value.
#   openssl rand -base64 24
S2R_DB_PASSWORD=<strong-password>

# AES key used to encrypt backend-profile credentials in the DB.
# MUST be a base64-encoded 32-byte (256-bit) value.
#   openssl rand -base64 32
# Rotating this later invalidates every previously-encrypted credential row —
# pick once, store in your secret manager, never change.
S2R_CREDENTIAL_KEY=<base64-32-byte-key>

For the full list of available settings, see the Configuration reference.

Never commit .env to source control. It contains your database password and the credential key.

2. Build (or pull) images

# Build locally on a Linux/macOS host:
docker compose -f docker-compose.standalone.yml build

# Windows host (PowerShell):
scripts/build-images.ps1

Skip this step if you pull pre-built images from a registry — set S2R_IMAGE_PREFIX and S2R_IMAGE_TAG in .env to point at them.

3. Start the stack

docker compose -f docker-compose.standalone.yml up -d

After roughly 60 seconds the admin UI is reachable on the host port (default 8080). The first request triggers the Flyway migrations, so the initial start takes 30–60 seconds longer than steady state.

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

4. Put TLS / your load balancer in front

With docker-compose.standalone.yml, point your external LB at the admin-ui host port:

Backend: HTTP <this-host>:<S2R_ADMIN_UI_HOST_PORT> (default 8080)
Health check: GET / → 200
Forward headers: Host, X-Forwarded-For, X-Forwarded-Proto: https

Consumer attribution (which client made a call) is resolved from X-Client-IP / X-Forwarded-For / Forwarded, so make sure your proxy forwards them.

Using an external (managed) PostgreSQL

The bundled postgres container is fine for demos and small installs. For production, use a managed PostgreSQL (RDS, Azure Database for PostgreSQL, Aurora, Cloud SQL, or your own HA cluster).

Add a docker-compose.override.yml next to the compose file, pointing each application service at the external host:

services:
  admin-api:
    environment:
      S2R_DB_HOST: my-postgres.internal
      S2R_DB_SSL_MODE: require
  runtime:
    environment:
      S2R_DB_HOST: my-postgres.internal
      S2R_DB_SSL_MODE: require
  worker:
    environment:
      S2R_DB_HOST: my-postgres.internal
      S2R_DB_SSL_MODE: require

Pre-create the database and the application role:

CREATE DATABASE soap_to_rest WITH ENCODING 'UTF8';
CREATE ROLE s2r_app WITH LOGIN PASSWORD '`<password>`';
GRANT ALL ON DATABASE soap_to_rest TO s2r_app;

Optionally stop the bundled service: docker compose stop postgres.

The credentials the services use are set via S2R_DB_USER / S2R_DB_PASSWORD / S2R_DB_NAME in .env (defaults s2r_app / soap_to_rest). On non-GCP hosts keep S2R_DB_IAM_AUTH_ENABLED=false so the services use password auth rather than the GCP IAM token path.

First boot

On first start the platform comes up with no admin yet. The first authenticated user to reach the admin UI becomes the bootstrap admin automatically, after which normal RBAC (admin / operator / reader) applies. Do not expose the URL to a wider audience until you have logged in as the bootstrap admin. You can pre-seed bootstrap roles with S2R_ADMIN_BOOTSTRAP_EMAILS / S2R_ADMIN_BOOTSTRAP_OPERATOR_EMAILS / S2R_ADMIN_BOOTSTRAP_READER_EMAILS (see Configuration reference).

Next steps

Configuration reference — every variable you can set.
Operations overview and Daily operations.
Onboarding a service — import your first WSDL.

All Specaria SOAP to REST docs

Loading…