VM Appliance Installation (OVA/VHDX)

Overview

The VM appliance is a single, downloadable virtual machine that contains the complete SOAP-2-REST product stack, including all services and a bundled PostgreSQL database. This installation method is designed for environments that are restricted to virtual machines, operate without internet access (air-gapped), or where operators may not have Kubernetes or Docker expertise.

The appliance is available for both VMware and Microsoft Hyper-V hypervisors. It is downloaded from the Specaria portal (portal.specaria.io) in one of two formats:

Internally, the appliance is a minimal Debian 12 virtual machine with Docker pre-installed. The product's Docker images are included as tar archives, which are loaded on the first boot, eliminating the need to pull images from a container registry. A systemd service automates the initial setup by reading the configuration you provide and launching the entire stack using Docker Compose.

Sizing Requirements

Allocate the following minimum resources to the virtual machine. For production workloads, use the recommended values.

The appliance ships with a 20 GB virtual disk. If you anticipate a high volume of traffic logs, expand the virtual disk in your hypervisor's settings before the first boot.

How It Works

The appliance automates the deployment process on its first boot. The sequence of operations is as follows:

1. Configuration Sourcing: The appliance reads configuration properties provided by the API publisher during the VM import process (either as OVF properties in VMware or from a config-drive ISO in Hyper-V).
2. Configuration Rendering: It uses these properties to generate a .env file at /opt/s2r/deploy/.env.
3. Image Loading: The load-images.sh script loads the bundled product Docker images from their tar archives into the local Docker daemon.
4. Stack Initialization: The docker compose up -d command starts the full application stack in the correct order: PostgreSQL, admin-api, runtime, worker, generic-ingest, admin-ui, and a TLS reverse proxy (Traefik).
5. Certificate Generation: If a TLS certificate is not provided, a self-signed certificate is generated for the configured hostname.

Once the boot process completes (typically 2–4 minutes), the platform's user interface is accessible on HTTPS port 443 at the configured hostname. The generic ingest receiver listens on TCP port 8081 by default.

The following diagram illustrates the first-boot process:

sequenceDiagram
    participant API Publisher
    participant Hypervisor
    participant VM Appliance
    participant Docker Engine

    API Publisher->>Hypervisor: Deploy Appliance with Config
    Hypervisor->>VM Appliance: Power On
    VM Appliance->>VM Appliance: First-boot service starts
    VM Appliance->>VM Appliance: Read config (OVF/ISO)
    VM Appliance->>VM Appliance: Render /opt/s2r/deploy/.env
    VM Appliance->>Docker Engine: Load image tarballs
    VM Appliance->>Docker Engine: Run `docker compose up -d`
    Docker Engine->>Docker Engine: Start services in order
    VM Appliance-->>API Publisher: Platform ready at https://<S2R_HOSTNAME>

Configuration

Configuration is supplied once during the VM import and first boot. The properties use the canonical names found throughout the product. You do not need to edit files inside the VM manually.

Licensing is handled through the admin UI after the first boot and is not a first-boot property.

VMware Installation

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 the values for the first-boot properties. At a minimum, you must provide S2R_HOSTNAME and S2R_ADMIN_BOOTSTRAP_EMAILS. You can leave secret fields like S2R_DB_PASSWORD blank to have them auto-generated.
5. Click Finish and power on the VM. The first boot will take 2–4 minutes.

Option B: vCenter govc CLI

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

1. Inspect the OVA to see the available configuration properties and save them to a spec file.

   govc import.spec s2r-appliance-<version>.ova > spec.json
   

2. Edit spec.json to set the desired values for the PropertyMapping keys (e.g., S2R_HOSTNAME).
3. Import and power on the VM using the spec file.

   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 OVF properties (vApp properties). You must provide configuration using one of two alternative methods:
   • Config-drive ISO: Create and attach a config-drive ISO as a second CD/DVD drive before the first power-on. See the Hyper-V section for instructions; the same ISO format works.
   • Console Prompt: If no configuration source is found, the appliance will fall back to an interactive prompt on the VM console to ask for the hostname and admin email. Secrets will be auto-generated.

Hyper-V Installation

Hyper-V does not have a mechanism equivalent to VMware's OVF properties. Configuration must be supplied using a config-drive ISO that conforms to the cloud-init NoCloud datasource format.

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 by copying build/appliance/config-drive/user-data.example and editing the key-value pairs.
   • Create a meta-data file containing 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. When prompted for the hard disk, choose Use an existing virtual hard disk and select the s2r-appliance-<version>.vhdx file.

3. In the VM's settings, add a DVD Drive and attach the seed.iso file you created.

4. Assign resources to the VM (at least 2 vCPUs, 4 GB RAM) and connect it to a virtual switch.

5. Start the VM. The first-boot service will read the configuration from the ISO 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:

It is recommended to restrict inbound access on port 443 to your trusted operator network. For single sign-on (SSO), place the appliance behind your own reverse proxy or load balancer, set S2R_ADMIN_UI_AUTH_MODE=none, and terminate authentication at the proxy.

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. You can proceed past the warning or replace the certificate.
3. Sign in using one of the email addresses provided in the S2R_ADMIN_BOOTSTRAP_EMAILS property.

To verify that the application stack is running correctly from within the VM, you can use the following commands:

# Check the status of the Docker containers
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 appliance and restart the proxy service.

# Copy your certificate and key files
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 in the config-drive ISO.

Upgrade Path

The appliance's data, configuration, and certificates are stored in persistent locations and are preserved during upgrades.

In-Place Image Upgrade

This method updates the product images on the existing VM.

1. Download the new product image tarballs (deploy/images/ bundle) from the Specaria portal.
2. Copy the new *.tar files to the appliance and run the upgrade scripts.

   # Copy the new image archives to the appliance
   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

This method involves deploying a new appliance and migrating data from the old one.

1. Deploy a new VM using the latest OVA/VHDX image.
2. Restore a database backup from the old appliance into the new one.
3. Ensure you configure the new appliance with the same S2R_CREDENTIAL_KEY as the old one to maintain access to encrypted credentials.

Troubleshooting

See Also

• Docker Compose Installation
• Configuration Reference
• Licensing and Egress Allow-list
• Backup and Restore Procedures
• F5 Syslog Connector

All SOAP-to-REST docs