From 586a5fa154f03e4d0cb556d8286d7e8653aefd57 Mon Sep 17 00:00:00 2001 From: ThakurKarthik Date: Fri, 16 Oct 2020 01:05:09 +0530 Subject: [PATCH 1/5] fix: add support for key,cert in https --- packages/docusaurus/src/commands/start.ts | 4 +- packages/docusaurus/src/webpack/utils.ts | 62 +++++++++++++++++++++++ 2 files changed, 64 insertions(+), 2 deletions(-) diff --git a/packages/docusaurus/src/commands/start.ts b/packages/docusaurus/src/commands/start.ts index 0a65982dbb59..55e9dbe54aee 100644 --- a/packages/docusaurus/src/commands/start.ts +++ b/packages/docusaurus/src/commands/start.ts @@ -23,7 +23,7 @@ import {load} from '../server'; import {StartCLIOptions} from '@docusaurus/types'; import {CONFIG_FILE_NAME, STATIC_DIR_NAME, DEFAULT_PORT} from '../constants'; import createClientConfig from '../webpack/client'; -import {applyConfigureWebpack} from '../webpack/utils'; +import {applyConfigureWebpack, getHttpsConfig} from '../webpack/utils'; import choosePort from '../choosePort'; function getHost(reqHost: string | undefined): string { @@ -142,7 +142,7 @@ export default async function start( // `webpackHotDevClient`. injectClient: false, quiet: true, - https: protocol === 'https', + https: getHttpsConfig(), headers: { 'access-control-allow-origin': '*', }, diff --git a/packages/docusaurus/src/webpack/utils.ts b/packages/docusaurus/src/webpack/utils.ts index a2988e6b3988..45ddb1dda323 100644 --- a/packages/docusaurus/src/webpack/utils.ts +++ b/packages/docusaurus/src/webpack/utils.ts @@ -9,6 +9,10 @@ import MiniCssExtractPlugin from 'mini-css-extract-plugin'; import env from 'std-env'; import merge from 'webpack-merge'; import webpack, {Configuration, Loader, RuleSetRule, Stats} from 'webpack'; +import fs from 'fs'; +import path from 'path'; +import crypto from 'crypto'; +import chalk from 'chalk'; import {TransformOptions} from '@babel/core'; import {ConfigureWebpackFn} from '@docusaurus/types'; import {version as cacheLoaderVersion} from 'cache-loader/package.json'; @@ -274,3 +278,61 @@ export function getFileLoaderUtils() { return {loaders, rules}; } + +// Ensure the certificate and key provided are valid and if not +// throw an easy to debug error +function validateKeyAndCerts({cert, key, keyFile, crtFile}) { + let encrypted; + try { + // publicEncrypt will throw an error with an invalid cert + encrypted = crypto.publicEncrypt(cert, Buffer.from('test')); + } catch (err) { + throw new Error( + `The certificate "${chalk.yellow(crtFile)}" is invalid.\n${err.message}`, + ); + } + + try { + // privateDecrypt will throw an error with an invalid key + crypto.privateDecrypt(key, encrypted); + } catch (err) { + throw new Error( + `The certificate key "${chalk.yellow(keyFile)}" is invalid.\n${ + err.message + }`, + ); + } +} + +// Read file and throw an error if it doesn't exist +function readEnvFile(file, type) { + if (!fs.existsSync(file)) { + throw new Error( + `You specified ${chalk.cyan( + type, + )} in your env, but the file "${chalk.yellow(file)}" can't be found.`, + ); + } + return fs.readFileSync(file); +} + +const appDirectory = fs.realpathSync(process.cwd()); +// Get the https config +// Return cert files if provided in env, otherwise just true or false +export function getHttpsConfig(): boolean | {cert: Buffer; key: Buffer} { + const {SSL_CRT_FILE, SSL_KEY_FILE, HTTPS} = process.env; + const isHttps = HTTPS === 'true'; + + if (isHttps && SSL_CRT_FILE && SSL_KEY_FILE) { + const crtFile = path.resolve(appDirectory, SSL_CRT_FILE); + const keyFile = path.resolve(appDirectory, SSL_KEY_FILE); + const config = { + cert: readEnvFile(crtFile, 'SSL_CRT_FILE'), + key: readEnvFile(keyFile, 'SSL_KEY_FILE'), + }; + + validateKeyAndCerts({...config, keyFile, crtFile}); + return config; + } + return isHttps; +} From 988076fab8f435dd9562611878c4a4472a04ee41 Mon Sep 17 00:00:00 2001 From: ThakurKarthik Date: Fri, 23 Oct 2020 23:14:33 +0530 Subject: [PATCH 2/5] docs: add steps for using https with docusaurus --- website/docs/cli.md | 30 ++++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/website/docs/cli.md b/website/docs/cli.md index 857722146172..624db09dc2d1 100644 --- a/website/docs/cli.md +++ b/website/docs/cli.md @@ -57,6 +57,36 @@ Please note that some functionality (for example, anchor links) will not work in ::: +#### `Running in https` + +1.Get the required certificate, key files for https. For demo purposes let's use [mkcert](https://github.com/FiloSottile/mkcert). + +2.In your root of docusaurus project place the above required files. + +For demo let's run + +```shell + mkcert localhost 127.0.0.1 ::1 +``` + +this will emit files required for the https mode. + +3.Finally start the server(`docusaurus start`) with the file path's as env variables + +```shell + HTTPS=true SSL_CRT_FILE= SSL_KEY_FILE= yarn start +``` + +For demo + +```shell + HTTPS=true SSL_CRT_FILE=localhost+2.pem SSL_KEY_FILE=localhost+2-key.pem yarn start +``` + +will start the docusaurus in https mode. Please note that `localhost+2.pem`, `localhost+2-key.pem` files are generated by mkcert for the demo. + +4.Now you must be running the docusaurus in https mode. + ### `docusaurus build` Compiles your site for production. From b6500a6cef238874434c92afcd142cb1ef5ed5c6 Mon Sep 17 00:00:00 2001 From: slorber Date: Mon, 26 Oct 2020 16:48:45 +0100 Subject: [PATCH 3/5] improve https certs docs --- website/docs/cli.md | 28 ++++++---------------------- 1 file changed, 6 insertions(+), 22 deletions(-) diff --git a/website/docs/cli.md b/website/docs/cli.md index c8f814e4a548..c454452b6bb4 100644 --- a/website/docs/cli.md +++ b/website/docs/cli.md @@ -57,35 +57,19 @@ Please note that some functionality (for example, anchor links) will not work in ::: -#### `Running in https` +#### `Enabling HTTPS` -1.Get the required certificate, key files for https. For demo purposes let's use [mkcert](https://github.com/FiloSottile/mkcert). +There are multiple ways to obtain a certificate. We will use [mkcert](https://github.com/FiloSottile/mkcert) as an example. -2.In your root of docusaurus project place the above required files. +1. Run `mkcert localhost` to generate `localhost.pem` + `localhost-key.pem` -For demo let's run +2. Start the app with Docusaurus HTTPS env variables: ```shell - mkcert localhost 127.0.0.1 ::1 +HTTPS=true SSL_CRT_FILE=localhost.pem SSL_KEY_FILE=localhost-key.pem yarn start ``` -this will emit files required for the https mode. - -3.Finally start the server(`docusaurus start`) with the file path's as env variables - -```shell - HTTPS=true SSL_CRT_FILE= SSL_KEY_FILE= yarn start -``` - -For demo - -```shell - HTTPS=true SSL_CRT_FILE=localhost+2.pem SSL_KEY_FILE=localhost+2-key.pem yarn start -``` - -will start the docusaurus in https mode. Please note that `localhost+2.pem`, `localhost+2-key.pem` files are generated by mkcert for the demo. - -4.Now you must be running the docusaurus in https mode. +3. Open `https://localhost:3000/` ### `docusaurus build` From bdf6fb1cf2dba3b18a647845560daf8b6ec6fd1b Mon Sep 17 00:00:00 2001 From: slorber Date: Mon, 26 Oct 2020 16:49:21 +0100 Subject: [PATCH 4/5] typo --- website/docs/cli.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/cli.md b/website/docs/cli.md index c454452b6bb4..f6ac13e45c0c 100644 --- a/website/docs/cli.md +++ b/website/docs/cli.md @@ -57,7 +57,7 @@ Please note that some functionality (for example, anchor links) will not work in ::: -#### `Enabling HTTPS` +#### Enabling HTTPS` There are multiple ways to obtain a certificate. We will use [mkcert](https://github.com/FiloSottile/mkcert) as an example. From b7d88ede074f02022a5fd6655c9b611ec108e10a Mon Sep 17 00:00:00 2001 From: slorber Date: Mon, 26 Oct 2020 17:08:18 +0100 Subject: [PATCH 5/5] local https: add mkcert -install step --- website/docs/cli.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/website/docs/cli.md b/website/docs/cli.md index f6ac13e45c0c..f649f7309a2c 100644 --- a/website/docs/cli.md +++ b/website/docs/cli.md @@ -63,13 +63,15 @@ There are multiple ways to obtain a certificate. We will use [mkcert](https://gi 1. Run `mkcert localhost` to generate `localhost.pem` + `localhost-key.pem` -2. Start the app with Docusaurus HTTPS env variables: +2. Run `mkcert -install` to install the cert in your trust store, and restart your browser + +3. Start the app with Docusaurus HTTPS env variables: ```shell HTTPS=true SSL_CRT_FILE=localhost.pem SSL_KEY_FILE=localhost-key.pem yarn start ``` -3. Open `https://localhost:3000/` +4. Open `https://localhost:3000/` ### `docusaurus build`