Add cli.sh (#46)

Author: eugene-khyst

README.md

@@ -36,7 +36,8 @@ Nginx and Let’s Encrypt with Docker Compose in less than 3 minutes.
 
 This example automatically obtains and renews [Let's Encrypt](https://letsencrypt.org/) free SSL/TLS certificates and sets up HTTPS in Nginx for multiple domain names using Docker Compose.
 
-You can run Nginx with IPv4, IPv6, HTTP/1.1, and HTTP/2 support and set up HTTPS with Let's Encrypt TLS certificates for your domain names and get an A+ rating in [SSL Labs SSL Server Test](https://www.ssllabs.com/ssltest/) using Docker Compose and _letsencrypt-docker-compose_ interactive CLI tool.
+You can run Nginx and set up HTTPS (`https://`) and WebSocket Secure (`wss://`) with Let's Encrypt TLS certificates for your domain names and get an A+ rating in [SSL Labs SSL Server Test](https://www.ssllabs.com/ssltest/) using Docker Compose and _letsencrypt-docker-compose_ interactive CLI tool.
+Nginx is configured to support IPv4, IPv6, HTTP/1.1, HTTP/2, and optionally, WebSocket.
 
 Let's Encrypt is a certificate authority that provides free X.509 certificates for TLS encryption.
 The certificates are valid for 90 days and can be renewed. Both initial creation and renewal can be automated using [Certbot](https://certbot.eff.org/).
@@ -116,6 +117,8 @@ cp -R ./examples/html/ ./html/a.evgeniy-khyst.com
 
 The [`docker-compose.yml`](docker-compose.yml) contains the `example-backend` service.
 It's a simple Node.js web app listening on port 8080.
+It has `/hello?name={name}` REST endpoint and WebSocket echo server sending back the request sent by the client.
+
 Replace it with your backend service or remove it.
 
 ```yaml
@@ -155,6 +158,12 @@ networks:
 
 Run the CLI tool and follow the instructions to perform an initial setup.
 
+```bash
+./cli.sh config
+```
+
+or
+
 ```bash
 docker compose run --rm cli
 ```
@@ -166,14 +175,26 @@ We will switch to a Let's Encrypt production environment after verifying that HT
 
 ### <a id="2-5"></a>Step 4 - Start the services
 
-On the first run, build the services.
+If you've made any changes to the Docker images, rebuild the services.
+
+```bash
+./cli.sh build
+```
+
+or
 
 ```bash
 docker compose build
 ```
 
 Start the services.
 
+```bash
+./cli.sh up
+```
+
+or
+
 ```bash
 docker compose up -d
 ```
@@ -193,7 +214,7 @@ Reloading Nginx configuration
 
 ### <a id="2-6"></a>Step 5 - Verify that HTTPS works with the test certificates
 
-For each domain, check `https://${domain}` and `https://www.${domain}` if you configured the `www` subdomain.
+For each domain, check `https://${domain}` and `https://www.${domain}` if you've configured the `www` subdomain.
 Certificates issued by `(STAGING) Let's Encrypt` are considered not secure by browsers and cURL.
 
 ```bash
@@ -203,10 +224,22 @@ curl --insecure https://b.evgeniy-khyst.com/hello?name=Eugene
 curl --insecure https://www.b.evgeniy-khyst.com/hello?name=Eugene
 ```
 
+If you've set up WebSocket, check it using the [wscat](https://github.com/websockets/wscat) tool.
+
+```bash
+wscat --no-check --connect wss://b.evgeniy-khyst.com/echo
+```
+
 ### <a id="2-7"></a>Step 6 - Switch to a Let's Encrypt production environment
 
 Run the CLI tool, choose `Switch to a Let's Encrypt production environment` and follow the instructions.
 
+```bash
+./cli.sh config
+```
+
+or
+
 ```bash
 docker compose run --rm cli
 ```
@@ -215,7 +248,7 @@ docker compose run --rm cli
 
 ### <a id="2-8"></a>Step 7 - Verify that HTTPS works with the production certificates
 
-For each domain, check `https://${domain}` and `https://www.${domain}` if you configured the `www` subdomain.
+For each domain, check `https://${domain}` and `https://www.${domain}` if you've configured the `www` subdomain.
 Certificates issued by `Let's Encrypt` are considered secure by browsers and cURL.
 
 ```bash
@@ -225,6 +258,12 @@ curl https://b.evgeniy-khyst.com/hello?name=Eugene
 curl https://www.b.evgeniy-khyst.com/hello?name=Eugene
 ```
 
+If you've set up WebSocket, check it using the [wscat](https://github.com/websockets/wscat) tool.
+
+```bash
+wscat --connect wss://b.evgeniy-khyst.com/echo
+```
+
 Optionally check your domains with [SSL Labs SSL Server Test](https://www.ssllabs.com/ssltest/) and review the SSL Reports.
 
 The `cron` service will automatically renew the Let's Encrypt production certificates when the time comes.
@@ -254,20 +293,32 @@ Repeat the actions described in [the subsection of the same name in the "Initial
 
 Run the CLI tool, choose `Add new domains` and follow the instructions.
 
+```bash
+./cli.sh config
+```
+
+or
+
 ```bash
 docker compose run --rm cli
 ```
 
 ### <a id="3-4"></a>Step 4 - Verify that HTTPS works
 
-For each new domain, check `https://${domain}` and `https://www.${domain}` if you configured the `www` subdomain.
+For each new domain, check `https://${domain}` and `https://www.${domain}` if you've configured the `www` subdomain.
 
 [Back to top](#0)
 
 ## <a id="4"></a>Removing existing domains without downtime
 
 Run the CLI tool, choose `Remove existing domains` and follow the instructions.
 
+```bash
+./cli.sh config
+```
+
+or
+
 ```bash
 docker compose run --rm cli
 ```
@@ -284,6 +335,12 @@ This operation is not appropriate to run daily because each certificate will be
 
 Run the CLI tool, choose `Manually renew all Let's Encrypt certificates (force renewal)` and follow the instructions.
 
+```bash
+./cli.sh config
+```
+
+or
+
 ```bash
 docker compose run --rm cli
 ```
@@ -300,13 +357,23 @@ It is possible in dry run mode.
 
 ### <a id="6-1"></a>Step 1 - Perform an initial setup using the CLI tool
 
+```bash
+./cli.sh config
+```
+
+or
+
 ```bash
 docker compose run --rm cli
 ```
 
 ### <a id="6-2"></a>Step 2 - Start the services in dry run mode
 
-Enable dry run mode by setting the environment variable `DRY_RUN=true`.
+```bash
+./cli.sh up --dry-run
+```
+
+Alternatively, you can enable dry run mode using the environment variable `DRY_RUN=true`.
 
 ```bash
 DRY_RUN=true docker compose up -d
@@ -332,9 +399,16 @@ upstream backend {
 ```
 
 After editing the Nginx configuration, do a hot reload of the Nginx configuration.
+Run the CLI tool and choose `Reload Nginx configuration without downtime`.
+
+```bash
+./cli.sh config
+```
+
+or
 
 ```bash
-docker compose exec --no-TTY nginx nginx -s reload
+docker compose run --rm cli
 ```
 
 Manual edits of the `nginx-conf/nginx.conf` and `nginx-conf/conf.d/${domain}.conf` are lost after running the CLI tool
@@ -346,6 +420,14 @@ To make Nginx configuration changes persistent, also edit the Handlebars templat
 - [`templates/nginx.conf.hbs`](templates/nginx.conf.hbs),
 - [`templates/servers.conf.hbs`](templates/servers.conf.hbs).
 
+To add domain-specific configuration to a template use the [`ifEquals` Handlebars helper](cli/src/handlebars-helpers.js).
+
+```hbs
+{{#ifEquals domain "a.evgeniy-khyst.com"}}
+  # Configuration for a specific domain
+{{/ifEquals}}
+```
+
 [Back to top](#0)
 
 ## <a id="8"></a>Running Docker containers as a non-root user
@@ -377,6 +459,18 @@ Run the CLI tool specifying the current user and `docker` group to make it creat
 CURRENT_USER="$(id -u):$(id -g)" DOCKER_GROUP="$(getent group docker | cut -d: -f3)" docker compose run --rm cli
 ```
 
+The convenience script `cli.sh` runs the CLI tool as the current user by default.
+
+```bash
+./cli.sh config
+```
+
+You can run the CLI tool as UID/GID 0 instead of the current user with the option `--no-current-user`.
+
+```bash
+./cli.sh config --no-current-user
+```
+
 [Back to top](#0)
 
 ## <a id="9"></a>SSL configuration for A+ rating

cli.sh

@@ -0,0 +1,77 @@
+#!/bin/bash
+
+usage() {
+      cat << EOF
+Usage: $(basename $0) COMMAND
+
+  config  [OPTIONS]          Run the CLI tool
+          --no-current-user  Run as root (Docker default) instead of the current user
+  
+  up      [OPTIONS]          Build, (re)create, and start all services in the background
+          --dry-run          Disable Certbot to run all services locally
+  
+  build   [OPTIONS]          Build or rebuild all Docker images
+          --no-cache         Do not use cache when building the images
+EOF
+    exit 1
+}
+
+case $1 in
+  config)
+    CMD=(docker compose run --rm cli)
+    export CURRENT_USER="$(id -u):$(id -g)"
+    export DOCKER_GROUP="$(getent group docker | cut -d: -f3)"
+    shift
+    while [[ $# -gt 0 ]]; do
+      case $1 in
+        --no-current-user)
+          unset CURRENT_USER
+          unset DOCKER_GROUP
+          shift
+          ;;
+        *)
+          echo "Unknown option $1"
+          usage
+          ;;
+      esac
+    done
+    ;;
+  up)
+    CMD=(docker compose up -d)
+    shift
+    while [[ $# -gt 0 ]]; do
+      case $1 in
+        --dry-run)
+          export DRY_RUN=true
+          shift
+          ;;
+        *)
+          echo "Unknown option $1"
+          usage
+          ;;
+      esac
+    done
+    ;;
+  build)
+    CMD=(docker compose --profile config build)
+    shift
+    while [[ $# -gt 0 ]]; do
+      case $1 in
+        --no-cache)
+          CMD+=(--no-cache)
+          shift
+          ;;
+        *)
+          echo "Unknown option $1"
+          usage
+          ;;
+      esac
+    done
+    ;;
+  *)
+    echo "Unknown command $1"
+    usage
+    ;;
+esac
+
+"${CMD[@]}"

cli/src/cli.js

@@ -107,24 +107,26 @@ const askDomain = async (config, domainName) => {
       {
         type: 'confirm',
         name: 'websockets',
-        message:
-          'Do you want to proxy websocket connections as well?',
-        default: true
+        message: 'Enable WebSocket proxying?',
+        default: domainConfig.websockets ?? false,
       },
     ];
 
-    const { upstream, dockerDns, websockets } = await inquirer.prompt(
+    const { dockerDns, upstream, websockets } = await inquirer.prompt(
       reverseProxyQuestions
     );
 
-    Object.assign(domainConfig, {
-      upstream,
-      ...(dockerDns ? { dnsResolver: dockerDnsResolver } : {}),
-      websockets,
-    });
+    Object.assign(
+      domainConfig,
+      {
+        upstream,
+        websockets,
+      },
+      dockerDns ? { dnsResolver: dockerDnsResolver } : {}
+    );
   } else {
-    delete domainConfig.upstream;
     delete domainConfig.dnsResolver;
+    delete domainConfig.upstream;
     delete domainConfig.websockets;
   }
 
@@ -192,7 +194,7 @@ const askNginxConfig = async (config) => {
   Object.assign(config, answers);
 };
 
-const askConfim = async () => {
+const askConfirm = async () => {
   const questions = [
     {
       type: 'confirm',
@@ -214,7 +216,7 @@ const writeConfigFiles = async (config) => {
 const initConfig = async (config) => {
   await askDomain(config);
   await askNginxConfig(config);
-  if (await askConfim()) {
+  if (await askConfirm()) {
     await writeConfigFiles(config);
   }
 };
@@ -228,7 +230,7 @@ const obtainProductionCertificates = async (config) => {
 
   domainConfig.testCert = false;
 
-  if (await askConfim()) {
+  if (await askConfirm()) {
     await writeConfigFiles(config);
     await execDeleteCertbotCertificate(domainName);
     await execConfigNginx(); // Use dummy certificate
@@ -239,7 +241,7 @@ const obtainProductionCertificates = async (config) => {
 
 const addDomains = async (config) => {
   await askDomain(config);
-  if (await askConfim()) {
+  if (await askConfirm()) {
     await writeConfigFiles(config);
     await execConfigNginx(); // Use dummy certificate
     await execCertbotCertonly(); // Obtain Let's Encrypt certificate
@@ -255,7 +257,7 @@ const removeDomains = async (config) => {
 
   config.domains.splice(index, 1);
 
-  if (await askConfim()) {
+  if (await askConfirm()) {
     await writeConfigFiles(config);
     await deleteNginxConfigFile(domainName);
     await execNginxReload();
@@ -264,12 +266,18 @@ const removeDomains = async (config) => {
 };
 
 const forceRenewCertificates = async () => {
-  if (await askConfim()) {
+  if (await askConfirm()) {
     await execForceRenewCertbotCertificate();
     await execNginxReload();
   }
 };
 
+const reloadNginxConfiguration = async () => {
+  if (await askConfirm()) {
+    await execNginxReload();
+  }
+};
+
 const askConfig = async () => {
   const config = await readConfig();
 
@@ -312,6 +320,10 @@ const askConfig = async () => {
             name: "Manually renew all Let's Encrypt certificates (force renewal)",
             value: 'forceRenewCertificates',
           },
+          {
+            name: 'Reload Nginx configuration without downtime',
+            value: 'reloadNginxConfiguration',
+          },
         ],
       },
     ];
@@ -323,6 +335,7 @@ const askConfig = async () => {
       addDomains,
       removeDomains,
       forceRenewCertificates,
+      reloadNginxConfiguration,
     };
 
     await commands[command](config);

cli/src/config-processor.js

@@ -1,5 +1,8 @@
 import * as fs from 'fs/promises';
 import Handlebars from 'handlebars';
+import registerHelpers from './handlebars-helpers.js';
+
+registerHelpers(Handlebars);
 
 const configPath = './config.json';
 const templatesDir = './templates';

cli/src/handlebars-helpers.js

@@ -0,0 +1,5 @@
+export default (Handlebars) => {
+  Handlebars.registerHelper('ifEquals', function (arg1, arg2, options) {
+    return arg1 === arg2 ? options.fn(this) : options.inverse(this);
+  });
+};

examples/nodejs-backend/package-lock.json

@@ -8,6 +8,7 @@
   },
   "license": "Apache-2.0",
   "dependencies": {
-    "express": "^4.18.1"
+    "express": "^4.18.1",
+    "express-ws": "^5.0.2"
   }
 }

examples/nodejs-backend/package.json

@@ -1,9 +1,10 @@
 const express = require("express");
+const app = express();
+const expressWs = require("express-ws")(app);
 
 const host = "0.0.0.0";
 const port = 8080;
 
-const app = express();
 app.get("/", (req, res) => {
   res.send("Hello, world!");
 });
@@ -12,5 +13,12 @@ app.get("/hello", (req, res) => {
   res.send(`Hello, ${req.query.name || "world"}!`);
 });
 
+app.ws("/echo", function (ws, req) {
+  ws.on("message", function (msg) {
+    console.log("Received message", msg);
+    ws.send(msg);
+  });
+});
+
 app.listen(port, host);
 console.log(`Running on http://${host}:${port}`);

examples/nodejs-backend/server.js

@@ -31,5 +31,10 @@ http {
     include /etc/nginx/conf.d/includes/gzip.conf;
     {{/if}}
 
+    map $http_upgrade $connection_upgrade {
+        default upgrade;
+        '' close;
+    }
+
     include /etc/nginx/conf.d/*.conf;
-}
+}

scripts/rebuild-all-images.sh

@@ -35,18 +35,20 @@ location / {
     proxy_set_header X-Real-IP $remote_addr;
     proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
     proxy_set_header X-Forwarded-Proto $scheme;
+
     {{#if dnsResolver}}
     # Let Nginx start if upstream host is unreachable
     set $upstream {{upstream}};
     proxy_pass http://$upstream;
     {{else}}
     proxy_pass http://{{upstream}};
     {{/if}}
+
     {{#if websockets}}
     proxy_http_version 1.1;
     proxy_set_header Upgrade $http_upgrade;
-    proxy_set_header Connection "upgrade";
-    proxy_read_timeout 86400;
+    proxy_set_header Connection $connection_upgrade;
+    proxy_read_timeout 3600;
     {{/if}}
 }
 {{/inline}}