VirtualBox OVA Installation Guide

This guide covers importing and configuring the STING-CE Quick Start OVA in VirtualBox for optimal performance.

Prerequisites

Downloading the OVA

Download the latest OVA from GitHub Releases:

• AMD64 (Intel/AMD): sting-ce-quickstart-1.0.0-amd64.ova
• ARM64 (Apple Silicon): sting-ce-quickstart-1.0.0-arm64.ova (requires UTM or Parallels)

Importing the OVA

1. Open VirtualBox
2. Go to File → Import Appliance
3. Select the .ova file and click Next
4. Review settings (see recommended settings below)
5. Click Import

Critical Performance Settings

Host I/O Cache (CRITICAL)

This setting dramatically affects disk performance. Without it, database operations and Docker image loading become severely bottlenecked.

1. Select the VM in VirtualBox
2. Click Settings → Storage
3. Click on Controller: SATA (the controller itself, not the disk)
4. Check Use Host I/O Cache ✓
5. Click OK

Impact:

Memory (RAM)

To adjust:

1. Settings → System → Motherboard
2. Set Base Memory to at least 4096 MB (8192 MB recommended)

CPU

To adjust:

1. Settings → System → Processor
2. Set Processor(s) to at least 2 (4 recommended)
3. Enable PAE/NX if available
4. Enable Nested VT-x/AMD-V if available (for Docker performance)

Network Configuration

• Bridged Adapter (Recommended)
• NAT (Local-Only)

Graphics

1. Settings → Display
2. Video Memory: 32 MB or higher
3. Graphics Controller: VMSVGA (recommended for Ubuntu)

First Boot

1. Start the VM
2. Wait for Ubuntu to boot to the login screen
3. Login with:
   • Username: sting
   • Password: sting
4. The STING-CE installation wizard will start automatically
5. Open your browser to the URL shown in the console

Expected Installation Timeline

With proper settings (Host I/O Cache enabled):

Accessing STING-CE

After installation completes:

Web Interface

From VM Console:
  URL: https://localhost:8443

From Host (Bridged Network):
  URL: https://<vm-hostname>.local:8443
  Example: https://ubuntu-vm.local:8443

From Host (NAT with Port Forwarding):
  URL: https://localhost:8443

SSH Access

# Bridged networking
ssh sting@<vm-hostname>.local
# Password: sting

# NAT with port forwarding
ssh -p 2222 sting@localhost

Setup Wizard

The web-based setup wizard runs on port 5000 during first boot:

• http://<vm-ip>:5000 - Initial configuration

Troubleshooting

Installation Taking Too Long

Symptoms:

• Kratos health checks failing repeatedly (retry 10+/60)
• Services taking 5+ minutes each to start
• Installation exceeding 30 minutes

Solution:

1. Power off the VM (Machine → ACPI Shutdown or force power off)
2. Verify Host I/O Cache is enabled (see above)
3. Ensure at least 4GB RAM allocated
4. Restart the VM

Network Not Working

Symptoms:

• Cannot access STING web interface
• Cannot resolve hostname
• Docker images failing to pull

Solutions:

• Check Adapter
• Check VM Network

1. Settings → Network → Adapter 1
2. Verify "Cable Connected" is checked
3. Try different adapter type:
   - Bridged: Select different physical interface
   - NAT: Ensure port forwarding is configured

# Inside the VM, check IP address
ip addr show

# Test internet connectivity
ping -c 3 google.com

# Check DNS resolution
nslookup google.com

VM Won’t Start

Symptoms:

• VT-x/AMD-V errors
• “Virtualization not available”

Solutions:

1. Enable virtualization in BIOS/UEFI:

   • Reboot host machine
   • Enter BIOS setup (usually F2, F12, or Del during boot)
   • Find “Virtualization” or “VT-x” option and enable it

2. On Windows, disable conflicting features:

   # Run as Administrator
   bcdedit /set hypervisorlaunchtype off
   
   # Or disable Hyper-V in Windows Features
   

3. Restart your computer after making changes

Poor Console Performance

Symptoms:

• Laggy terminal
• Screen tearing
• Slow typing response

Solutions:

1. Install VirtualBox Guest Additions (pre-installed in OVA)
2. Increase video memory to 64 MB
3. Try different graphics controller (VBoxVGA vs VMSVGA)
4. Use SSH instead of console for better performance

Services Keep Restarting

Symptoms:

• Containers entering restart loops
• docker ps shows services restarting

Solutions:

1. Check available memory:

   free -h
   docker stats --no-stream
   

2. Increase VM RAM if memory is exhausted
3. Check disk space:

   df -h
   

Recommended VirtualBox Settings Summary

System:
  Base Memory: 8192 MB (minimum 4096 MB)
  Processors: 4 (minimum 2)
  Enable PAE/NX: Yes
  Enable Nested VT-x/AMD-V: Yes (if available)

Storage:
  Controller: SATA
  Host I/O Cache: ENABLED (critical!)

Display:
  Video Memory: 32 MB+
  Graphics Controller: VMSVGA

Network:
  Attached to: Bridged Adapter (recommended)
  Cable Connected: Yes

Audio:
  Enable Audio: No (not needed, saves resources)

VMware Alternative

If you experience issues with VirtualBox, the OVA is also compatible with:

• VMware Workstation (Windows/Linux)
• VMware Fusion (macOS Intel)
• VMware Player (free for personal use)

VMware typically handles I/O caching automatically and may provide better performance out of the box.

Next Steps

After successful installation:

• Create Your First Honey Jar - Organize your knowledge
• Configure Authentication - Set up passkeys
• Connect AI Models - Configure Ollama or external AI
• Admin Setup - Configure your instance

Getting Help

If you continue to experience issues:

1. Check the Common Errors and Fixes
2. Review VirtualBox logs: Machine → Show Log
3. Create an issue at STING-CE GitHub

Include in your report:

• VirtualBox version
• Host OS and version
• VM settings screenshot
• Console output or error messages