Skip to content

Commit 4118f74

Browse files
mfranzkeJosefBredereck
mfranzke
and
JosefBredereck
authored
feat: added https description to the docs (#1355)
* feat(https): added docs on how to setup https for localhost dev server * refactor(https): added differentiation on the terminals output regarding the correct, protocol related URL * chore: simplification * chore: using markdown instead of HTML * Update packages/docs/src/docs/running-patternlab.md Co-authored-by: Josef Bredreck <slime.games@outlook.de> * Update packages/docs/src/docs/running-patternlab.md Co-authored-by: Josef Bredreck <slime.games@outlook.de> * Update packages/docs/src/docs/running-patternlab.md Co-authored-by: Josef Bredreck <slime.games@outlook.de> * Update packages/docs/src/docs/running-patternlab.md Co-authored-by: Josef Bredreck <slime.games@outlook.de> * Update packages/docs/src/docs/running-patternlab.md Co-authored-by: Josef Bredreck <slime.games@outlook.de> * Update packages/docs/src/docs/running-patternlab.md Co-authored-by: Josef Bredreck <slime.games@outlook.de> * Update packages/docs/src/docs/running-patternlab.md Co-authored-by: Josef Bredreck <slime.games@outlook.de> * Update packages/docs/src/docs/running-patternlab.md Co-authored-by: Josef Bredreck <slime.games@outlook.de> * Update packages/docs/src/docs/running-patternlab.md Co-authored-by: Josef Bredreck <slime.games@outlook.de> * Update packages/docs/src/docs/running-patternlab.md Co-authored-by: Josef Bredreck <slime.games@outlook.de> Co-authored-by: Josef Bredreck <slime.games@outlook.de>
1 parent 64fd8f4 commit 4118f74

File tree

3 files changed

+68
-2
lines changed

3 files changed

+68
-2
lines changed

‎packages/core/src/lib/server.js‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -87,7 +87,9 @@ const server = (patternlab) => {
8787
setTimeout(() => {
8888
try {
8989
liveServer.start(liveServerConfig);
90-
resolveMsg = `Pattern Lab is being served from http://127.0.0.1:${liveServerConfig.port}`;
90+
resolveMsg = `Pattern Lab is being served from ${
91+
liveServerConfig.https ? 'https' : 'http'
92+
}://127.0.0.1:${liveServerConfig.port}`;
9193
logger.info(resolveMsg);
9294
} catch (e) {
9395
const err = `Pattern Lab serve failed to start: ${e}`;

‎packages/docs/src/docs/advanced-config-options.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -236,7 +236,8 @@ Sets [live-server options](https://github.com/pattern-lab/live-server#usage-from
236236
| wait | 100 | Waits for all changes, before reloading. Defaults to 0 sec. |
237237
| mount | [['/components', './node_modules']] | Mount a directory to a route. |
238238
| logLevel | 2 | 0 = errors only, 1 = some, 2 = lots |
239-
| middleware | [function(req, res, next) { next(); }] | Takes an array of Connect-compatible middleware that are injected into the server middleware stack |
239+
| middleware | [function(req, res, next) { next(); }] | Takes an array of Connect-compatible middleware that are injected into the server middleware stack |
240+
| https | 'ssl/ssl.js' | adding the path to a configuration module for HTTPS dev servers, see detailed explanation on the[`running patternlab` page](/docs/running-pattern-lab/#heading-running-localhost-via-https) |
240241

241242
**default**:
242243

‎packages/docs/src/docs/running-patternlab.md‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,3 +25,66 @@ Relevant information regarding and step and possible errors are being logged to
2525
### Problems and errors after restructuring files and folders
2626

2727
If you're doing bigger changes especially to the file and folder structure and recognize some errors on the console like e.g. `TypeError: Cannot read property 'render' of undefined` or `Error building BuildFooterHTML`, it's recommended to stop Pattern Lab, delete the cache file `dependencyGraph.json` within the projects root and start Pattern Lab again, as these changes might conflict with the existing cache structures.
28+
29+
### Running localhost via HTTPS
30+
31+
There might be use cases in which you'd like to let your [localhost dev server run via HTTPS instead of HTTP](https://github.com/pattern-lab/live-server#https), like e.g. when consuming from other secure contexts to prevent browser errors or problems.
32+
33+
Achieving this is a three-step process:
34+
- generate a self-signed SSL certificate
35+
- add it to the trusted certificates
36+
- configure the certificates for `live-server`
37+
38+
#### Generate a self-signed SSL certificate
39+
40+
First, create a folder like, e.g., `ssl` at the root of your project.
41+
42+
Then run the following command in your terminal:
43+
44+
```
45+
openssl req -x509 -nodes -out ssl/localhost.crt \
46+
-keyout ssl/localhost.key \
47+
-newkey rsa:2048 -sha256 \
48+
-subj '/CN=localhost' -extensions EXT \
49+
-config <( \
50+
printf "[dn]\nCN=localhost\n[req]\ndistinguished_name = dn\n[EXT]\nsubjectAltName=DNS:localhost\nkeyUsage=digitalSignature\nextendedKeyUsage=serverAuth")
51+
```
52+
53+
This has been adapted from <https://stackoverflow.com/a/56074120> according to the [`Let's encrypt` instructions](https://letsencrypt.org/docs/certificates-for-localhost/); additionally, DigitalOcean provides some further explanations in [a tutorial](https://www.digitalocean.com/community/tutorials/how-to-create-a-self-signed-ssl-certificate-for-nginx-in-ubuntu-16-04).
54+
55+
#### Add the certificate to the trusted certificates
56+
57+
A [stack overflow entry](https://stackoverflow.com/a/56074120) as well mentions using the following command to add the certificate to the trusted certificates, as [suggested on a blog](https://derflounder.wordpress.com/2011/03/13/adding-new-trusted-root-certificates-to-system-keychain/):
58+
59+
```
60+
sudo security add-trusted-cert -d -r trustRoot -k "/Library/Keychains/System.keychain" "ssl/localhost.crt"
61+
```
62+
63+
You could as well skip this step and accept the certificate after opening the secured pattern lab in your browser for the first time, as described in step 5 of the [DigitalOcean tutorial](https://www.digitalocean.com/community/tutorials/how-to-create-a-self-signed-ssl-certificate-for-nginx-in-ubuntu-16-04#step-5-test-encryption).
64+
65+
#### Configure the certificates for `live-server`
66+
67+
According to the [`live-server` documentation](https://github.com/pattern-lab/live-server#https), you'll then add those certificates to the local dev server:
68+
69+
> To enable HTTPS support, you'll need to create a configuration module.
70+
71+
In our case, you could, e.g., create a file called `ssl.js` in the `ssl` folder with the following contents:
72+
73+
```js
74+
var fs = require("fs");
75+
76+
module.exports = {
77+
cert: fs.readFileSync(__dirname + "/localhost.crt"),
78+
key: fs.readFileSync(__dirname + "/localhost.key")
79+
};
80+
```
81+
82+
Finally, you'll have to add this as a configuration module to the pattern lab `serverOptions` within the `patternlab-config.json` file:
83+
```json
84+
"serverOptions": {
85+
...
86+
"https": "ssl/ssl.js"
87+
},
88+
```
89+
90+
Et voilà, after starting the process of serving pattern lab the next time, it'll open as a secured page.

0 commit comments

Comments
 (0)