Skip to main content

Server

The Server page groups controller-level configuration and connectivity into six tabs: General (operational flags and site identity), Email (outbound SMTP), SMS (outbound text alerts), Network & Database (read-only connection info), SSL / TLS (HTTPS certificates), and Tunnel (the reverse connection to the cloud orchestrator).

The General, Email, SMS, and Network tabs edit sections of the on-disk gem.json configuration file. Saves are atomic (written to a temporary file and renamed) and only touch the keys exposed in the form, so unrelated gem.json sections are preserved. Some changes — server ports, the REST API toggle, SMTP server/credentials — take effect only after a restart.

:::info Secrets are write-only Passwords and API keys are never sent back to the browser. Each secret field shows only whether a value is currently set (•••••••• (unchanged)) and is left blank on load. Leave it blank to keep the stored value; type a new value only to replace it. :::

General​

The General tab edits operational flags and site identity stored in gem.json.

SettingDescription
Start OfflineStart GEM even if devices are unreachable
REST APIEnable the /api endpoints (takes effect after restart)
Device AlertsEmail when a device goes offline
Alert ThresholdConsecutive monitor failures before a device alert is sent
Start AlertEmail when GEM starts
Failed Start AlertEmail when startup fails
Monitor AlertEmail on monitor (ping) state changes
External URLPublic URL used in notifications and links
LocationSite location used for weather and sunrise/sunset

Click Save to write the section back to gem.json.

Email​

The Email tab configures the outbound SMTP server used for alerts and notifications.

FieldDescription
SMTP HostMail server hostname
PortSMTP port (e.g. 587 for STARTTLS, 465 for implicit TLS)
Secure ConnectionUse implicit TLS (SMTPS)
UsernameSMTP authentication user
PasswordSMTP authentication password (write-only — leave blank to keep current)
From AddressEnvelope/from address for outbound mail
Default RecipientDefault destination for alert emails

Server and credential changes take effect after a restart.

SMS​

The SMS tab configures outbound text alerts via Telnyx.

FieldDescription
From NumberSending number in E.164 format (e.g. +15551234567)
Default RecipientDefault destination number
Telnyx API KeyTelnyx API key (write-only — leave blank to keep current)

If gem.json specifies a non-Telnyx provider, that provider is reported as read-only here and must be managed directly in gem.json.

Network & Database​

The Network & Database tab is read-only. It displays the listen port and database connection (dialect, host, port, name, user) read from gem.json at boot.

warning

The database connection is not editable from the admin UI — an incorrect value could prevent GEM from starting. Change these settings directly in gem.json and restart.

SSL / TLS​

The SSL / TLS tab manages HTTPS certificates for secure browser connections to GEM. GEM uses a self-signed Certificate Authority (CA) to issue certificates, providing enterprise-grade encryption without dependency on external certificate providers.

Overview​

GEM's SSL implementation:

  • Self-Signed CA: GEM creates its own Certificate Authority
  • Automatic Certificates: Server certificates generated automatically
  • Subject Alternative Names (SANs): Includes all detected IP addresses
  • Auto-Renewal: Certificates regenerate on expiry or IP changes (when enabled)
  • Easy Device Trust: One-time CA installation on each device

Certificate Status​

The status section displays current certificate information:

SSL Status​

  • Enabled: HTTPS is active, HTTP redirects to HTTPS
  • Disabled: HTTP only (no encryption)

CA Certificate​

  • Generated: Certificate Authority is created
  • Not Generated: SSL not configured (enable and restart to create)

Server Certificate​

  • Generated: Server certificate is active
  • Not Generated: Server certificate not created

Expiration​

  • Expires: Certificate expiration date
  • Days remaining: Countdown to expiration
  • ⚠️ Warning: Shows in red when < 30 days remaining

IP Match​

  • OK: Certificate SANs match current server IPs
  • IPs Changed: Server IP addresses changed since certificate creation
    • Certificate should be regenerated to match new IPs
    • Clients may see warnings when connecting via new IPs

SANs (Subject Alternative Names)​

Lists all IP addresses and hostnames included in the server certificate:

192.168.1.100, 10.0.0.50, gem-server.local

Browsers check this list when connecting via HTTPS.

Configuration​

Enable SSL​

Toggle Enable SSL to activate/deactivate HTTPS.

When Enabled:

  • Server listens on HTTPS port (default: 443)
  • HTTP port redirects to HTTPS
  • Certificates are generated on first restart
  • Client devices can access via HTTPS

