Install the VM Appliance (OVA/VHDX)

Overview

The VM appliance is a single, downloadable virtual machine that contains the complete SOAP-2-REST product, including all services and a bundled PostgreSQL database. This installation method is designed for environments that do not use Kubernetes or Docker, or for deployments in air-gapped networks with no internet access.

The appliance is available for VMware and Microsoft Hyper-V hypervisors. It consists of a minimal Debian 12 virtual machine with Docker pre-installed. The product's container images are included as tar archives within the appliance and are loaded into the local Docker engine on first boot, eliminating the need to pull from an external container registry.

A systemd-managed service automates the initial setup process by reading user-provided configuration, preparing the environment, and starting the entire application stack using Docker Compose.

Two appliance formats are available for download from the Specaria portal:

Sizing Requirements

Provision the virtual machine with the following minimum resources. For production environments, use the recommended values.

The appliance is distributed with a 20 GB virtual disk. If you anticipate high volumes of traffic logs, expand the virtual disk in your hypervisor settings before the first boot.

How It Works

On its first boot, the appliance executes an automated setup sequence:

flowchart TD
    A[VM Power On] --> B{First Boot?};
    B -- Yes --> C[First-boot Service Starts];
    C --> D[Read Configuration<br/>(OVF Properties or Config-Drive ISO)];
    D --> E[Render /opt/s2r/deploy/.env];
    E --> F[Load Bundled Docker Images<br/>(load-images.sh)];
    F --> G[Start Application Stack<br/>(docker compose up -d)];
    G --> H[Generate Self-Signed TLS Certificate];
    H --> I[Platform Ready];
    I --> J[Admin UI on Port 443];
    I --> K[Ingest Receiver on Port 8081];
    B -- No --> I;

1. Render Configuration: It generates the /opt/s2r/deploy/.env file from the configuration properties you supply during import.
2. Load Images: It runs load-images.sh to load the bundled product image tarballs into the local Docker engine.
3. Start Services: It executes docker compose up -d to launch the full stack in the correct order: PostgreSQL, admin-api, runtime, worker, generic-ingest, admin-ui, and a Traefik reverse proxy.
4. Generate Certificate: It creates a self-signed TLS certificate for immediate use. This certificate can be replaced.

After this process completes, the platform's admin UI is accessible via HTTPS on port 443 at the configured hostname. The generic-ingest receiver listens on its default port, 8081.

First-Boot Configuration Properties

You must provide configuration properties once, at the time of VM import or first boot. These keys are the canonical environment variables used across all deployment types. You do not need to edit files inside the VM manually.

VMware: Import the OVA

Option A: vSphere / vCenter (UI)

1. In the vSphere client, navigate to Hosts and Clusters, right-click a host or cluster, and select Deploy OVF Template.
2. Select the s2r-appliance-<version>.ova file from your local machine or provide a URL.
3. Follow the wizard to name the VM and select compute, storage, and network resources.
4. On the Customize template page, enter values for the first-boot properties. At a minimum, provide S2R_HOSTNAME and S2R_ADMIN_BOOTSTRAP_EMAILS. Leave secret fields like S2R_DB_PASSWORD blank to have them auto-generated.
5. Finish the wizard and power on the VM. The first boot typically takes 2–4 minutes as it loads images and starts the services.

Option B: vCenter (govc CLI)

For automated deployments, use the govc command-line tool.

# Inspect the OVA to see the configurable properties
govc import.spec s2r-appliance-<version>.ova > spec.json

# Edit spec.json to set the desired values in the PropertyMapping section
# (e.g., S2R_HOSTNAME, S2R_ADMIN_BOOTSTRAP_EMAILS).

# Import the OVA using the modified spec file and power it on
govc import.ova -options=spec.json -name=s2r-appliance s2r-appliance-<version>.ova
govc vm.power -on s2r-appliance

Option C: VMware Workstation / Fusion

1. Select File → Open and choose the .ova file.
2. VMware Workstation and Fusion do not support the vApp properties mechanism for configuration. You must either:
   • Use a config-drive ISO: Attach a cidata-labeled ISO file (as described in the Hyper-V section) as a second CD/DVD drive before the first power-on.
   • Use the console prompt: If no configuration source is found, the appliance will prompt for the hostname and admin email on the VM console during the first boot and auto-generate secrets.

