Install the Platform with Docker Compose

Overview

The Docker Compose installation is the fastest method for standing up the full API platform on a single host. It is suitable for any environment with Docker, including cloud virtual machines (e.g., AWS EC2, Azure VM, Oracle Cloud Compute) or on-premises hypervisors (e.g., KVM, VMware, Hyper-V). This installation method does not require a cloud provider account.

This deployment method has been available since v1.0 and is validated by an automated CI smoke test.

The installation provides a single-host stack of the following services:

• postgres: A bundled PostgreSQL database for storing platform data.
• admin-api: The backend API for the administration UI.
• runtime: The core API gateway runtime component.
• worker: A background job processor.
• admin-ui: The web-based administration interface.

All services within the stack communicate over plain HTTP. TLS termination is handled by a proxy layer. Two compose files are provided to accommodate different TLS termination strategies:

• docker-compose.yml: Includes a built-in Traefik proxy that automatically handles TLS termination and self-signed certificate generation. This is ideal for a self-contained host without an external load balancer.
• docker-compose.standalone.yml: Exposes the admin-ui on a plain HTTP host port (default: 8080) and does not include a built-in proxy. This file is intended for use with an external load balancer or reverse proxy (e.g., F5 BIG-IP, nginx, a cloud application gateway) that manages TLS termination.

This guide focuses on the docker-compose.standalone.yml file for integration with existing edge infrastructure.

Prerequisites

• Docker: Docker Engine 24+ and Docker Compose v2 (verify with docker compose version).
• System Resources: Approximately 2 GB of available RAM and 2 GB of disk space for Docker images and the data volume.
• Application Images: You must have access to pre-built images from your designated registry or have a local build toolchain installed (Java 25 and Maven 3.9).

Installation Steps

These steps guide you through configuring and launching the platform using docker-compose.standalone.yml.

1. Configure Secrets

The platform's configuration is managed through an .env file in the same directory as the docker-compose.standalone.yml file. Create this file by copying the provided example:

cp docker-compose.env.example .env

Next, edit the .env file to set the following mandatory secrets:

# Postgres password for the bundled database. Use a strong, randomly generated value.
# Example generation command: openssl rand -base64 24
S2R_DB_PASSWORD=<strong-password>

# AES key for encrypting backend credentials in the database.
# This MUST be a base64-encoded 32-byte (256-bit) value.
# Example generation command: openssl rand -base64 32
# IMPORTANT: Store this key securely. Rotating it will invalidate all previously
# encrypted credentials, requiring them to be re-entered.
S2R_CREDENTIAL_KEY=<base64-32-byte-key>

Security Warning: The .env file contains sensitive credentials, including the database password and the master encryption key. Never commit this file to source control.

For a complete list of all available configuration variables, see the Configuration reference.

2. Build or Pull Images

If you are building images from source, run one of the following commands. If you are using pre-built images from a container registry, you can skip this step.

# Build on a Linux or macOS host
docker compose -f docker-compose.standalone.yml build

# Build on a Windows host using PowerShell
scripts/build-images.ps1

To use pre-built images, set the S2R_IMAGE_PREFIX and S2R_IMAGE_TAG variables in your .env file to point to the correct registry location and version tag.

3. Start the Stack

Launch all services in the background (detached mode):

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

The services will start, and the admin-ui will become available on the host port (default 8080) after approximately 60 seconds.

Note: The very first request to the admin-api triggers the Flyway database migrations. This causes the initial startup to take 30–60 seconds longer than subsequent restarts.

4. Verify the Installation

You can check the status of the running services and view logs to confirm a successful startup.

# Check the health status of all containers
docker compose -f docker-compose.standalone.yml ps

# Tail the logs for a specific service, e.g., admin-api, to watch migrations and boot process
docker compose -f docker-compose.standalone.yml logs -f admin-api

Post-Installation Configuration

Load Balancer Integration

When using docker-compose.standalone.yml, you must configure an external load balancer or reverse proxy to route traffic to the platform and handle TLS termination.

Configure your load balancer with the following settings:

• Backend Target: http://<host_ip>:<S2R_ADMIN_UI_HOST_PORT> (The default port is 8080).
• Health Check: GET / should return a 200 OK status.
• HTTP Headers: Your proxy must forward the following headers to the backend:
  • Host
  • X-Forwarded-For
  • X-Forwarded-Proto: https

The platform uses the X-Client-IP, X-Forwarded-For, or Forwarded headers to determine the original IP address of the API consumer for attribution and logging. Ensure your proxy correctly sets at least one of these headers.

