Skip to main content

Deployment Guide

Deploy HyperSDK and the marketing website to your infrastructure.

System Requirements​

ComponentMinimumRecommended
OSRHEL 8+ / Fedora 38+ / Ubuntu 22.04+Fedora 42+
CPU2 cores4+ cores
RAM4 GB8+ GB
Disk50 GB200+ GB (for VM storage)
Kernel5.4+ with KVM support6.x+

HyperSDK Daemon​

Install from source​

git clone https://github.com/ssahani/hypersdk.git
cd hypersdk
make build
sudo make install

Start the service​

sudo systemctl enable --now hypervisord

HyperSDK starts with HTTPS by default (self-signed certificate). Access the dashboard at https://your-server:5080/web/dashboard/.

To disable TLS:

# In /etc/systemd/system/hypervisord.service.d/override.conf
[Service]
Environment=HYPERSDK_TLS=0

Configuration​

HyperSDK searches for config in order:

  1. ./hypersdk.yaml
  2. ~/.config/hypersdk/config.yaml
  3. /etc/hypersdk/config.yaml

Website Deployment​

One command handles everything — build, sync, SSL, container:

REMOTE_USER=sus ./scripts/deploy.sh your-server-ip

This automatically:

  1. Builds the website locally (npm run build)
  2. Syncs build + nginx config to the remote server
  3. Installs real SSL cert from ssl/fullchain.crt if present
  4. Falls back to self-signed cert if no real cert exists
  5. Builds and starts a podman container on ports 80+443

Options:

REMOTE_USER=sus ./scripts/deploy.sh your-server-ip --skip-build  # Use existing build/
REMOTE_USER=sus ./scripts/deploy.sh your-server-ip --bare        # Bare nginx (no container)
./scripts/deploy.sh --help                                        # All options

Makefile shortcuts​

make deploy SERVER=your-server-ip           # Container (default)
make deploy-bare SERVER=your-server-ip      # Bare nginx
make deploy-all SERVER=your-server-ip       # Website + HyperSDK + hyper2kvm

Build customization​

Override the site URL and dashboard link at build time:

SITE_URL=https://hypersdk.example.com \
DASHBOARD_URL=https://dashboard.example.com/ \
npm run build

Firewall​

Open these ports on your server:

PortService
80Website (HTTP, redirects to HTTPS)
443Website (HTTPS, Sectigo SSL)
5080HyperSDK dashboard (HTTPS, auto cert)
5070hyper2kvm dashboard (HTTPS, auto cert)

Verify​

# Website
curl -s -o /dev/null -w "%{http_code}" http://your-server/

# HyperSDK API
curl -sk https://your-server:5080/api/v1/health

Troubleshooting​

Port 5080 Already in Use​

Symptom: hypervisord fails to start with "address already in use" on port 5080.

Fix:

  1. Find the process occupying the port: 
    sudo ss -tlnp | grep 5080
  2. Stop the conflicting service, or configure HyperSDK to use a different port: 
    # /etc/hypersdk/config.yaml
    server:
      port: 5090
  3. Restart the daemon: 
    sudo systemctl restart hypervisord

SSL Certificate Errors​

Symptom: Browser shows ERR_CERT_AUTHORITY_INVALID or API clients fail with "certificate verify failed".

Fix:

  • For development: Accept the self-signed certificate in your browser, or pass -k / --insecure to curl.
  • For production: Replace the self-signed certificate with a trusted one: 
    sudo mkdir -p /etc/hypersdk/tls
    sudo cp fullchain.pem /etc/hypersdk/tls/cert.pem
    sudo cp privkey.pem /etc/hypersdk/tls/key.pem
    Then set the environment variables: 
    # In /etc/systemd/system/hypervisord.service.d/override.conf
    [Service]
    Environment=HYPERSDK_TLS_CERT=/etc/hypersdk/tls/cert.pem
    Environment=HYPERSDK_TLS_KEY=/etc/hypersdk/tls/key.pem
    Reload and restart: 
    sudo systemctl daemon-reload
    sudo systemctl restart hypervisord

Permission Denied on /var/lib/hypersdk​

Symptom: The daemon logs permission denied when writing to /var/lib/hypersdk or the upload directory.

Fix:

  1. Ensure the directory exists and is owned by the correct user: 
    sudo mkdir -p /var/lib/hypersdk
    sudo chown hypersdk:hypersdk /var/lib/hypersdk
    sudo chmod 750 /var/lib/hypersdk
  2. If running as root, check that SELinux is not blocking access: 
    sudo ausearch -m avc -ts recent
    sudo setsebool -P httpd_sys_rw_content_t 1
  3. Verify the hypervisord systemd unit is not using ProtectSystem=strict without the proper ReadWritePaths= override.

Dashboard Not Loading​

Symptom: Navigating to https://your-server:5080/web/dashboard/ shows a blank page, a 502 error, or a CORS error in the browser console.

Fix:

  1. Check that hypervisord is running: 
    sudo systemctl status hypervisord
    journalctl -u hypervisord --no-pager -n 50
  2. If using an external nginx reverse proxy, ensure the proxy configuration passes WebSocket upgrades: 
    location /ws {
        proxy_pass https://127.0.0.1:5080;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
  3. CORS errors: If the dashboard and API are on different origins, set the allowed origin in the config: 
    # /etc/hypersdk/config.yaml
    server:
      cors_origins:
        - "https://dashboard.example.com"
  4. Clear browser cache and hard-reload (Ctrl+Shift+R) to pick up updated assets after an upgrade.

API Returning 401 Unauthorized​

Symptom: API requests that previously worked now return {"error": "unauthorized", "status": 401}.

Fix:

  1. JWT token expired: The default session expiry is 30 minutes. Re-authenticate to obtain a fresh token: 
    curl -sk -X POST https://your-server:5080/api/v1/auth/login \
      -H "Content-Type: application/json" \
      -d '{"username": "admin", "password": "secret"}'
  2. RBAC role changed: If an administrator modified your role while you were logged in, the existing token may lack the required permissions. Log out and log back in.
  3. API key revoked: If using an API key for automation, verify the key has not been rotated or disabled. Check active keys at GET /api/v1/auth/keys.
  4. Clock skew: JWT validation requires the server and client clocks to be in sync. Ensure NTP is configured on both ends.

Contact us if you need help with your deployment.