Hyper-V: Import the VHDX

Hyper-V does not have a mechanism equivalent to VMware's vApp properties. Configuration must be supplied using a cloud-init compatible "config-drive" ISO file.

1. Create the config-drive ISO. This is a one-time setup on any machine with an ISO creation tool.

   • Create a user-data file containing the first-boot properties. An example file is available in the source at build/appliance/config-drive/user-data.example.
   • Create a meta-data file specifying an instance-id and local-hostname.
   • Use a command-line tool to build the ISO with the volume label cidata.
     • On Linux: genisoimage -output seed.iso -volid cidata -joliet -rock user-data meta-data
     • On Windows (requires Windows ADK): oscdimg -lcidata -j2 .\seed seed.iso

2. In Hyper-V Manager, create a New Virtual Machine. Select Generation 1.

3. When prompted for the hard disk, choose Use an existing virtual hard disk and select the s2r-appliance-<version>.vhdx file.

4. Before starting the VM, edit its settings to add a DVD Drive and mount the seed.iso file you created.

5. Assign resources (vCPU, RAM) and connect the VM to a virtual switch.

6. Start the VM. The first-boot service will detect and read the config-drive ISO, configure the system, and start the application stack. The ISO can be detached after the first successful boot.

Networking and Firewall Rules

The appliance requires the following network access:

For production deployments, restrict inbound access to port 443 to your trusted operator network. If you require single sign-on (SSO), front the appliance with your own load balancer or reverse proxy, set S2R_ADMIN_UI_AUTH_MODE=none, and terminate authentication at that layer.

First Login and Verification

1. Open a web browser and navigate to https://<S2R_HOSTNAME>.
2. Your browser will show a security warning because the appliance uses a self-signed TLS certificate by default. Accept the warning to proceed.
3. Sign in using one of the email addresses you provided in S2R_ADMIN_BOOTSTRAP_EMAILS.

To verify that all services are running correctly from within the VM, you can use the following commands:

# Check the status of all Docker containers in the stack
sudo docker compose -f /opt/s2r/deploy/docker-compose.yml ps

# Run the health check script
sudo /opt/s2r/deploy/scripts/test-health.sh https://<S2R_HOSTNAME> --insecure

Replace the TLS Certificate

To replace the default self-signed certificate with your own, copy your certificate and private key to the VM and restart the proxy service.

# Copy your certificate and key to the correct location
sudo cp your-tls.crt /opt/s2r/deploy/certs/tls.crt
sudo cp your-tls.key /opt/s2r/deploy/certs/tls.key

# Restart the proxy container to apply the new certificate
sudo docker compose -f /opt/s2r/deploy/docker-compose.yml restart proxy

You can also pre-load a certificate by including /etc/s2r/tls.crt and /etc/s2r/tls.key files in the config-drive ISO.

Upgrade Path

Your configuration (.env), database, and certificates are preserved across upgrades.

In-Place Image Upgrade

This method updates the application images without redeploying the entire VM.

1. Download the new product image tarball bundle from the Specaria portal.
2. Copy the new *.tar files into the appliance's image directory and run the upgrade commands.

# Copy new image tarballs into the VM
sudo cp /path/to/new/*.tar /opt/s2r/deploy/images/

# Load the new images into Docker
sudo /opt/s2r/deploy/scripts/load-images.sh

# Re-create the containers with the new images
sudo docker compose -f /opt/s2r/deploy/docker-compose.yml up -d

Database schema migrations are applied automatically when the admin-api service starts.

Whole-Appliance Upgrade

Alternatively, you can deploy a new version of the OVA/VHDX appliance and migrate your data.

1. Deploy the new appliance.
2. Restore a database backup from your old appliance into the new one.
3. Ensure you use the same S2R_CREDENTIAL_KEY from your old appliance so that encrypted data remains accessible.

Troubleshooting

See Also

• Docker Compose Installation Guide
• Egress Allow-list and Licensing
• Canonical Configuration Reference
• F5 Traffic Log Integration
• Backup and Restore Procedures

All SOAP-to-REST docs