From 567b27a4782ddf2a588ee55183afeccd9855ab5d Mon Sep 17 00:00:00 2001
From: Marcin Rataj <lidel@lidel.org>
Date: Wed, 27 Nov 2024 18:34:33 +0100
Subject: [PATCH] docs: Corefile for production and local dev  (#10)

* docs: document production Corefile

it was missing acme section, and docs were also lacking context

* docs: Corefile.local-dev

documenting how to get started locally, saving an hour figuring it out
---
 .dockerignore      |  2 ++
 .gitignore         |  1 +
 Corefile           | 13 +++++++++++++
 Corefile.local-dev | 14 ++++++++++++++
 README.md          | 25 +++++++++++++++++--------
 5 files changed, 47 insertions(+), 8 deletions(-)
 create mode 100644 Corefile.local-dev

diff --git a/.dockerignore b/.dockerignore
index 44b8fd0..867dd74 100644
--- a/.dockerignore
+++ b/.dockerignore
@@ -1,5 +1,7 @@
 Corefile
+Corefile.local-dev
 zones
 p2p-forge
 p2p-forge-certs/
 badger.libp2p-direct-challenges/
+registration_libp2p_direct-certs/
diff --git a/.gitignore b/.gitignore
index f1552d3..ea8cc30 100644
--- a/.gitignore
+++ b/.gitignore
@@ -4,3 +4,4 @@ cmd/cmd
 p2p-forge
 p2p-forge-certs/
 badger.libp2p-direct-challenges/
+registration_libp2p_direct-certs/
diff --git a/Corefile b/Corefile
index e7008c5..734b78e 100644
--- a/Corefile
+++ b/Corefile
@@ -1,3 +1,5 @@
+# this file demonstrates reference production settings.
+# for local development use: ./p2p-forge -conf Corefile.local-dev
 libp2p.direct {
     log
     errors
@@ -5,4 +7,15 @@ libp2p.direct {
     prometheus localhost:9253
     ipparser libp2p.direct
     file zones/libp2p.direct
+    acme libp2p.direct {
+        # HTTP API at /v1/_acme-challenge
+        # production settings: TLS is terminated elsewhere:
+        registration-domain registration.libp2p.direct listen-address=:80 external-tls=true
+        # to handle tls termination as well, use: listen-address=:443 external-tls=false
+        #
+        # DNS-01 challenge cache
+        # production settings: DynamoDB shared across all instances
+        database-type dynamo libp2p-direct-challenges
+        # for local dev with badger: database-type badger badger.libp2p-direct-challenges
+    }
 }
diff --git a/Corefile.local-dev b/Corefile.local-dev
new file mode 100644
index 0000000..62fb7c3
--- /dev/null
+++ b/Corefile.local-dev
@@ -0,0 +1,14 @@
+# for local development on ports 5354 (dns) and 5380 (http)
+# run with: ./p2p-forge -conf Corefile.local-dev -dns.port 5354
+libp2p.direct {
+    log
+    errors
+    any # RFC 8482
+    prometheus localhost:9253
+    ipparser libp2p.direct
+    file zones/libp2p.direct
+    acme libp2p.direct {
+        registration-domain registration.libp2p.direct listen-address=:5380 external-tls=true
+        database-type badger badger.libp2p-direct-challenges
+    }
+}
diff --git a/README.md b/README.md
index 5630616..ea4481d 100644
--- a/README.md
+++ b/README.md
@@ -96,17 +96,26 @@ Will download using go mod, build and install the binary in your global Go binar
 
 ### Local testing
 
-Build and run a custom Corefile configuration and on custom port:
+Build and run a custom Corefile configuration and on custom ports (DNS port set to `5354` via CLI, HTTP port set to `5380` via custom Corefile):
 
 ```console
-$ ./p2p-forge -conf Corefile.example -dns.port 5353
+$ ./p2p-forge -conf Corefile.local-dev -dns.port 5354
 ```
 
 Test with `dig`:
 
 ```console
-$ dig A 1-2-3-4.k51qzi5uqu5dlwfht6wwy7lp4z35bgytksvp5sg53fdhcocmirjepowgifkxqd.libp2p.direct @localhost -p 5353
+$ dig A 1-2-3-4.k51qzi5uqu5dlwfht6wwy7lp4z35bgytksvp5sg53fdhcocmirjepowgifkxqd.libp2p.direct @localhost -p 5354
 1.2.3.4
+
+$ curl http://localhost:5380/v1/health -I
+HTTP/1.1 204 No Content
+```
+
+To run on port `53` as non-root user, adjust permission:
+
+```console
+$ sudo setcap cap_net_bind_service=+ep /path/to/p2p-forge
 ```
 
 ### Docker
@@ -154,13 +163,13 @@ acme FORGE_DOMAIN {
 }
 ~~~
 
-- **FORGE_DOMAIN** the domain of the forge (e.g. libp2p.direct)
-- **REGISTRATION_DOMAIN** the domain used by clients to send requests for setting ACME challenges (e.g. registration.libp2p.direct)
+- **FORGE_DOMAIN** the domain suffix of the forge (e.g. `libp2p.direct`)
+- **REGISTRATION_DOMAIN** the HTTP API domain used by clients to send requests for setting ACME challenges (e.g. `registration.libp2p.direct`)
    - **ADDRESS** is the address and port for the internal HTTP server to listen on (e.g. :1234), defaults to `:443`.
-   - external-tls should be set to true if the TLS termination (and validation of the registration domain name) will happen externally or should be handled locally, defaults to false
+   - `external-tls` should be set to `true` if the TLS termination (and validation of the registration domain name) will happen externally or should be handled locally, defaults to false
 - **DB_TYPE** is the type of the backing database used for storing the ACME challenges. Options include:
-    - dynamo TABLE_NAME (where all credentials are set via AWS' standard environment variables)
-    - badger DB_PATH
+  - `dynamo TABLE_NAME` for production-grade key-value store shared across multiple instances (where all credentials are set via AWS' standard environment variables: `AWS_REGION`, `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`)
+  - `badger DB_PATH` for local key-value store (good for local development and testing)
 
 ### Example