diff --git a/pages/guide/troubleshooting/_meta.json b/pages/guide/troubleshooting/_meta.json index d8dbf0e..1330abf 100644 --- a/pages/guide/troubleshooting/_meta.json +++ b/pages/guide/troubleshooting/_meta.json @@ -1,3 +1,4 @@ { - "browser-errors": "Common Browser Errors" + "browser-errors": "Common Browser Errors", + "developer-tools": "CLI & Language Support" } \ No newline at end of file diff --git a/pages/guide/troubleshooting/developer-tools.mdx b/pages/guide/troubleshooting/developer-tools.mdx new file mode 100644 index 0000000..6d3687e --- /dev/null +++ b/pages/guide/troubleshooting/developer-tools.mdx @@ -0,0 +1,91 @@ +import { Callout, Steps } from 'nextra/components' +import { Terminal, Code, Server } from 'lucide-react' + +# CLI & Language Issues + +Even if you installed the Root CA on your operating system, many developer tools and programming languages **ignore the system store** and use their own. + +If your code or scripts are failing with certificate errors, check the solutions below. + +## 1. cURL & Wget + +Standard command-line tools often look for a specific bundle file. + +### cURL +}> + `curl: (60) SSL certificate problem: unable to get local issuer certificate` + + +**Solution:** +Pass the Root CA explicitly: +```bash +curl --cacert /path/to/trustlab-root.crt https://your-domain.local +``` + +### Wget +**Solution:** +```bash +wget --ca-certificate=/path/to/trustlab-root.crt https://your-domain.local +``` + +--- + +## 2. Node.js / JavaScript + +Node.js does not use the System Root CA by default. + +}> + `Error: self signed certificate in certificate chain` + + +**Solution (Environment Variable):** +Set this variable before running your application. It works for most Node.js apps (npm, yarn, custom scripts). + +```bash +export NODE_EXTRA_CA_CERTS="/path/to/trustlab-root.crt" +node server.js +``` + +--- + +## 3. Python (Requests/Pip) + +Python's `requests` library (and `pip`) uses its own certificate bundle (`certifi`), ignoring Windows/macOS/Linux system stores. + +}> + `SSLError(SSLCertVerificationError(1, '[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed'))` + + +**Solution:** +Point to your Root CA using an environment variable. + +```bash +export REQUESTS_CA_BUNDLE="/path/to/trustlab-root.crt" +python script.py +``` + +--- + +## 4. Java Applications + +Java uses a proprietary "Keystore" (JKS) and typically **ignores** the Windows Certificate Store. + +}> + `sun.security.validator.ValidatorException: PKIX path building failed` + + +**Solution:** +You must import the TrustLab Root CA into the Java Keystore (cacerts). + + +### Locate standard cacerts +Usually at `$JAVA_HOME/lib/security/cacerts`. + +### Import with keytool +```bash +keytool -import -trustcacerts -alias trustlab-root \ + -file trustlab-root.crt \ + -keystore "$JAVA_HOME/lib/security/cacerts" +``` +*Default password is typically `changeit`.* +