When Disabled:

  • Server listens on HTTP port only
  • No encryption or certificate validation
  • Simpler configuration for local-only installations

HTTPS Port​

Port for encrypted connections (default: 443)

Common Ports:

  • 443: Standard HTTPS (requires root/admin privileges)
  • 8443: Alternative HTTPS (no special privileges needed)
  • 9000: Custom port

Firewall: Ensure chosen port is open in firewall.

HTTP Port​

Port for unencrypted connections (default: 80)

Uses:

  • CA certificate download (works without trust)
  • Redirect to HTTPS
  • Initial setup before devices trust CA

Auto-Regenerate​

When enabled, GEM automatically regenerates certificates when:

  • Certificate approaches expiration (< 30 days)
  • Server IP addresses change
  • Hostname changes

Recommended: Enabled (default)

Prevents expired certificates and IP mismatch issues.

Saving Configuration​

  • Save: Saves configuration only
  • Save & Restart: Saves and restarts GEM to apply changes

SSL changes require a restart to take effect.

CA Certificate Download​

Why Download the CA Certificate?​

Each client device (browser, tablet, phone) must trust GEM's CA certificate to:

  • Avoid browser security warnings
  • Enable secure HTTPS connections
  • Allow embedded webviews to load

One-Time Setup: Each device installs the CA once. Future server certificate renewals work automatically.

Download Formats​

PEM Format (.pem):

  • Text-based format
  • Use for: macOS, Linux, Chrome, Firefox
  • View in text editor

DER Format (.crt):

  • Binary format
  • Use for: Windows, iOS, Android
  • Double-click to install

HTTP Download URL​

When SSL is enabled, GEM serves the CA certificate over HTTP:

http://192.168.1.100:80/ssl/ca.pem
http://192.168.1.100:80/ssl/ca.crt

Why HTTP?: Devices can download without already trusting the certificate (chicken-and-egg problem).

Installation Instructions​

The page provides platform-specific installation guides:

iOS / iPadOS​

  1. Open Safari and navigate to http://<server-ip>:<http-port>/ssl/ca.pem
  2. Tap "Allow" when prompted to download profile
  3. Open Settings > General > VPN & Device Management
  4. Tap "GEM Local CA" profile and install
  5. Go to Settings > General > About > Certificate Trust Settings
  6. Enable full trust for "GEM Local CA"

Important: Must use Safari, not Chrome or other browsers.

Android​

  1. Download the .crt file from http://<server-ip>:<http-port>/ssl/ca.crt
  2. Open Settings > Security > Encryption & credentials
  3. Tap "Install a certificate" > "CA certificate"
  4. Select the downloaded gem-ca.crt file
  5. Confirm installation

Note: Steps vary slightly by Android version and manufacturer.

Windows​

  1. Download the .crt file
  2. Double-click the file
  3. Click "Install Certificate"
  4. Select "Local Machine" and click Next
  5. Select "Place all certificates in the following store"
  6. Click Browse and select "Trusted Root Certification Authorities"
  7. Click Next and Finish

Requires: Administrator privileges

macOS​

  1. Download the .pem file
  2. Double-click to open in Keychain Access
  3. Add to the "System" keychain
  4. Find "GEM Local CA" in the certificate list
  5. Double-click, expand "Trust"
  6. Set to "Always Trust"
  7. Close and authenticate with password

Ubuntu / Debian​

Terminal commands:

# Download CA certificate
wget http://192.168.1.100:80/ssl/ca.crt -O gem-ca.crt

# Install system-wide
sudo cp gem-ca.crt /usr/local/share/ca-certificates/gem-ca.crt
sudo update-ca-certificates

# For Chrome browser
certutil -d sql:$HOME/.pki/nssdb -A -t "C,," -n "GEM Local CA" -i gem-ca.crt

# For Firefox
# Import via Settings > Privacy & Security > Certificates > View Certificates > Import

Copy Commands: Click Copy Commands button to copy to clipboard.

Certificate Management​

Regenerate Server Certificate​

Creates a new server certificate signed by the existing CA.

When to Use:

  • Certificate expiring soon
  • IP addresses changed
  • Hostname changed
  • SANs need updating

Impact:

  • Devices already trusting CA: No action needed
  • New certificate is trusted automatically
  • No client device reconfiguration

Process:

  1. Click Regenerate Server Cert
  2. New certificate generated with current IP addresses
  3. Server certificate updated
  4. Restart may be required

Regenerate All Certificates​

Creates a new CA and server certificate.

