sparkstudio.
Download
Development docs
Development docsMay include features newer than the installer.

Network access workshop

The preview.8 companion build provides installer choices for Local only and Network access — HTTPS, with a DNS hostname or IPv4 address for operator access. For HTTPS, choose Generate a self-signed certificate (no files needed) or supply an existing certificate and key. Managed-listener upgrades also offer Keep existing listener settings, selected by default, so an upgrade preserves its listener and certificate. Preview.7 supports supplied certificates; generated certificates require preview.8 or later.

Local management remains HTTP on 127.0.0.1, port 5090 by default. Network access adds HTTPS on 0.0.0.0, port 5443 by default, with a separate operator DNS hostname or specific IPv4 address. The two ports must differ. 0.0.0.0 is a listening address; it is never the URL operators use or the identity matched against a certificate. This version binds all IPv4 interfaces for network access; selecting a particular network interface or IPv6 network listener is not included.

Use the supplied gateway-network.json screen as a read-only connectivity exercise on an isolated evaluation gateway. This setup-required workshop has no device, database, script, account or certificate material. A project package cannot configure listeners or carry private keys. From a source checkout, use the dedicated authenticated loader below to create its draft, then review and publish it explicitly. It is cataloged as setup-required and is not included among standalone portable workshop packages.

Certificate and network prerequisites

Choose either a DNS hostname resolving to the gateway or a stable IPv4 address assigned to it. DNS is not required for IP-based access. An address must use four decimal octets without leading zeros, for example 10.20.30.40; abbreviated, hexadecimal and IPv6 forms are not supported for this network identity. Addresses starting with 0 or 224–255 are rejected. Loopback and link-local IPv4 addresses are accepted, but operators on other computers normally need a stable LAN address. Plan for certificate replacement if that address changes.

If you do not have certificate files, choose Generate a self-signed certificate (no files needed). Setup creates an RSA-3072 private key and SHA-256 certificate valid for one year, with server-authentication use and exactly the DNS name or IPv4 address you entered. It requires no certificate vendor, internet connection or separate certificate tool; IP access requires no DNS. The private key stays in the gateway's protected certificate directory. Setup also exports the public certificate as C:\ProgramData\SparkStudio\certificates\deployment\gateway-public.cer and writes the URL, fingerprint, validity and trust instructions into the adjacent gateway-trust.txt.

A generated certificate encrypts the connection, but browsers will warn until each operator computer trusts it. Using administrator access on the gateway computer, copy only gateway-public.cer to the operator computer through a trusted transfer. Compare its SHA-256 fingerprint with gateway-trust.txt on the gateway. On a Windows operator computer, double-click the .cer, choose Install Certificate → Current User → Place all certificates in the following store → Trusted Root Certification Authorities, and confirm the intended certificate. Your organization may instead deploy trust centrally or require administrator approval. Restart the browser if needed. Do not distribute the -key.pem file or the complete certificate directory, and do not suppress certificate validation. Trusting this public certificate does not give anyone its private key.

To use your organization's certificate instead, ask its network administrator for a currently valid PEM server certificate, the matching unencrypted PEM private key, and the issuing CA certificates. For a DNS hostname, the certificate needs that exact DNS subject alternative name. For an IPv4 address, it needs that exact address encoded as an iPAddress subject alternative name (SAN). A numeric DNS SAN or a common name containing the address does not satisfy IP validation. If intermediate certificates are needed, append them after the leaf certificate in the PEM certificate file. Certificates with a server-authentication EKU restriction must permit TLS server authentication. Configure the issuing CA's trust on operator computers through the site's normal procedure. Wildcard-only and common-name-only certificates are not accepted by the exact identity check. Public CA enrollment is not required, so an internal CA also works air-gapped.

Setup does not create DNS records, open firewall rules or install certificate trust. Permit the selected HTTPS TCP port on the intended Windows firewall network profile and any intervening firewall. Keep the local management port closed to remote traffic; it is bound only to loopback. No remote HTTP login listener is added.

Load the synthetic screen

On a disposable local gateway, create an administrator and save its username/password in a protected local-only JSON file. Do not put that file in source control or pass a password on the command line. From the source checkout:

$env:SPARKSTUDIO_ADMIN_AUTH_FILE = 'C:\path-to-private-fixture\admin.json'
node tools/load-network-example.mjs http://127.0.0.1:5091

The loader also accepts local port 5090, but use an isolated gateway for this exercise. It refuses an existing project with the workshop name, creates only a new project draft, and signs its temporary engineering session out afterward. The printed Designer URL opens the draft. The optional "--publish" flag performs explicit publication; otherwise publish through Designer after reviewing it. Configure HTTPS separately using the installer or Deployment editor.

