System Requirements for the SOAP-2-REST Platform

Overview

This document specifies the mandatory system requirements for deploying and operating the SOAP-2-REST platform as of version 1.0. Before installation, an administrator must ensure the target environment meets these prerequisites, which cover the database, container runtime, network connectivity, and other operational parameters.

The platform is designed to run within an API publisher's infrastructure, with all persistent configuration and state stored in a PostgreSQL database. The core components are delivered as container images. The system requires outbound network access for license verification but is otherwise designed to be internal-only, with no public-facing endpoints of its own.

Failing to meet these requirements can lead to installation failures or runtime errors. Refer to the Quickstart guide after confirming your environment is compliant.

Database Requirements

The platform uses a PostgreSQL database as its single source of truth for all persistent data, including service configurations, mappings, audit logs, and pre-computed aggregation tables. All application tables are prefixed with s2r_.

• Version: PostgreSQL 16 is the validated and tested baseline. The standalone Docker Compose stack includes a postgres:16-alpine image. While recent prior major versions are expected to work, version 16 is the officially supported version.
• Schema Management: Database schema migrations are managed by Flyway and are applied automatically when the application starts for the first time. Manual SQL execution is not required. Do not manually edit applied migration records.
• Encoding: The database encoding must be set to UTF-8 (ENCODING 'UTF8'). This is critical to prevent data corruption and ensure that SOAP envelopes, REST payloads, generated contracts, and content in languages such as Hebrew can be processed correctly.
• Required Extension: The pgcrypto extension is mandatory for encrypting credentials at rest in the database.
  • On managed PostgreSQL instances where the application's database role lacks superuser privileges, a privileged user must execute CREATE EXTENSION pgcrypto; on the target database before the application starts.
  • Failure to enable this extension will cause credential-related operations to fail with the error code S2R-ADM-0421.
• Authentication: The platform supports standard password-based authentication. For deployments on Google Cloud, IAM database authentication is also supported. For production environments, a managed PostgreSQL service (such as Google Cloud SQL or an equivalent) is recommended over the bundled container.

Database connection details are configured via environment variables (e.g., S2R_DB_HOST, S2R_DB_NAME, S2R_DB_USER, S2R_DB_SSL_MODE). For a complete list, see the Installation → Configuration reference.

Example: Enabling the pgcrypto Extension

If the application's database user is not a superuser, a database administrator must enable the pgcrypto extension manually.

1. Connect to the target PostgreSQL database using a privileged account.
2. Run the following SQL command:

   CREATE EXTENSION pgcrypto;
   

3. Expected Result: The command completes successfully. The application can now perform cryptographic operations required for managing credentials. Without this step, the application will log S2R-ADM-0421 errors.

Container and Runtime Requirements

The platform and its components (admin-api, runtime, worker, admin-ui) are distributed as container images.

• Container Runtime:
  • For standalone deployments on a single host: Docker Engine 24+ and Docker Compose v2 are required.
  • For clustered deployments: A Kubernetes or OpenShift cluster is required for the Helm-based deployment.
• Resource Allocation (Evaluation): For a single-host evaluation environment, the following resources are recommended as a baseline:
  • RAM: ~2 GB of free memory headroom.
  • Disk: ~2 GB of free disk space for container images and the data volume.
  • Production resource sizing depends on traffic volume and the number of managed services. See the Operations guide for more details.

JVM Details

The core application components (admin-api, runtime, worker) are built on a Java 25 + Spring Boot 3.5 stack, with the Java package root com.specaria.s2r.

The Java Virtual Machine (JVM) is bundled within the container images. You do not need to install a JDK on the host machine to run the product. The containers are configured with -XX:+UseContainerSupport to be container-aware and automatically adjust heap size based on the memory limits assigned to the container.

A local installation of JDK 25 and Maven 3.9 is only necessary if you intend to build the container images from source instead of using the pre-built images.

Supported Deployment Targets

As of version 1.0, the platform officially supports the following deployment targets.

Target	Notes
GCP-native	Deploys using Cloud Run, Cloud SQL (with IAM DB auth), Cloud Storage, and Cloud IAP.
Kubernetes / OpenShift	Deploys via a Helm chart. Can use an in-cluster or external PostgreSQL database.
GCP Marketplace	A marketplace listing is available for a streamlined deployment experience on Google Cloud.
Standalone Docker Compose	Deploys all components on a single host. Requires a user-provided reverse proxy or load balancer.

