README/docs refresh #3876

cpu · 2018-09-28T18:29:54Z

This is primarily based on @rolandshoemaker's readme-updates branch and the closed PR: #3195

The README is restructured to be user-driven. Information that is strictly contributor focused (e.g. dep upgrades) is moved to CONTRIBUTING.md. The review feedback from #3195 from @jsha was all about text that we removed entirely in 29cdd78

The README now links to the production deployment guide in the wiki and describes our general position on using Boulder.

The CONTRIBUTING.md guide links to the various docs/ pages and was updated.

The docs/acme-divergences page is updated for draft-15.

The DESIGN.md document is moved from the root of the repo into docs/. It has been updated to cover ACMEv2 and precertificates/SCT embedding.

Resolves #3850

This is primarily based on Roland's `readme-updates` branch and the closed PR[0]. The README is restructured to be user-driven. Information that is strictly contributor focused (e.g. dep upgrades) is moved to CONTRIBUTING.md. The README now links to the production deployment guide in the wiki and describes our general position on using Boulder. The CONTRIBUTING.md guide links to the various docs/ pages and was updated. The docs/acme-divergences page is updated for draft-15. The DESIGN.md document is moved from the root of the repo into docs/. It has been updated to cover ACMEv2 and precertificates/SCT embedding. [0] - #3195

cpu · 2018-09-28T18:31:38Z

CONTRIBUTING.md

-request into the body of the commit message.
-
-If the Travis tests are failing on your branch, you should look at the logs to figure out why. Sometimes they fail spuriously, in which case you can post a comment requesting that a project owner kick the build.
+If the Travis tests are failing on your branch, you should look at the logs to figure out why. Sometimes (though rarely) they fail spuriously, in which case you can post a comment requesting that a project owner kick the build.


Note: I removed the mention of the merger copying the URL of the PR into the body of the commit message. In practice I don't think we ever do that and it doesn't seem worthwhile.

Yep; The default title for squash commits puts the PR number in the summary line, which is all we need.

rolandshoemaker · 2018-09-28T20:24:57Z

CONTRIBUTING.md

@@ -28,16 +26,14 @@ Thanks for helping us build Boulder! This page contains requirements and guideli
 ```
 // TODO(<email-address>): Hoverboard + Time-machine unsupported until upstream patch.
 // TODO(Issue #<num>): Pending hoverboard/time-machine interface.


I think in reality we generally only ever use TODO(#<num>), not sure there are any instances of TODO(Issue #<num>).

Fixed in 7e15e4d

rolandshoemaker · 2018-10-10T17:37:11Z

CONTRIBUTING.md

+git commit
+```
+
+NOTE: If you get "godep: no packages can be updated," there's a good chance you're trying to update a single package that belongs to a repo with other packages. For instance, `godep update golang.org/x/crypto/ocsp` will produce this error, because it's part of the `golang.org/x/crypto` repo, from which we also other packages. Godep requires that all packages from the same repo be on the same version, so it can't update just one. See https://github.com/tools/godep/issues/164 for the issue dedicated to fixing it.


s/from which we also other/from which we also vendor other/

rolandshoemaker · 2018-10-10T17:39:24Z

README.md

+
+This component model lets us separate the function of the CA by security context.  The Web Front End, Validation Authority, and Publisher need access to the Internet, which puts them at greater risk of compromise.  The Registration Authority can live without Internet connectivity, but still needs to talk to the Web Front End and Validation Authority.  The Certificate Authority need only receive instructions from the Registration Authority. All components talk to the SA for storage, so lines indicating SA RPCs are not shown here.
+
+```


OCSP Updater -> Publisher communication is deprecated.

rolandshoemaker · 2018-10-10T17:44:19Z

This generally LGTM, I'm supportive of merging and fixing anything else that pops up later.

jsha · 2018-10-01T18:57:05Z

CONTRIBUTING.md

-request into the body of the commit message.
-
-If the Travis tests are failing on your branch, you should look at the logs to figure out why. Sometimes they fail spuriously, in which case you can post a comment requesting that a project owner kick the build.
+If the Travis tests are failing on your branch, you should look at the logs to figure out why. Sometimes (though rarely) they fail spuriously, in which case you can post a comment requesting that a project owner kick the build.


Yep; The default title for squash commits puts the PR number in the summary line, which is all we need.

jsha · 2018-10-10T17:43:04Z

README.md

+7. OCSP Updater
+8. OCSP Responder
+
+This component model lets us separate the function of the CA by security context.  The Web Front End, Validation Authority, and Publisher need access to the Internet, which puts them at greater risk of compromise.  The Registration Authority can live without Internet connectivity, but still needs to talk to the Web Front End and Validation Authority.  The Certificate Authority need only receive instructions from the Registration Authority. All components talk to the SA for storage, so lines indicating SA RPCs are not shown here.


*"most lines indicating SA RPCs are not shown" -- since the RA->SA line is in fact shown.

jsha · 2018-10-10T17:47:41Z

README.md


    ifconfig docker0 | grep "inet addr:" | cut -d: -f2 | awk '{ print $1}'

-And edit docker-compose.yml to change the FAKE_DNS environment variable to
-match.
+And edit docker-compose.yml to change the FAKE_DNS environment variable to match. This will cause Boulder to use the local system resolver available on your host if one is available.


The second sentence is inaccurate. Instead I would say "This will cause Boulder's stubbed-out DNS resolver (sd-test-srv) to respond to all A queries to the address in FAKE_DNS". This is a common source of confusion for just about everyone, myself included. :-D It might be nice to do this in a more intuitive way in the future.

jsha · 2018-10-10T17:48:53Z

README.md

-Your local Boulder instance uses a fake DNS server that returns 127.0.0.1 for
-any query, so you can use any value for the -d flag. You can also override that
-value by setting the environment variable FAKE_DNS=1.2.3.4
+Your local Boulder instance uses a fake DNS resolver that returns 127.0.0.1 for any query, so you can use any value for the -d flag. If you want to use another DNS resolver you can by setting the environment variable FAKE_DNS=1.2.3.4.


The "If you want to use another..." sentence is also inaccurate for the reason described above.

jsha · 2018-10-10T17:50:14Z

README.md


-```
+Your local Boulder instance uses a fake DNS resolver that returns 127.0.0.1 for any query, allowing you to issue certificates for any domain as if it resolved to your localhost. If you want to use another DNS resolver you can by setting the environment variable FAKE_DNS=1.2.3.4.