First Boot and Bootstrap Admin

On its first launch, the platform has no configured administrator users. The first user who authenticates to the admin UI is automatically granted the bootstrap admin role. After this initial user is established, standard Role-Based Access Control (RBAC) applies for all subsequent users.

To secure your installation, you must log in as the bootstrap administrator immediately after deployment. Do not expose the admin UI URL publicly until this step is complete.

You can also pre-seed user roles by setting the following environment variables in your .env file:

• S2R_ADMIN_BOOTSTRAP_EMAILS
• S2R_ADMIN_BOOTSTRAP_OPERATOR_EMAILS
• S2R_ADMIN_BOOTSTRAP_READER_EMAILS

Using an External PostgreSQL Database

For production environments, it is recommended to use a managed, high-availability PostgreSQL service (such as AWS RDS, Azure Database for PostgreSQL, or Google Cloud SQL) instead of the bundled postgres container.

To switch to an external database:

1. Create an Override File: Create a file named docker-compose.override.yml in the same directory. This file will add environment variables to the services to point them at your external database.

   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
   

   Replace my-postgres.internal with the hostname of your PostgreSQL instance. Set S2R_DB_SSL_MODE according to your database's security requirements.

2. Prepare the Database: Connect to your external PostgreSQL instance and execute the following SQL commands to create the database and application user role. The password must match the S2R_DB_PASSWORD value in your .env file.

   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;
   

3. Configure Credentials: The services use the S2R_DB_USER, S2R_DB_PASSWORD, and S2R_DB_NAME variables from the .env file to connect. The default values are s2r_app and soap_to_rest respectively. Ensure S2R_DB_PASSWORD is set correctly.

4. Disable Bundled Service (Optional): After configuring the override, you can stop and remove the bundled postgres container to conserve resources.

   docker compose stop postgres
   

Note on Authentication: For hosts not running on GCP, ensure S2R_DB_IAM_AUTH_ENABLED is set to false (the default) so that services use standard password authentication.

Configuration Variables

The following table lists the environment variables mentioned in this guide. They are configured in the .env file.

Variable	Description	Default
S2R_DB_PASSWORD	The password for the database user. Used for both the bundled and external PostgreSQL.	—
S2R_CREDENTIAL_KEY	A Base64-encoded 32-byte (256-bit) AES key for encrypting credentials in the database. Changing this key invalidates all existing encrypted data.	—
S2R_IMAGE_PREFIX	The registry prefix for pulling pre-built Docker images.	—
S2R_IMAGE_TAG	The tag for pulling pre-built Docker images.	—
S2R_ADMIN_UI_HOST_PORT	The host port on which the admin-ui service is exposed when using docker-compose.standalone.yml.	8080
S2R_DB_HOST	The hostname of the PostgreSQL database. Used in docker-compose.override.yml for external databases.	—
S2R_DB_SSL_MODE	The SSL connection mode for the PostgreSQL database (e.g., require, verify-full).	—
S2R_DB_USER	The username for the PostgreSQL database connection.	s2r_app
S2R_DB_NAME	The name of the PostgreSQL database.	soap_to_rest
S2R_DB_IAM_AUTH_ENABLED	If true, services attempt to use GCP IAM database authentication. Set to false for standard password authentication.	false
S2R_ADMIN_BOOTSTRAP_EMAILS	A comma-separated list of user emails to be granted the bootstrap admin role on first login.	—
S2R_ADMIN_BOOTSTRAP_OPERATOR_EMAILS	A comma-separated list of user emails to be granted the operator role on first login.	—
S2R_ADMIN_BOOTSTRAP_READER_EMAILS	A comma-separated list of user emails to be granted the reader role on first login.	—

Troubleshooting

• Slow Initial Startup: The first time the platform starts, the admin-api service runs database migrations via Flyway. This can add 30-60 seconds to the startup time. This delay only occurs on the very first boot or after a database schema upgrade.
• Insecure Bootstrap Admin: The first authenticated user becomes the administrator. It is critical to secure the admin-ui endpoint and log in immediately after deployment to claim the administrator role before other users can access the system.
• Credential Key Rotation: The S2R_CREDENTIAL_KEY is used to encrypt sensitive data at rest. If this key is lost or rotated, all credentials for backend services previously stored in the database will become unreadable and must be re-configured.

See Also

• Configuration reference
• Operations overview
• Daily operations
• Onboarding a service

---

All SOAP-to-REST docs