When to Use:

  • CA certificate compromised
  • Starting fresh
  • CA certificate expiring (rare, usually 10-year validity)

Impact:

  • All devices lose trust
  • Must re-install new CA on all devices
  • Significant reconfiguration effort

Process:

  1. Click Regenerate All
  2. Confirmation dialog warns about impact
  3. Click Regenerate All to confirm
  4. New CA and server certificates created
  5. Download new CA certificate
  6. Re-install on all client devices

Important: Only use when absolutely necessary. Server-only regeneration is preferred.

Common Workflows​

Initial SSL Setup​

  1. Navigate to System > Server and open the SSL / TLS tab
  2. Enable Enable SSL
  3. Configure ports (443/80 recommended)
  4. Enable Auto-Regenerate
  5. Click Save & Restart
  6. Wait for GEM to restart
  7. Download CA certificate (both .pem and .crt)
  8. Install on all client devices
  9. Access GEM via https://<server-ip>

Adding a New Client Device​

  1. On the new device, navigate to http://<server-ip>:<http-port>/ssl/ca.pem (or .crt)
  2. Follow platform-specific installation instructions
  3. Access GEM via HTTPS
  4. Verify no security warnings

Server IP Address Changed​

If Auto-Regenerate Enabled:

  1. GEM detects IP change
  2. Automatically regenerates server certificate
  3. Restarts server
  4. Devices continue working (same CA)

If Auto-Regenerate Disabled:

  1. Access shows "IP Changed" warning
  2. Manually click Regenerate Server Cert
  3. Server certificate updated with new IPs
  4. Access via new IP works without warnings

Certificate Expiring Soon​

If Auto-Regenerate Enabled:

  • Certificate automatically renews when < 30 days remaining
  • No manual intervention needed

If Auto-Regenerate Disabled:

  1. Status shows expiry warning
  2. Click Regenerate Server Cert
  3. New certificate issued with extended validity

Security Considerations​

Self-Signed vs. Public CA​

