SOAP-2-REST Operations Overview

A runbook for operating the SOAP-2-REST platform in production, covering deployment, daily checks, troubleshooting, and backup and restore procedures.

Operations Overview

This guide is the operator's runbook for the SOAP-2-REST platform. It provides a central reference for production operational procedures, including safe deployment and upgrade sequences, daily health checks, diagnostics for common failures, and backup and restore strategies.

NOTE

This guide is for operators of an existing installation. For initial setup, see the Installation and Configuration reference guides first.

System Architecture

The platform consists of four cooperating services that rely on a single PostgreSQL database as the source of truth for all configuration and state.

flowchart TD
    subgraph "Platform Services"
        AdminUI["admin-ui (Operator Web UI)"]
        AdminAPI["admin-api (Control Plane)"]
        Runtime["runtime (Data Plane)"]
        Worker["worker (Aggregation & Discovery)"]
    end

    DB[(PostgreSQL Database)]

    AdminUI -- "Proxies API calls" --> AdminAPI
    AdminUI -- "Proxies API calls" --> Runtime
    AdminAPI -- "Manages config & state" --> DB
    Runtime -- "Reads config" --> DB
    Worker -- "Writes aggregations" --> DB
    Worker -- "Reads data" --> DB

Service Roles

Service	Role	Operational Note
`admin-api`	Control Plane	Owns the database schema migrations via Flyway. This service must be deployed or upgraded first.
`runtime`	Data Plane (SOAP-to-REST conversion)	Stateless and can be scaled horizontally. Maintain a warm minimum number of instances to avoid cold-start latency.
`worker`	Aggregation, discovery derivation, learned examples	This service populates the aggregation tables that power the operations dashboards. Its health is critical for accurate monitoring.
`admin-ui`	Operator web UI	Provides the user interface for operators, proxying requests to the `admin-api` and `runtime` services.

Core Operating Principles

Two principles are fundamental to operating the platform:

The database is the single source of truth. All persistent configuration and application state are stored in the PostgreSQL database within tables prefixed with s2r_*. The application services are stateless and can be replaced, but the database must be backed up and protected.
Dashboards read from aggregation tables, not raw logs. All time-bucketed metrics and visualizations are served from pre-computed aggregation tables. The worker service is responsible for refreshing this data. If the worker fails, dashboards will become stale without any explicit error. A stale dashboard is a high-priority operational issue.

Operational Guides

This section links to the detailed runbooks for specific operational tasks.

Deployment Runbook Details the required sequence for deploying and upgrading services (admin-api → runtime → worker). It explains why the order is critical and how to verify a deployment's provenance.
Daily Operations A day-2 playbook covering the use of the Operations Dashboard, ingest health checks, catalog updates, and managing the update channel. Includes a suggested daily checklist for operators.
Troubleshooting Provides symptom-based diagnostic procedures for common issues such as ingest data gaps, schema mismatches after an upgrade, credential errors (e.g., S2R-ADM-0419), payload size errors (S2R-RUN-0413), and user lockout. Also explains where to locate service logs.
Backup & Restore Contains procedures for backing up and restoring the PostgreSQL database, which holds all platform configuration and state.

Capacity Baseline

The platform is engineered and load-tested for a baseline traffic volume of approximately 1 million calls per day. This corresponds to a sustained rate of about 12 requests per second (rps), with support for short bursts up to approximately 100 rps.

To monitor your platform's current usage against this baseline, see the capacity check procedures in the Daily Operations guide and the available dashboards described in Metrics & SLO Reports.

Tagsguides

All SOAP-to-REST docs