wip

.github/workflows/tests.yml

@@ -517,7 +517,7 @@ jobs:
         actual_exit_code="$(with_backoff ssh-uuid -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null \
           ${{ steps.register-test-device.outputs.balena_device_uuid }}.balena \
           "balena ps -q | xargs balena inspect \
-          | jq -re '.[] | select(.Name | contains(\"sut_\")).State.ExitCode'")
+          | jq -re '.[] | select(.Name | contains(\"sut_\")).State.ExitCode'")"
 
         [[ $expected_exit_code -eq $actual_exit_code ]] || false
 

Makefile

@@ -1,24 +1,26 @@
 .PHONY: lint
 
 TMPKI := $(shell mktemp)
-DNS_TLD ?= openbalena.local
+DNS_TLD ?= api.openbalena.local
 
 lint:
 	find . -type f -name *.sh | xargs shellcheck
 
-update-pki:
-	true | openssl s_client -showcerts -connect $(DNS_TLD):443 \
+pki:
+	true | openssl s_client -showcerts -connect api.$(DNS_TLD):443 \
 	  | awk '/BEGIN CERTIFICATE/,/END CERTIFICATE/ {print $0}' > $(TMPKI).ca
 
 	cat <$(TMPKI).ca | openssl x509 -text \
 	  | awk '/BEGIN CERTIFICATE/,/END CERTIFICATE/ {print $0}' > $(TMPKI).srv
 
-	mkdir -p /usr/local/share/ca-certificates
+	mkdir -p /usr/local/share/ca-certificates .balena
 	diff --suppress-common-lines --unchanged-line-format= $(TMPKI).srv $(TMPKI).ca \
-	  >/usr/local/share/ca-certificates/open-balena.pem || true
+	  >/usr/local/share/ca-certificates/ca-$(DNS_TLD).pem || true
 
 	update-ca-certificates
-	cat </usr/local/share/ca-certificates/open-balena.pem
+	cat </usr/local/share/ca-certificates/ca-$(DNS_TLD).pem >.balena/ca-$(DNS_TLD).pem
+
+test:
 	curl --fail --retry 3 --silent https://api.$(DNS_TLD)/ping
 
 up:

docs/getting-started.md

@@ -53,67 +53,80 @@ make update
 #### Test the openBalena server
 
 To confirm that everything is running correctly, try a simple request from the
-local machine to the server:
+local machine to the server after registering its root CA certificate(s) with the
+local SSL trust store:
 
 ```bash
-make update-pki
+make pki && make test
 ```
 
 Congratulations! The openBalena server is up and running. The next step is to
 setup the local machine to use the server, provision a device and deploy a
 small project.
 
-#### Domain Configuration
+### Install self-signed certificates on the local machine.
 
-The following CNAME records must be configured to point to the openBalena server:
+The installation of the openBalena server produces a self-signed certificate,
+which must be trusted by all devices communicating with it.
 
-```text
-api.mydomain.com
-registry.mydomain.com
-cloudlink.mydomain.com
-s3.mydomain.com
-tunnel.mydomain.com
-```
-
-Check with your internet domain name registrar for instructions on how to
-configure CNAME records.
-
-
-### Install self-signed certificates on the local machine
-
-The installation of the openBalena server produces a few self-signed certificates
-that must be installed on the local machine, so that it can securely communicate
-with the server.
-
-The root certificate is found at `config/certs/root/ca.crt` on the server. Copy
-it to some folder on the local machine and keep a note to the path -- it will be
-used later during the CLI installation. Follow the steps below for the specific
-platform of the local machine.
+The root CA bundle can be found at `.balena/ca-${DNS_TLD}.pem`. Follow the steps
+below for your specific local machine platform after copying it across.
 
 #### Linux:
 
 ```bash
-sudo cp ca.crt /usr/local/share/ca-certificates/ca.crt
+sudo cp ca-bundle.pem /usr/local/share/ca-certificates/ca.crt
 sudo update-ca-certificates
 sudo systemctl restart docker
 ```
 
 #### macOS:
 
 ```bash
-sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain ca.crt
+sudo security add-trusted-cert -d \
+  -r trustRoot \
+  -k /Library/Keychains/System.keychain \
+  ca-bundle.pem
+
 osascript -e 'quit app "Docker"' && open -a Docker
 ```
 
 #### Windows:
 
 ```bash
-certutil -addstore -f "ROOT" ca.crt
+certutil -addstore -f "ROOT" ca-bundle.pem
 ```
 
 The Docker daemon on the local machine must then be restarted for Docker to
 pick up the new certificate.
 
+#### Domain Configuration
+
+While mDNS is usually fine for local development and evaluating the product, it is
+unsuitable for production deployments.
+
+
+The following CNAME records must be configured to point to the openBalena server:
+
+
+```text
+api.mydomain.com
+registry.mydomain.com
+cloudlink.mydomain.com
+s3.mydomain.com
+tunnel.mydomain.com
+```
+
+Check with your internet domain name registrar for instructions on how to
+configure CNAME records.
+
+
+
+
+
+
+
+
 ### Install the balena CLI on the local machine
 
 Follow the [balena CLI installation