Self-Signed (GEM's Approach):

  • ✅ No external dependencies
  • ✅ Works offline
  • ✅ No recurring costs
  • ✅ Full control
  • ⚠️ Requires manual trust installation
  • ⚠️ Not trusted by default

Public CA (Let's Encrypt, etc.):

  • ✅ Trusted by default
  • ✅ No manual installation
  • ⚠️ Requires public DNS
  • ⚠️ Requires internet connectivity
  • ⚠️ External dependency
  • ⚠️ Not suitable for local-only networks

GEM's Choice: Self-signed is appropriate for local automation systems.

CA Key Security​

The CA private key is the most sensitive component:

Protection:

  • Stored with restrictive file permissions
  • Not exposed via web interface
  • Not included in backups by default

Compromise Scenarios:

  • Physical server access
  • Backup file theft (if included)
  • Root-level system compromise

If Compromised:

  1. Regenerate all certificates
  2. Re-install CA on all devices
  3. Review access logs
  4. Investigate breach source

HTTPS Benefits​

  • Encryption: All traffic encrypted in transit
  • Authentication: Verifies server identity
  • Integrity: Prevents man-in-the-middle attacks
  • Compliance: Required for many security standards

HTTP Fallback​

GEM keeps HTTP port active even with SSL enabled:

Use Cases:

  • CA certificate download
  • Initial setup
  • Troubleshooting

Security Note: HTTP port only serves:

  • CA certificate
  • Redirect to HTTPS

Configuration and control interfaces require HTTPS.

Troubleshooting​

Browser Shows "Not Secure" Warning​

Causes:

  1. CA certificate not installed on this device
  2. Wrong CA certificate installed
  3. Certificate expired
  4. IP mismatch

Solutions:

  1. Download and install current CA certificate
  2. Verify certificate is "GEM Local CA"
  3. Check expiration date in certificate status
  4. Regenerate server certificate if IPs changed

Mobile App Can't Connect​

Symptoms: App shows connection error or certificate warning

Solutions:

  1. Install CA certificate using platform instructions
  2. Verify HTTPS port is accessible (firewall)
  3. Confirm Auto-Regenerate is enabled
  4. Check if accessing via IP in SANs list

Certificate Installation Fails​

iOS: Must use Safari browser, not Chrome Android: May need to set screen lock PIN first Windows: Need administrator privileges macOS: Must authenticate with password

"NET::ERR_CERT_COMMON_NAME_INVALID"​

Cause: Accessing via IP not in certificate SANs

Solutions:

  1. Access via an IP in the SANs list
  2. Regenerate server certificate to add current IPs
  3. Enable Auto-Regenerate to prevent recurrence

Regenerate Button Disabled​

Cause: No CA certificate exists yet

Solution: Enable SSL and restart to generate initial certificates

Advanced Topics​

Multiple Network Interfaces​

GEM automatically detects all network interfaces:

  • Ethernet
  • Wi-Fi
  • VPN interfaces
  • Docker bridges (if applicable)

All IPs are included in server certificate SANs.

Excluding Interfaces: Not currently configurable. All IPs are included.

Custom Hostnames​

Add custom hostname to certificate:

  1. Configure DNS or hosts file: gem-server.local → server IP
  2. Regenerate server certificate (auto-includes hostname)
  3. Access via https://gem-server.local

Certificate Validity Period​

  • CA Certificate: 10 years
  • Server Certificate: 2 years

Auto-regenerate renews server certificate when < 30 days remain.

Port Conflicts​

Port 443 Already in Use:

  • Another service is using HTTPS port
  • Choose alternative port (8443, 9000)
  • Update firewall rules

Port 80 Already in Use:

  • Another web server is running
  • Choose alternative HTTP port
  • Update CA download URLs in documentation

Firewall Configuration​

Open required ports in firewall:

iptables (Linux):

sudo iptables -A INPUT -p tcp --dport 443 -j ACCEPT
sudo iptables -A INPUT -p tcp --dport 80 -j ACCEPT

firewalld (RHEL/CentOS):

sudo firewall-cmd --permanent --add-port=443/tcp
sudo firewall-cmd --permanent --add-port=80/tcp
sudo firewall-cmd --reload

ufw (Ubuntu):

sudo ufw allow 443/tcp
sudo ufw allow 80/tcp

Best Practices​

  1. Enable Auto-Regenerate: Prevents expiration and IP mismatch issues

  2. Document CA Installation: Create site-specific installation guide for technicians

  3. Test on All Platforms: Verify CA installation process on all client device types

  4. Backup CA Certificate: Download and store CA certificate in documentation

  5. Monitor Expiration: Even with auto-regenerate, monitor expiration dates

  6. Use Standard Ports: 443/80 unless there's a conflict

  7. Secure Server Access: Protect physical and remote access to GEM server

  8. Update Documentation: When regenerating all certificates, update client documentation

Tunnel​

The Tunnel tab controls the reverse connection from this controller to the cloud orchestrator. The tunnel is a single persistent outbound WebSocket that lets the orchestrator reach the controller for remote management without any inbound port forwarding or public IP.

How it works​

The controller initiates the connection outbound, so nothing needs to be opened on the site firewall. The connection binding — orchestrator URL, tenant, and a short-lived rotating token — is delivered automatically inside the signed update check; the controller does not store long-lived credentials. You normally only decide whether the tunnel runs.

Enable Tunnel​

Toggle Enable Tunnel to start or stop the connection. Changes take effect immediately — no restart required. Disabling stops the active tunnel; re-enabling reconnects and fetches a fresh token on the next update check.

The toggle is backed by the tunnel system attribute. When no attribute is set, the tunnel defaults to on.

Status​

The status panel reflects the live transport:

  • State: Connected, Connecting, Reconnecting, Waiting (enabled but no binding yet), Disabled, or Identity Fail
  • Connected: whether the WebSocket is currently established
  • Identity Pinned: whether the orchestrator's public key is pinned and verified. Unpinned means the orchestrator's identity is not cryptographically verified — set orchestrator_pubkey to pin it
  • Orchestrator URL / Tenant / Site: the active binding
  • Active Streams: in-flight multiplexed requests
  • Last Connected / Reconnect In: connection age and current backoff
  • Config Source: whether the effective config came from gem.json or the tunnel system attribute
  • Last Error / Reconcile Error: most recent transport or reconciliation failure

Refresh re-reads the status on demand; the panel also polls periodically.

Advanced​

Advanced binding overrides — orchestrator url, tenant_id, and pinned orchestrator_pubkey — are set on the tunnel system attribute under System → Attributes. The attribute is a single JSON object that fully overrides the gem.json tunnel block, so include every field you need:

{ "enabled": true, "url": "wss://tunnel.example.com", "tenant_id": "…", "orchestrator_pubkey": "…hex…" }

A read-only Orchestrator Tunnel dashboard widget shows the same status at a glance; add it from the admin dashboard's Customize editor.