From 9eb8ecf2ab1136096ebb4d02332a008a9b1aa17b Mon Sep 17 00:00:00 2001
From: Anton Belodedenko <2033996+ab77@users.noreply.github.com>
Date: Mon, 29 Apr 2024 21:09:28 -0700
Subject: [PATCH] woip

---
 .github/workflows/tests.yml |  4 +--
 Makefile                    | 19 ++++++------
 docs/getting-started.md     | 61 +++++++++++++++++++++++++++++--------
 3 files changed, 59 insertions(+), 25 deletions(-)

diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
index 88fc04035..7d363f1a1 100644
--- a/.github/workflows/tests.yml
+++ b/.github/workflows/tests.yml
@@ -400,7 +400,7 @@ jobs:
         # wait for services to start running
         while with_backoff ssh-uuid -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null \
           ${{ steps.register-test-device.outputs.balena_device_uuid }}.balena \
-          'balena ps -aq | xargs balena inspect | jq -r .[].State.Status' \
+          'balena ps -q | xargs balena inspect | jq -r .[].State.Status' \
           | grep -E 'created|restarting|removing|paused|exited|dead'; do
 
             echo "::warning::Still working..."
@@ -410,7 +410,7 @@ jobs:
         # wait for Docker healthchecks
         while with_backoff ssh-uuid -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null \
           ${{ steps.register-test-device.outputs.balena_device_uuid }}.balena \
-          'balena ps -aq | xargs balena inspect \
+          'balena ps -q | xargs balena inspect \
           | jq -r ".[] | select(.State.Health.Status!=null).Name + \":\" + .State.Health.Status"' \
           | grep -E ':starting|:unhealthy'; do
 
diff --git a/Makefile b/Makefile
index 7582730e2..0077e01e4 100644
--- a/Makefile
+++ b/Makefile
@@ -42,23 +42,22 @@ update:
 
 pki-cloudflare:
 	echo "CLOUDFLARE_API_TOKEN=$(CLOUDFLARE_API_TOKEN)" >> .env
+	sed -i 's/DNS_TLD/d' .env
 	sed -i 's/MDNS_TLD/d' .env
+	echo "DNS_TLD=$(DNS_TLD)" >> .env
 	echo "MDNS_TLD=" >> .env
 	docker compose restart
 
 pki-gandi:
 	echo "GANDI_API_TOKEN=$(GANDI_API_TOKEN)" >> .env
+	sed -i 's/DNS_TLD/d' .env
 	sed -i 's/MDNS_TLD/d' .env
+	echo "DNS_TLD=$(DNS_TLD)" >> .env
 	echo "MDNS_TLD=" >> .env
 	docker compose restart
 
-
-	  * specify `DNS_TLD` (e.g. `openbalena.foo.com`)
-  * unset `MDNS_TLD`
-  * set `ACME_EMAIL` to be notified about SSL certificate renewal issues; and
-  * specify either `GANDI_API_TOKEN` or `CLOUDFLARE_API_TOKEN` scoped to create DNS
-    entries under `DNS_TLD`; or
-  * manually obtain a wildcard SSL certificate covering `*.dns_tld` and place into
-    `/certs/export/chain.pem` (e.g. mounted on `cert-manager`, `haproxy` containers, etc.)
-
-
+pki-custom:
+	echo "HAPROXY_CRT=$(HAPROXY_CRT)" >> .env
+	echo "HAPROXY_KEY=$(HAPROXY_KEY)" >> .env
+	echo "ROOT_CA=$(ROOT_CA)" >> .env
+	docker compose restart
diff --git a/docs/getting-started.md b/docs/getting-started.md
index bcc233a1e..0314b57f4 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -105,6 +105,45 @@ pick up the new certificate.
 While mDNS is sufficient for evaluating the product, it is unlikely to be suitable for
 production deployments.
 
+opeBalena server supports automatic DNS/TLS PKI configuration via ACME protocol and this
+is the easiest way to configuring public DNS/SSL. The following providers are currently
+supported:
+
+* Cloudflare
+* Gandi
+
+#### Cloudflare
+
+1. Obtain a Cloudflare API token with write access to your domain name records:
+
+```bash
+export DNS_TLD=mydomain.com
+export ACME_EMAIL=admin@mydomain.com
+export CLOUDFLARE_API_TOKEN={{token}}
+```
+
+2. Configure openBalena server:
+
+```bash
+make pki-cloudflare
+```
+
+#### Gandi
+
+1. Obtain a Gandi API token with write access to your domain name records:
+
+```bash
+export DNS_TLD=mydomain.com
+export ACME_EMAIL=admin@mydomain.com
+export GANDI_API_TOKEN={{token}}
+```
+
+2. Configure openBalena server:
+
+```bash
+make pki-gandi
+```
+
 The following CNAME records must be configured to point to the openBalena server:
 
 ```text
@@ -118,23 +157,19 @@ s3.mydomain.com
 tunnel.mydomain.com
 ```
 
-Check with your Internet domain name registrar for instructions on how to obtain a DNS
-domain and configure CNAME records.
-
-opeBalena server also supports automatic DNS/TLS PKI configuration via ACME protocol. The
-following providers are currently supported:
+Alternatively you may consider configuring a single wildcard DNS record `*.mydomain.com`.
 
-* Cloudflare
-* Gandi
+openBalena server also supports custom/manual DNS/TLS configuration. Check with your
+Internet domain name registrar for instructions on how to obtain a DNS domain and
+configure CNAME records. You will also need to supply you own SSL certificate, private key
+and a full certificate signing chain. A wildcard SSL certificate is recommended.
 
-To use this feature..
+After obtaining a custom SSL certificate, run the following commands on openBalena server:
 
+```bash
+make pki-custom
+```
 
-  * specify `DNS_TLD` (e.g. `openbalena.foo.com`)
-  * unset `MDNS_TLD`
-  * set `ACME_EMAIL` to be notified about SSL certificate renewal issues; and
-  * specify either `GANDI_API_TOKEN` or `CLOUDFLARE_API_TOKEN` scoped to create DNS
-    entries under `DNS_TLD`; or
   * manually obtain a wildcard SSL certificate covering `*.dns_tld` and place into
     `/certs/export/chain.pem` (e.g. mounted on `cert-manager`, `haproxy` containers, etc.)