@ternion/t3d

CA Certificate Installation

If you're using MQTT over TLS/WSS connections with custom or self-signed certificates, you'll need to install the CA certificate to your operating system's trust store. This allows browsers and applications (including VS Code webviews) to trust certificates signed by that CA.

Manual Installation (Without CLI)

If you prefer to install the CA certificate manually without using the CLI scripts:

Windows

Option 1: Certificate Manager (GUI)

• Press Win + R, type certmgr.msc and press Enter
• Navigate to Trusted Root Certification Authorities → Certificates
• Right-click → All Tasks → Import
• Select your CA certificate file (.pem or .crt)
• Click Next → Finish
• Restart browsers/VS Code

Option 2: PowerShell (as Administrator)

certutil -addstore -f Root "path\to\ca-chain.pem"

macOS

Option 1: Keychain Access (GUI)

• Open "Keychain Access" app
• Select "System" keychain (unlock if needed)
• File → Import Items
• Select your CA certificate file
• Double-click the imported certificate
• Expand "Trust" → Set to "Always Trust"
• Close and enter your password
• Restart browsers/VS Code

Option 2: Command Line

sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain /path/to/ca-chain.pem

Linux (Ubuntu/Debian)

# Copy certificate to system certificates directory
sudo cp ca-chain.pem /usr/local/share/ca-certificates/

# Update certificate store
sudo update-ca-certificates

# Restart browsers/VS Code

For other Linux distributions, the certificate location may vary. Common locations:

• Fedora/RHEL: /etc/pki/ca-trust/source/anchors/
• Arch Linux: /etc/ca-certificates/trust-source/anchors/

Quick Installation (Using T3D CLI)

Prerequisites:

• Node.js 18+ installed
• T3D CLI installed (via npm install -g @ternion/t3d or npm link)
• Administrator/sudo privileges (required for certificate installation)
• Certificate file (.pem or .crt format)

Install CA Certificate:

t3d ca install --cert <path-to-certificate-file>

Example:

t3d ca install --cert src/mqtt-node/data/ca-chain.pem

Uninstall CA Certificate (when no longer needed):

t3d ca uninstall --cert <path-to-certificate-file>

Note: You can also pipe certificate content via stdin or use --cert-content "<PEM>" for inline PEM content. See T3D CLI User Manual for more options.

Platform-Specific Notes

• Windows: Run PowerShell or Command Prompt as Administrator
  • Certificate is added to "Trusted Root Certification Authorities"
  • You may see a User Account Control (UAC) prompt
• macOS: You'll be prompted for your administrator password
  • Certificate is added to /Library/Keychains/System.keychain
  • You can verify in the "Keychain Access" app
• Linux: You'll be prompted for your sudo password
  • Works best on Debian/Ubuntu-based distributions
  • Certificate is copied to /usr/local/share/ca-certificates/

After Installation

• Restart your web browsers (Chrome, Firefox, Safari, Edge)
• Restart VS Code if using MQTT connections
• Applications will now trust certificates signed by the installed CA

Why OS-Level Installation?

Browsers and VS Code webviews use the operating system's certificate store to validate SSL/TLS certificates. Installing the CA at the OS level ensures:

• All browsers automatically trust WSS connections
• VS Code webviews can connect to MQTT brokers over WSS
• No certificate errors when using custom/internal CA certificates

Detailed Documentation

For comprehensive information including:

• Troubleshooting common issues
• Security considerations
• Advanced installation options
• Platform-specific details

See: CA Certificate Installation Guide

Getting Started

See the main documentation:

• T3D Engine Documentation
• T3D UI Components Documentation