Same comment as above: FAKE_DNS doesn't change which DNS resolver you use, just the answers you get.

jsha · 2018-10-10T17:52:22Z

README.md

+a production setting we prioritize support and development work that favors
+Let's Encrypt's mission. This means we may not be able to provide timely support
+or accept pull-requests that deviate significantly from our first line goals. We
+will try our best to engage with folks who have done their homework and need


Instead of "folks who have done their homework," how about "if you've thoroughly evaluated the alternatives and Boulder is definitely the best fit, we're happy to answer questions to the best of our ability."

jsha · 2018-10-10T17:54:38Z

docs/DESIGN.md

@@ -0,0 +1,423 @@
+# Boulder flow diagrams
+
+Boulder is built in a decentralized way in order to enable parts to be deployed


How about "Boulder is built out of multiple components that can be deployed in different security contexts?" I think "decentralized" here might lead to some minor confusion.

cpu · 2018-10-10T19:42:42Z

@rolandshoemaker @jsha Thanks for the feedback. This branch should be ready for another 🔍 now.

Daniel added 2 commits September 28, 2018 14:24

Merge remote-tracking branch 'le/master' into cpu-roland-readme-revamp

d63a070

cpu requested a review from a team as a code owner September 28, 2018 18:29

cpu commented Sep 28, 2018

View reviewed changes

rolandshoemaker reviewed Sep 28, 2018

View reviewed changes

Update TODO syntax

7e15e4d

cpu mentioned this pull request Oct 10, 2018

Update DESIGN.md for ACMEv2 #3850

Closed

rolandshoemaker reviewed Oct 10, 2018

View reviewed changes

jsha requested changes Oct 10, 2018

View reviewed changes

Daniel added 7 commits October 10, 2018 15:35

Fix vendor typo

2ecd3a8

Remove ocsp-updater -> publisher comms

2a2b124

Clarify SA rpc lines

f615ceb

Fix FAKE_DNS references

fb84853

Clarify components vs distributed

9192c58

Merge remote-tracking branch 'le/master' into cpu-roland-readme-revamp

ce05ce9

Clarify prod help

b02b0d5

jsha approved these changes Oct 10, 2018

View reviewed changes

rolandshoemaker approved these changes Oct 10, 2018

View reviewed changes

rolandshoemaker merged commit 8caecd0 into master Oct 10, 2018

cpu deleted the cpu-roland-readme-revamp branch October 11, 2018 13:12

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README/docs refresh #3876

README/docs refresh #3876

cpu commented Sep 28, 2018 •

edited

Loading

cpu Sep 28, 2018

jsha Oct 1, 2018

rolandshoemaker Sep 28, 2018

cpu Sep 28, 2018

rolandshoemaker Oct 10, 2018

rolandshoemaker Oct 10, 2018

rolandshoemaker commented Oct 10, 2018

jsha Oct 1, 2018

jsha Oct 10, 2018

jsha Oct 10, 2018

jsha Oct 10, 2018

jsha Oct 10, 2018

jsha Oct 10, 2018

jsha Oct 10, 2018

cpu commented Oct 10, 2018


		This component model lets us separate the function of the CA by security context. The Web Front End, Validation Authority, and Publisher need access to the Internet, which puts them at greater risk of compromise. The Registration Authority can live without Internet connectivity, but still needs to talk to the Web Front End and Validation Authority. The Certificate Authority need only receive instructions from the Registration Authority. All components talk to the SA for storage, so lines indicating SA RPCs are not shown here.

		```


		```
		Your local Boulder instance uses a fake DNS resolver that returns 127.0.0.1 for any query, allowing you to issue certificates for any domain as if it resolved to your localhost. If you want to use another DNS resolver you can by setting the environment variable FAKE_DNS=1.2.3.4.

		@@ -0,0 +1,423 @@
		# Boulder flow diagrams

		Boulder is built in a decentralized way in order to enable parts to be deployed

README/docs refresh #3876

README/docs refresh #3876

Conversation

cpu commented Sep 28, 2018 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

rolandshoemaker commented Oct 10, 2018

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

cpu commented Oct 10, 2018

cpu commented Sep 28, 2018 •

edited

Loading