From b9674aef2f6942e1ef5782b300ca05fb6d85fb69 Mon Sep 17 00:00:00 2001
From: AJ ONeal <awesome@coolaj86.com>
Date: Mon, 18 Apr 2016 17:01:35 +0000
Subject: [PATCH] clean up old examples

---
 README.md                                     | 219 ++----------------
 examples/README.md                            |  37 +++
 scraps/README.md                              | 202 ++++++++++++++++
 {examples => scraps}/commandline-minimal.js   |   0
 {examples => scraps}/commandline.js           |   0
 {examples => scraps}/config-minimal.js        |   0
 {examples => scraps}/express-minimal.js       |   0
 {examples => scraps}/express.js               |   0
 .../private-key-json-to-account-id.js         |   0
 {examples => scraps}/renewal-example.com.conf |   0
 {examples => scraps}/ursa.js                  |   0
 11 files changed, 260 insertions(+), 198 deletions(-)
 create mode 100644 examples/README.md
 create mode 100644 scraps/README.md
 rename {examples => scraps}/commandline-minimal.js (100%)
 rename {examples => scraps}/commandline.js (100%)
 rename {examples => scraps}/config-minimal.js (100%)
 rename {examples => scraps}/express-minimal.js (100%)
 rename {examples => scraps}/express.js (100%)
 rename {examples => scraps}/private-key-json-to-account-id.js (100%)
 rename {examples => scraps}/renewal-example.com.conf (100%)
 rename {examples => scraps}/ursa.js (100%)

