Loading…
Loading…
A comprehensive reference for deploy-time environment variables and in-app settings for the S2R platform, covering database, identity, and cloud providers.
## Overview
This document provides a comprehensive reference for all configuration settings for the S2R platform, available since v1.0. Configuration is managed at two distinct layers, targeting operators responsible for installation and ongoing platform management.
1. **Deploy-Time Configuration**: These settings are provided as environment variables or secret bindings when deploying the platform services (e.g., `admin-api`, `runtime`, `worker`). They are read once on service startup and are used to configure fundamental infrastructure connections, such as database connectivity, credential encryption, and cloud provider selection. These values are static for the life of a service revision.
2. **In-App Configuration**: These settings are tuned dynamically through the **Settings** section of the Admin UI after the platform is running. They are persisted in the PostgreSQL database and control application-level behavior, such as data retention policies, conversion defaults, and topology labels.
This reference details all available settings at both layers.
## How it works
The platform's configuration mechanism is determined by when and how a setting is applied.
### Deploy-Time Environment Variables
At startup, each service reads its configuration from environment variables. These variables must be set in the execution environment of the service containers, such as a Docker Compose `.env` file, Helm `values.yaml`, or Cloud Run service definition.
Environment variable names are case-sensitive and must be exact. For settings that correspond to Spring Boot properties (e.g., `s2r.cloud.provider`), the platform uses Spring's relaxed binding to resolve the equivalent upper-snake-case environment variable (e.g., `S2R_CLOUD_PROVIDER`).
The `admin-api` service is responsible for applying database migrations on startup, based on its connectivity settings. All services (`admin-api`, `runtime`, `worker`) require consistent database connectivity configuration to function.
### In-App Settings
After the initial deployment and boot, an operator can modify certain application behaviors through the Admin UI. These settings are stored in the platform's PostgreSQL database. When an operator saves a change in the UI, the `admin-api` service writes the new value to the database. Other services, such as the `runtime`, read these settings from the database to apply them to their operations.
## Example: Generating the Credential Key
The `S2R_CREDENTIAL_KEY` is a critical secret that must be generated and securely stored before the first deployment. It is used to encrypt sensitive data in the database.
1. Generate a secure, base64-encoded 32-byte (256-bit) key using `openssl`:
```bash
openssl rand -base64 32
The command will output a random string, which is your key. Expected Output:
rO/dMVq8a8y1A4Z1f8b9eG2kL3jJ5cN7pI6sF0tX4yQ=
Set this value for the S2R_CREDENTIAL_KEY environment variable in your secret manager (e.g., GCP Secret Manager, Kubernetes Secrets) and bind it to the admin-api and runtime services.
Important: This key must be chosen once and never changed. Rotating the key will render all previously encrypted credentials in the database unreadable.
The following sections detail all available configuration parameters.
These secrets must be set for every deployment. Failure to provide them will result in startup errors (e.g., S2R-ADM-0419).
| Variable | Type | Required | Description |
|---|---|---|---|
S2R_DB_PASSWORD | string | Conditional | The password for the PostgreSQL application user. Required when S2R_DB_IAM_AUTH_ENABLED is false. |
S2R_CREDENTIAL_KEY | string (Base64) | Yes | A base64-encoded, 32-byte (256-bit) AES key used to encrypt backend credentials in the database. This key is read by admin-api and runtime. Do not rotate this key after initial setup. |
S2R_F5_VM_DB_PASSWORD | string | Conditional | The database password used during F5 relay-VM provisioning. Only required if a traffic relay VM is used. Read by admin-api and worker. |
These variables configure the connection to the PostgreSQL database. They must be set consistently across the admin-api, runtime, and worker services.
| Variable | Type | Default | Required | Description |
|---|---|---|---|---|
S2R_DB_IAM_AUTH_ENABLED | boolean | — | No | Set to true to use GCP IAM database authentication for Cloud SQL. Set to false for password-based authentication. |
S2R_DB_AUTH_MODE | string | — | No | Set to password for password authentication. Used alongside S2R_DB_IAM_AUTH_ENABLED=false. |
S2R_DB_HOST | string | postgres | Yes | The hostname or IP address of the PostgreSQL database server. The default postgres applies to Docker Compose deployments. |
S2R_DB_PORT | integer | 5432 | No | The port number of the PostgreSQL database server. |
S2R_DB_NAME | string | soap_to_rest | No | The name of the database to connect to. |
S2R_DB_USER | string | s2r_app | No | The username (application role) for connecting to the database. |
S2R_DB_SSL_MODE | string | — | No | The SSL mode for the database connection. Recommended value is require for managed or external databases. Use disable only for a bundled, in-network database. |
These variables control user authentication and initial role seeding.
| Variable | Type | Required | Description |
|---|---|---|---|
S2R_ADMIN_UI_AUTH_MODE | string | No | Sets the UI authentication mode. Use none when an upstream proxy or identity provider (e.g., Cloud IAP) terminates authentication. |
S2R_ADMIN_BOOTSTRAP_EMAILS | string | No | A comma-separated list of user emails to be seeded into the admin role on the first boot of the application. |
S2R_ADMIN_BOOTSTRAP_OPERATOR_EMAILS | string | No | A comma-separated list of user emails to be seeded into the operator role on first boot. |
S2R_ADMIN_BOOTSTRAP_READER_EMAILS | string | No | A comma-separated list of user emails to be seeded into the reader role on first boot. |
Note: If no admin users are seeded on first boot, the first authenticated user to access the Admin UI is automatically granted the bootstrap admin role.
These variables define the internal network addresses for services, primarily for Docker Compose deployments.
| Variable | Type | Default | Description |
|---|---|---|---|
S2R_ADMIN_API_INTERNAL_URL | string | http://admin-api:8080 | The internal URL for the admin-api service. |
S2R_RUNTIME_INTERNAL_URL | string | http://runtime:8080 | The internal URL for the runtime service. On GCP, this should be the load balancer's host, not a *.run.app URL. |
S2R_ADMIN_UI_HOST_PORT | integer | 8080 | The host port targeted by an external load balancer in standalone mode. |
These settings determine which cloud-specific implementation is used for features like object storage, secret management, and compute provisioning.
| Environment Variable | Spring Property | Default | Accepted Values |
|---|---|---|---|
S2R_CLOUD_PROVIDER | s2r.cloud.provider | gcp | gcp, azure, vmware, aws |
S2R_RELAY_VM_PROVIDER | s2r.relay-vm.provider | gcp | gcp, aws, vmware |
The S2R_RELAY_VM_PROVIDER can be set independently, allowing the platform to run in one cloud while provisioning a traffic relay VM in another. The selected provider is logged on service startup.
These variables control which container images are pulled for deployment.
| Variable | Type | Default | Description |
|---|---|---|---|
S2R_IMAGE_PREFIX | string | s2r | The registry and repository prefix for the service container images. |
S2R_IMAGE_TAG | string | latest | The tag for the container images. For reproducible deployments, pin this to a specific version tag (e.g., v1.0.0). |
The following are built-in default behaviors for the conversion runtime. These can be overridden on a per-service or per-operation basis in the Admin UI.
100 ms230 MB. Requests exceeding this size are rejected.These settings are configured in the Settings section of the Admin UI after deployment.
| Setting | Internal Key | Default | Description |
|---|---|---|---|
| Data retention | default_retention_days | 60 days | Governs the retention period for the raw traffic archive. Aggregation tables and audit logs have separate, longer retention defaults. |
| Install profile | — | both | Controls which feature surfaces are shown in the UI. Accepts f5_modernization, generic, or both. |
| Topology labels | — | — | Free-text labels (e.g., prod, staging) that are surfaced in audit logs and structured logs for context. |
| Excluded consumer IP ranges | — | — | A list of IP addresses or CIDR ranges to exclude from traffic aggregation, such as synthetic monitoring agents. |
| License | — | Trial / Community | Allows viewing license status and uploading a renewal token. |
These environment variables are set automatically by the deployment tooling and are read-only. They can be inspected on a running service to identify the exact version of the code.
S2R_DEPLOY_COMMIT_SHAS2R_DEPLOY_COMMIT_SHORTS2R_DEPLOY_BRANCHS2R_DEPLOY_TIMESTAMPS2R_DEPLOY_IMAGE_TAGEach service logs these values on startup with a S2R-DEPLOY … log line.
S2R-ADM-0419 on startup: This indicates a startup or credential error. It commonly occurs on Cloud Run if a required secret binding (e.g., S2R_CREDENTIAL_KEY) was not applied during deployment. Secret bindings are not inherited from previous revisions and must be re-applied with every deployment.413 Response with error S2R-RUN-0413: This error occurs when the runtime service receives a request with a payload larger than the configured Synchronous payload ceiling (default: 30 MB). The request is rejected.S2R_ADMIN_BOOTSTRAP_EMAILS variable is not set on first boot, the system enters a bootstrap mode where the first authenticated user to access the Admin UI is automatically promoted to the admin role.