The platform includes a cloud-adapter abstraction for integrations with object stores, compute provisioners, and secret stores, with existing adapters for Google Cloud, Azure, and VMware. Sample Terraform environments are provided for AWS, Azure, and a vSphere relay.

The following are not supported in v1.0 and are considered bespoke engagements:

• VM appliance images (OVA, Hyper-V, Nutanix).
• First-class native integrations for AWS, Azure, or Oracle Cloud (though sample Terraform exists for some).
• Fully air-gapped deployments.

Network Requirements

Internal-Only Architecture

The platform is designed to operate entirely within your private network (e.g., VPC). It has no public endpoints by default. All traffic, API payloads, and metadata remain within your infrastructure. Access to the platform is managed through your own gateways and load balancers.

Outbound Egress for Licensing

The platform requires outbound internet access for license verification.

• Connectivity: Your firewall must permit outbound HTTPS (TLS 1.3+) traffic on port 443 from the product's runtime environment to Specaria's licensing and update notification endpoints. A complete list of required endpoints is available in Licensing → Egress allow-list.
• Connection Direction: All connections are initiated outbound from the product. The Specaria platform will never initiate an inbound connection to your environment.
• Offline Grace Period: If the licensing service is unreachable, the product continues to operate in a fully functional state for a 14-day grace period. After this period, it enters a degraded (read-only) mode until connectivity is restored.
• Failure Modes:
  • Fail-open for telemetry: An inability to send telemetry/heartbeat data will never disrupt traffic processing.
  • Fail-closed for entitlement: An invalid or expired license will disable write operations after the grace period expires.
• Data Egress: Outbound telemetry does not contain Personally Identifiable Information (PII). It includes only numeric counts, component versions, a hashed host fingerprint, an installation ID, a customer label, and a contact email. API payloads and hostnames are never transmitted.

TLS Termination

The application containers communicate internally over plain HTTP. A TLS-terminating reverse proxy or load balancer (such as nginx, HAProxy, or a cloud provider's load balancer) must be placed in front of the platform. This proxy is responsible for terminating TLS and forwarding traffic to the admin-ui. The following headers must be passed to the upstream application:

• Host
• X-Forwarded-For
• X-Forwarded-Proto: https

Runtime Limits and Defaults

The following default limits and retention policies are in effect at runtime.

Parameter	Default Value	Notes
Synchronous Payload Ceiling	30 MB	Requests with payloads larger than this are rejected with HTTP status 413 and error code S2R-RUN-0413.
Per-Operation Timeout	100 ms	Configurable on a per-operation basis.
Per-Operation Retries	2	Configurable on a per-operation basis.
Data Retention	60 days	Configurable. See Security → Data retention.

Capacity Baseline

The platform is engineered and load-tested to support a baseline of approximately 1 million calls per day.

• Sustained Throughput: ~12 requests per second.
• Burst Throughput: ~100 requests per second for short bursts.

Administrative dashboards are designed to remain responsive (sub-second load times) even with large numbers of services. This is achieved by querying pre-computed aggregation tables for time-bucketed data, rather than processing raw logs at query time. This baseline is not a hard limit; refer to the Operations guide for information on scaling for higher throughput.

Identity and Access Management

Access to the admin UI and its Role-Based Access Control (RBAC) features (admin, operator, reader roles) is managed by integrating with an external identity provider. Supported providers include:

• Google IAP (Identity-Aware Proxy)
• Azure AD (Azure Active Directory)
• Standard SAML or OIDC providers

While an evaluation stack can run without an identity provider, all production deployments should secure the admin UI with one.

Troubleshooting

• Credential Operations Fail (S2R-ADM-0421): If you see this error in the logs, it indicates that the pgcrypto extension has not been enabled in the PostgreSQL database. A privileged user must run CREATE EXTENSION pgcrypto; on the database.
• Large Payloads Rejected (S2R-RUN-0413): If API consumers receive an HTTP 413 "Payload Too Large" response, the request body exceeds the 30 MB synchronous payload ceiling.
• Degraded (Read-Only) Mode: If the platform is unable to contact the Specaria licensing service for more than 14 days, it will enter a degraded mode where write operations are disabled. Full functionality is restored once network connectivity to the licensing service is re-established.

See Also

• Quickstart
• Installation Guide
• Licensing → Egress allow-list
• Security → Authentication
• API Reference → Error Codes

---

All SOAP-to-REST docs