diff --git a/README.md b/README.md
index 56399ae..a584b92 100644
--- a/README.md
+++ b/README.md
@@ -13,10 +13,29 @@ Automatic [Let's Encrypt](https://letsencrypt.org) HTTPS Certificates for node.j
 
 **See Also**
 
-* See the node-letsencrypt [Examples](https://github.com/Daplie/node-letsencrypt/tree/master/examples)
 * [Let's Encrypt in (exactly) 90 seconds with Caddy](https://daplie.com/articles/lets-encrypt-in-literally-90-seconds/)
 * [lego](https://github.com/xenolf/lego): Let's Encrypt for golang
 
+STOP
+====
+
+**These aren't the droids you're looking for.**
+
+This is a low-level library for implementing CLIs,
+system tools, and abstracting storage backends (file vs db, etc).
+This is not the thing to use in your webserver directly.
+
+Are you planning to use one of these?
+
+  * `express`
+  * `hapi`
+  * `connect`
+  * `koa`
+  * raw `https`
+  * raw `spdy`
+
+### Use [letsencrypt-express](https://github.com/Daplie/letsencrypt-express) instead!
+
 Install
 =======
 
@@ -128,203 +147,6 @@ le.register({                                                 // and either rene
 **However**, due to the nature of what this library does, it has a few more "moving parts"
 than what makes sense to show in a minimal snippet.
 
-Examples
-========
-
-The simplest example of setting up a webserver appropriately is probably `letsencrypt-cli` (~120 lines of code):
-
-* [letsencrypt-cli//lib/standalone.js](https://github.com/Daplie/node-letsencrypt-cli/blob/master/lib/standalone.js)
-
-Similary, `letsencrypt-cli`'s usage of `le.register()` is fairly simple (~75 lines of code):
-
-* [letsencrypt-cli/bin/letsencrypt.js](https://github.com/Daplie/node-letsencrypt-cli/blob/master/bin/letsencrypt.js)
-
-### One-Time Registration
-
-Register a 90-day certificate manually, on a whim
-
-**Note**: We've been running a fast development cycle and this example may be out of date.
-The API *shouldn't* have changed much but, we probably need to come back and update it.
-
-#### Snippets
-
-[`commandline-minimal`](https://github.com/Daplie/node-letsencrypt/blob/master/examples/commandline-minimal.js):
-
-**Part 1: the Let's Encrypt client**:
-```javascript
-'use strict';
-
-var LE = require('letsencrypt');
-var config = require('./config-minimal');
-
-// Note: you should make this special dir in your product and leave it empty
-config.le.webrootPath = __dirname + '/../tests/acme-challenge';
-config.le.server = LE.stagingServer;
-
-
-//
-// Manual Registration
-//
-var le = LE.create(config.backend, config.le);
-le.register({
-  agreeTos: true
-, domains: ['example.com']          // CHANGE TO YOUR DOMAIN
-, email: 'user@email.com'           // CHANGE TO YOUR EMAIL
-}, function (err) {
-  if (err) {
-    console.error('[Error]: node-letsencrypt/examples/standalone');
-    console.error(err.stack);
-  } else {
-    console.log('success');
-  }
-
-  plainServer.close();
-  tlsServer.close();
-});
-```
-
-**Part 2: Express Web Server**:
-```javascript
-//
-// Express App
-//
-var app = require('express')();
-app.use('/', le.middleware());  // TODO le.middleware was moved to letsencrypt-express, we need to update the docs here
-
-
-//
-// HTTP & HTTPS servers
-// (required for domain validation)
-//
-var plainServer = require('http').createServer(app).listen(config.plainPort, function () {
-  console.log('Listening http', this.address());
-});
-
-var tlsServer = require('https').createServer({
-  key: config.tlsKey
-, cert: config.tlsCert
-, SNICallback: le.sniCallback
-}, app).listen(config.tlsPort, function () {
-  console.log('Listening http', this.address());
-});
-```
-
-#### Runnable Demo
-
-* [commandline (standalone with "webroot")](https://github.com/Daplie/node-letsencrypt/blob/master/examples/commandline.js)
-
-```bash
-# manual standalone registration via commandline
-# (runs against testing server on tls port 5001)
-node examples/commandline.js example.com,www.example.com user@example.net agree
-```
-
-### Express
-
-Fully Automatic HTTPS with ExpressJS using Free SSL certificates from Let's Encrypt
-
-#### Snippets
-
-* [Minimal ExpressJS Example](https://github.com/Daplie/node-letsencrypt/blob/master/examples/express-minimal.js)
-
-```javascript
-'use strict';
-
-var LE = require('letsencrypt');
-var config = require('./config-minimal');
-
-// Note: you should make this special dir in your product and leave it empty
-config.le.webrootPath = __dirname + '/../tests/acme-challenge';
-config.le.server = LE.stagingServer;
-
-//
-// Automatically Register / Renew Domains
-//
-var le = LE.create(config.backend, config.le, {
-  sniRegisterCallback: function (args, expiredCert, cb) {
-    // Security: check that this is actually a subdomain we allow
-    // (otherwise an attacker can cause you to rate limit against the LE server)
-
-    var hostname = args.domains[0];
-    if (!/\.example\.com$/.test(hostname)) {
-      console.error("bad domain '" + hostname + "', not a subdomain of example.com");
-      cb(nul, null);
-    }
-
-    // agree to the LE TOS for this domain
-    args.agreeTos = true;
-    args.email = 'user@example.com';
-
-    // use the cert even though it's expired
-    if (expiredCert) {
-      cb(null, expiredCert);
-      cb = function () { /*ignore*/ };
-    }
-
-    // register / renew the certificate in the background
-    le.register(args, cb);
-  }
-});
-
-
-//
-// Express App
-//
-var app = require('express')();
-app.use('/', le.middleware());
-
-
-//
-// HTTP & HTTPS servers
-//
-require('http').createServer(app).listen(config.plainPort, function () {
-  console.log('Listening http', this.address());
-});
-
-require('https').createServer({
-  key: config.tlsKey
-, cert: config.tlsCert
-, SNICallback: le.sniCallback
-}, app).listen(config.tlsPort, function () {
-  console.log('Listening http', this.address());
-});
-```
-
-#### Runnable Example
-
-* [Full ExpressJS Example](https://github.com/Daplie/node-letsencrypt/blob/master/examples/express.js)
-
-```bash
-# clear out the certificates
-rm -rf tests/letsencrypt.*
-
-# automatic registration and renewal (certs install as you visit the site for the first time)
-# (runs against testing server on tls port 5001)
-node examples/express.js example.com,www.example.com user@example.net agree
-```
-
-```bash
-# this will take a moment because it won't respond to the tls sni header until it gets the certs
-curl https://example.com/
-```
-
-### non-root
-
-If you want to run this as non-root, you can.
-
-You just have to set node to be allowed to use root ports
-
-```
-# node
-sudo setcap cap_net_bind_service=+ep /usr/local/bin/node
-```
-
-and then make sure to set all of of the following to a directory that your user is permitted to write to
-
-* `webrootPath`
-* `configDir`
-
-
 API
 ===
 
@@ -490,6 +312,7 @@ the python client, but it's not necessary)
 Change History
 ==============
 
+* v1.4.x I can't remember... but it's better!
 * v1.1.0 Added letiny-core, removed node-letsencrypt-python
 * v1.0.2 Works with node-letsencrypt-python
 * v1.0.0 Thar be dragons
diff --git a/examples/README.md b/examples/README.md
new file mode 100644
index 0000000..714536c
--- /dev/null
+++ b/examples/README.md
@@ -0,0 +1,37 @@
+STOP
+====
+
+** These aren't the droids you're looking for.**
+
+You probably don't want to use `node-letsencrypt` directly.
+
+Instead, look here:
+
+Webservers
+----------
+
+For any type of webserver (express, hapi, koa, connect, https, spdy, etc),
+you're going to want to take a look at
+[letsencrypt-express](https://github.com/Daplie/letsencrypt-express).
+
+<https://github.com/Daplie/letsencrypt-express>
+
+CLIs
+----
+
+For any type of CLI (like what you want to use with bash, fish, zsh, cmd.exe, PowerShell, etc),
+you're going to want to take a look at
+[letsencrypt-cli](https://github.com/Daplie/letsencrypt-cli).
+
+<https://github.com/Daplie/letsencrypt-cli>
+
+No, I wanted node-letsencrypt
+=============================
+
+Well, take a look at the API in the main README
+and you can also check out the [scraps](https://github.com/Daplie/node-letsencrypt/tree/master/scraps).
+
+Feel free to create issues for examples that don't work and pull requests if you fix one.
+
+And please, please, do open an issue. We haven't updated the scrap examples
+(hence being moved), but we do have it on the roadmap to bring back some raw API examples.
diff --git a/scraps/README.md b/scraps/README.md
new file mode 100644
index 0000000..3e27fa8
--- /dev/null
+++ b/scraps/README.md
@@ -0,0 +1,202 @@
+Scraps
+======
+
+These are examples that we might come back and update (and would love help updating),
+but they are more likely to cause confusion than success for the casual googled-it-and-got-here-er.
+
+Probably Outdated Examples
+========
+
+The simplest example of setting up a webserver appropriately is probably `letsencrypt-cli` (~120 lines of code):
+
+* [letsencrypt-cli//lib/standalone.js](https://github.com/Daplie/node-letsencrypt-cli/blob/master/lib/standalone.js)
+
+Similary, `letsencrypt-cli`'s usage of `le.register()` is fairly simple (~75 lines of code):
+
+* [letsencrypt-cli/bin/letsencrypt.js](https://github.com/Daplie/node-letsencrypt-cli/blob/master/bin/letsencrypt.js)
+
+### One-Time Registration
+
+Register a 90-day certificate manually, on a whim
+
+**Note**: We've been running a fast development cycle and this example may be out of date.
+The API *shouldn't* have changed much but, we probably need to come back and update it.
+
+#### Snippets
+
+[`commandline-minimal`](https://github.com/Daplie/node-letsencrypt/blob/master/examples/commandline-minimal.js):
+
+**Part 1: the Let's Encrypt client**:
+```javascript
+'use strict';
+
+var LE = require('letsencrypt');
+var config = require('./config-minimal');
+
+// Note: you should make this special dir in your product and leave it empty
+config.le.webrootPath = __dirname + '/../tests/acme-challenge';
+config.le.server = LE.stagingServer;
+
+
+//
+// Manual Registration
+//
+var le = LE.create(config.backend, config.le);
+le.register({
+  agreeTos: true
+, domains: ['example.com']          // CHANGE TO YOUR DOMAIN
+, email: 'user@email.com'           // CHANGE TO YOUR EMAIL
+}, function (err) {
+  if (err) {
+    console.error('[Error]: node-letsencrypt/examples/standalone');
+    console.error(err.stack);
+  } else {
+    console.log('success');
+  }
+
+  plainServer.close();
+  tlsServer.close();
+});
+```
+
+**Part 2: Express Web Server**:
+```javascript
+//
+// Express App
+//
+var app = require('express')();
+app.use('/', le.middleware());  // TODO le.middleware was moved to letsencrypt-express, we need to update the docs here
+
+
+//
+// HTTP & HTTPS servers
+// (required for domain validation)
+//
+var plainServer = require('http').createServer(app).listen(config.plainPort, function () {
+  console.log('Listening http', this.address());
+});
+
+var tlsServer = require('https').createServer({
+  key: config.tlsKey
+, cert: config.tlsCert
+, SNICallback: le.sniCallback
+}, app).listen(config.tlsPort, function () {
+  console.log('Listening http', this.address());
+});
+```
+
+#### Runnable Demo
+
+* [commandline (standalone with "webroot")](https://github.com/Daplie/node-letsencrypt/blob/master/examples/commandline.js)
+
+```bash
+# manual standalone registration via commandline
+# (runs against testing server on tls port 5001)
+node examples/commandline.js example.com,www.example.com user@example.net agree
+```
+
+### Express
+
+Fully Automatic HTTPS with ExpressJS using Free SSL certificates from Let's Encrypt
+
+#### Snippets
+
+* [Minimal ExpressJS Example](https://github.com/Daplie/node-letsencrypt/blob/master/examples/express-minimal.js)
+
+```javascript
+'use strict';
+
+var LE = require('letsencrypt');
+var config = require('./config-minimal');
+
+// Note: you should make this special dir in your product and leave it empty
+config.le.webrootPath = __dirname + '/../tests/acme-challenge';
+config.le.server = LE.stagingServer;
+
+//
+// Automatically Register / Renew Domains
+//
+var le = LE.create(config.backend, config.le, {
+  sniRegisterCallback: function (args, expiredCert, cb) {
+    // Security: check that this is actually a subdomain we allow
+    // (otherwise an attacker can cause you to rate limit against the LE server)
+
+    var hostname = args.domains[0];
+    if (!/\.example\.com$/.test(hostname)) {
+      console.error("bad domain '" + hostname + "', not a subdomain of example.com");
+      cb(nul, null);
+    }
+
+    // agree to the LE TOS for this domain
+    args.agreeTos = true;
+    args.email = 'user@example.com';
+
+    // use the cert even though it's expired
+    if (expiredCert) {
+      cb(null, expiredCert);
+      cb = function () { /*ignore*/ };
+    }
+
+    // register / renew the certificate in the background
+    le.register(args, cb);
+  }
+});
+
+
+//
+// Express App
+//
+var app = require('express')();
+app.use('/', le.middleware());
+
+
+//
+// HTTP & HTTPS servers
+//
+require('http').createServer(app).listen(config.plainPort, function () {
+  console.log('Listening http', this.address());
+});
+
+require('https').createServer({
+  key: config.tlsKey
+, cert: config.tlsCert
+, SNICallback: le.sniCallback
+}, app).listen(config.tlsPort, function () {
+  console.log('Listening http', this.address());
+});
+```
+
+#### Runnable Example
+
+* [Full ExpressJS Example](https://github.com/Daplie/node-letsencrypt/blob/master/examples/express.js)
+
+```bash
+# clear out the certificates
+rm -rf tests/letsencrypt.*
+
+# automatic registration and renewal (certs install as you visit the site for the first time)
+# (runs against testing server on tls port 5001)
+node examples/express.js example.com,www.example.com user@example.net agree
+```
+
+```bash
+# this will take a moment because it won't respond to the tls sni header until it gets the certs
+curl https://example.com/
+```
+
+### non-root
+
+If you want to run this as non-root, you can.
+
+You just have to set node to be allowed to use root ports
+
+```
+# node
+sudo setcap cap_net_bind_service=+ep /usr/local/bin/node
+```
+
+and then make sure to set all of of the following to a directory that your user is permitted to write to
+
+* `webrootPath`
+* `configDir`
+
diff --git a/examples/commandline-minimal.js b/scraps/commandline-minimal.js
similarity index 100%
rename from examples/commandline-minimal.js
rename to scraps/commandline-minimal.js
diff --git a/examples/commandline.js b/scraps/commandline.js
similarity index 100%
rename from examples/commandline.js
rename to scraps/commandline.js
diff --git a/examples/config-minimal.js b/scraps/config-minimal.js
similarity index 100%
rename from examples/config-minimal.js
rename to scraps/config-minimal.js
diff --git a/examples/express-minimal.js b/scraps/express-minimal.js
similarity index 100%
rename from examples/express-minimal.js
rename to scraps/express-minimal.js
diff --git a/examples/express.js b/scraps/express.js
similarity index 100%
rename from examples/express.js
rename to scraps/express.js
diff --git a/examples/private-key-json-to-account-id.js b/scraps/private-key-json-to-account-id.js
similarity index 100%
rename from examples/private-key-json-to-account-id.js
rename to scraps/private-key-json-to-account-id.js
diff --git a/examples/renewal-example.com.conf b/scraps/renewal-example.com.conf
similarity index 100%
rename from examples/renewal-example.com.conf
rename to scraps/renewal-example.com.conf
diff --git a/examples/ursa.js b/scraps/ursa.js
similarity index 100%
rename from examples/ursa.js
rename to scraps/ursa.js