Walkthrough

  1. On a disposable gateway host, use the preview.8 companion installer build and choose Network access — HTTPS. Retain a free local management port, choose a distinct free HTTPS port, and enter the operator DNS hostname or specific IPv4 address without a URL scheme or port.
  2. Choose Generate a self-signed certificate (no files needed), or choose Use an existing certificate and private key and select the certificate chain PEM and matching key PEM. Setup validates the requested identity and ports before stopping an owned service; supplied certificates also have their dates, exact identity, server usage and key correspondence checked. Generation occurs during installation, not while browsing the wizard. Both paths store the certificate and key in uniquely named files under <data-directory>/certificates/deployment/ with access limited to the service identity, Administrators and SYSTEM. Original imported files remain your responsibility.
  3. Finish setup. Its local readiness check verifies the owned process and bundled Python. A second local HTTPS request pins the installed certificate, uses the selected hostname or IP address as the TLS identity, and verifies the same process. This check does not prove trust or reachability from operator computers.
  4. On the gateway host, open the loopback management URL. If no administrator exists, read C:\ProgramData\SparkStudio\security\setup-code.txt from an elevated PowerShell and enter the code in the local setup form. Bootstrap remains local-only.
  5. Use the authenticated loader above to create the workshop project, publish it, and grant an operator account View on that project. Copy the operator application's project path, such as /runtime/<project-id>.
  6. On a second computer, establish trust as described above, then open https://your-gateway-name:your-https-port/runtime/<project-id> or, for IP access, an address such as https://10.20.30.40:5443/runtime/<project-id>. A generated certificate is expected to show a trust warning before it is installed on that computer. After trust is configured, verify the browser recognizes the intended DNS or IP identity without bypassing its warning. Sign in as the operator and confirm the screen appears. Toggle the checkbox; it changes only that browser's local input.
  7. Inspect Gateway Settings → Deployment on the gateway. Both actual listeners should be visible. Its saved listener URL is the network binding; the operator hostname or IPv4 address is a separate setting. Saving a change only stages it; restart the service deliberately to apply it.
  8. On the isolated installation, upgrade with Keep existing listener settings. Confirm the selected hostname or IP address, network port and certificate references remain unchanged. Switching explicitly to Local only removes the network intent on the next service start.

Failure, renewal and recovery

The installer rejects remote HTTP, missing/mismatched/expired supplied certificates, invalid hostnames or unsupported IP forms, conflicting ports and unowned service commands. Generated mode does not require input files. Managed service startup also rejects conflicting external URL/Kestrel/environment overrides before any listener starts. A manually configured host without the installer marker can still use explicit overrides. It retains the existing data. If installation fails after staging new deployment settings, the helper restores the previous deployment bytes and trust exports and removes only the new certificate files created by that attempt. Payload rollback is a separate installer capability and is not implied by restoring listener settings.

If the configured certificate later becomes unavailable or invalid, managed startup opens only the local recovery listener and reports a recovery condition. It does not fall back to unencrypted network access. A port collision can still prevent startup. Use the documented explicit loopback recovery override after stopping the service if necessary.

Inspect expiry in gateway-trust.txt or Gateway Settings → Deployment → Validate draft. Renewal is manual. For a generated certificate, run the installer again and deliberately select Network access → Generate a self-signed certificate, using the same identity unless you are changing the operator address. This creates a new key and certificate; copy and trust the replacement public .cer on every operator computer, and remove the obsolete certificate from their trust stores after migration. Choosing Keep existing listener settings instead preserves the existing certificate and does not renew it. An IP change also needs a certificate for the new address and updated operator links.

For a supplied certificate, place renewed PEM files in the protected deployment certificate directory, update their filename references in Gateway Settings → Deployment, validate, save and restart, or import them through the installer. No certificate or key bytes are accepted through the web form. DNS, CA trust, revocation operations, renewal automation and reverse-proxy trust remain site-managed work.

For unattended installation, use /ACCESS=network /HOSTNAME=10.20.30.40 /HTTPSPORT=5443 /CERTIFICATEMODE=self-signed. Use /CERTIFICATEMODE=provided /CERTIFICATE="C:\certs\server.pem" /PRIVATEKEY="C:\certs\server-key.pem" to import files instead. Supplying either file parameter without a certificate mode retains the earlier provided-certificate behavior. Do not combine self-signed with file parameters. Portable extraction ignores all listener pages and does not create certificates or alter trust.

Automated verification uses synthetic certificate fixtures: helper ownership/migration and rollback checks, a real certificate-pinned TLS request, and real Kestrel dual-listener startup plus local-only fallback after a missing key. Consult the preview.8 release notes for the generated-certificate fixture results. Elevated service installation with these new choices, remote-client browser trust and firewall traversal require a separate acceptance run; older preview.5 upgrade evidence does not establish them.