Update Docker Quickstart (#2482) (#2486)

* Implement partial files

* fix markdown link

* Update Quickstart Doc

This update simplifies the quickstart process by assuming a local test environment without a TLS solution or a FQDN

* add TLS warning

* point to local verify container

* rm empty file

* reference Certificate topic page instructions

* update mkcert instructions

* Update docs/docs/install/readme.md

Co-authored-by: bobby <1544881+desimone@users.noreply.github.com>

* Update docs/partials/install-mkcert.md

Co-authored-by: bobby <1544881+desimone@users.noreply.github.com>

* Update examples/config/config.docker.yaml

Co-authored-by: bobby <1544881+desimone@users.noreply.github.com>

* Update examples/config/config.docker.yaml

Co-authored-by: bobby <1544881+desimone@users.noreply.github.com>

* Update examples/config/config.docker.yaml

Co-authored-by: bobby <1544881+desimone@users.noreply.github.com>

* Update examples/config/config.docker.yaml

Co-authored-by: bobby <1544881+desimone@users.noreply.github.com>

* review edits

Co-authored-by: bobby <1544881+desimone@users.noreply.github.com>

Co-authored-by: bobby <1544881+desimone@users.noreply.github.com>

docs/.vuepress/config.js

@@ -27,6 +27,11 @@ module.exports = {
   ],
   markdown: {
     externalLinkSymbol: false,
+    extendMarkdown:(md) => {
+      md.use(require('markdown-it-include'), {
+        root: './docs/partials/'
+      })
+    },
   },
   themeConfig: {
     home: false,

docs/docs/install/helm.md

@@ -33,18 +33,7 @@ This setup uses [mkcert] to generate certificates that are trusted by your local
 
 ### Install mkcert
 
-After [installing mkcert], confirm the presence and names of your local CA files:
+!!!include(install-mkcert.md)!!!
-
-```bash
-mkcert -install
-The local CA is already installed in the system trust store! 👍
-The local CA is already installed in the Firefox and/or Chrome/Chromium trust store! 👍
-
-ls $(mkcert -CAROOT)
-rootCA-key.pem  rootCA.pem
-```
-
-The output of `mkcert -install` may vary depending on you operating system.
 
 ## Install and Configure cert-manager
 
@@ -216,7 +205,6 @@ Congratulations on installing Pomerium to your Kubernetes cluster! If you're ins
 [Install helm]: https://helm.sh/docs/using_helm/
 [identity provider]: ../identity-providers/readme.md
 [Install Pomerium Enterprise in Helm]: /enterprise/install/helm.md
-[installing mkcert]: https://github.com/FiloSottile/mkcert#installation
 [Install kubectl]: https://kubernetes.io/docs/tasks/tools/install-kubectl/
 [Kubernetes]: https://kubernetes.io
 [mkcert]: https://github.com/FiloSottile/mkcert

docs/docs/install/readme.md

@@ -16,44 +16,23 @@ In this quick-start document, we'll create a minimal but complete environment fo
 - A configured [identity provider]
 - [Docker] and [docker-compose]
 - [TLS certificates]
+  - This document assumes that your local Docker environment does not have a fully qualified domain name (**[FQDN]**) routed to it, and that you followed [Self-signed wildcard certificate] to generate a locally trusted key pair. Otherwise, adjust the configurations below to match your certificate solution.
 
 ## Configure
 
-### Configuration file
+1. Create a [configuration file] (e.g `config.yaml`) for defining Pomerium's configuration settings, routes, and access policies. Consider the following example:
 
-Create a [configuration file] (e.g `config.yaml`) for defining Pomerium's configuration settings, routes, and access-policies. Consider the following example:
+   <<< @/examples/config/config.docker.yaml
 
-<<< @/examples/config/config.minimal.yaml
+   Keep track of the path to this file, relative to the `docker-compose.yml` file created in the next step. `docker-compose.yml` will need the correct relative path to your `config.yaml`.
 
-Ensure the `docker-compose.yml` contains the correct path to your `config.yaml`.
+1. Create or copy the following `docker-compose.yml` file and modify it to match your configuration, including the correct paths to your `config.yaml` and certificate files:
 
-### Autocert Docker-compose
+   <<< @/examples/docker/basic.docker-compose.yml
-Ensure you have set up the requisite DNS and port forwarding in [TLS certificates]
-
-Download the following `docker-compose.yml` file and modify it to:
-
-- generate new secrets
-- mount your [TLS certificates]
-- mount your `config.yaml` [configuration file]
-- Set `autocert_use_staging` to `false` once you have finished testing
-
-<<< @/examples/docker/autocert.docker-compose.yml
-
-Please note that you should use a persistent volume to store certificate data, or you may exhaust your domain quota on Let's Encrypt.
-
-### Wildcard Docker-compose
-
-Download the following `docker-compose.yml` file and modify it to:
-
-- generate new secrets
-- mount your [TLS certificates]
-- mount your `config.yaml` [configuration file]
-
-<<< @/examples/docker/basic.docker-compose.yml
 
 ## Run
 
-Finally, simply run docker compose.
+Run docker compose:
 
 ```bash
 docker-compose up
@@ -63,10 +42,18 @@ Docker will automatically download the required [container images] for Pomerium
 
 You should now be able access to the routes (e.g. `https://verify.localhost.pomerium.io`) as specified in your policy file.
 
-You can also navigate to the special pomerium endpoint `verify.corp.yourdomain.example/.pomerium/` to see your current user details.
+You can also navigate to the special pomerium endpoint `verify.localhost.pomerium.io/.pomerium/` to see your current user details.
 
 ![currently logged in user](./img/logged-in-as.png)
 
+## Next Steps
+
+Now you can experiment with adding services to Docker and defining routes and policies for them in Pomerium. See [Guides](/guides/readme.md) for help or inspiration.
+
+::: warning This is a test environment!
+If you followed all the steps in this doc your Pomerium environment is not using trusted certificates. Remember to use a valid certificate solution before moving this configuration to a production environment. See [Certificates][tls certificates] for more information.
+:::
+
 [configuration file]: ../../reference/readme.md
 [container images]: https://hub.docker.com/r/pomerium/pomerium
 [docker]: https://docs.docker.com/install/
@@ -74,3 +61,6 @@ You can also navigate to the special pomerium endpoint `verify.corp.yourdomain.e
 [verify]: https://verify.pomerium.com/
 [identity provider]: ../identity-providers/readme.md
 [tls certificates]: ../topics/certificates.md
+[fqdn]: https://en.wikipedia.org/wiki/Fully_qualified_domain_name
+[mkcert]: https://github.com/FiloSottile/mkcert
+[Self-signed wildcard certificate]: /docs/topics/certificates.md##self-signed-wildcard-certificate

docs/docs/topics/certificates.md

@@ -50,15 +50,31 @@ See the [Autocert] and [Autocert Directory] settings for more details.
 
 In production, we'd use a public certificate authority such as LetsEncrypt. But for a local proof of concept or for development, we can use [mkcert](https://mkcert.dev/) to make locally trusted development certificates with any names you'd like. The easiest, is probably to use `*.localhost.pomerium.io` which we've already pre-configured to point back to localhost.
 
-```bash
+1. Install mkcert.
-# Install mkcert.
+
-go get -u filippo.io/mkcert
+   :::: tabs
-# Bootstrap mkcert's root certificate into your operating system's trust store.
+   ::: tab Go
-mkcert -install
+   ```bash
-# Create your wildcard domain.
+   go get -u filippo.io/mkcert
-# *.localhost.pomerium.io is helper domain we've hard-coded to route to localhost
+   ```
-mkcert "*.localhost.pomerium.io"
+   :::
-```
+   ::: tab Homebrew
+   ```bash
+   brew install mkcert
+   ```
+   ::::
+
+1. Bootstrap mkcert's root certificate into your operating system's trust store.
+
+   ```bash
+   mkcert -install
+   ```
+
+1. Create your wildcard domain. `*.localhost.pomerium.io` is helper domain we've hard-coded to route to localhost:
+
+   ```bash
+   mkcert "*.localhost.pomerium.io"
+   ```
 
 ### Manual DNS Let's Encrypt wildcard certificate
 

docs/partials/install-mkcert.md

@@ -0,0 +1,14 @@
+After [installing mkcert], confirm the presence and names of your local CA files:
+
+```bash
+mkcert -install
+The local CA is already installed in the system trust store! 👍
+The local CA is already installed in the Firefox and/or Chrome/Chromium trust store! 👍
+
+ls "$(mkcert -CAROOT)"
+rootCA-key.pem  rootCA.pem
+```
+
+The output of `mkcert -install` may vary depending on your operating system.
+
+[installing mkcert]: https://github.com/FiloSottile/mkcert#installation

examples/config/config.docker.yaml

@@ -0,0 +1,36 @@
+# See detailed configuration settings : https://www.pomerium.com/docs/reference/
+
+
+# this is the domain the identity provider will callback after a user authenticates
+authenticate_service_url: https://authenticate.localhost.pomerium.io
+
+####################################################################################
+# Certificate settings:  https://www.pomerium.com/docs/reference/certificates.html #
+# The example below assumes a certificate and key file will be mounted to a volume available to the       #
+# Docker image.                                                                    #
+####################################################################################
+certificate_file: /pomerium/cert.pem
+certificate_key_file: /pomerium/privkey.pem
+
+##################################################################################
+# Identity provider settings : https://www.pomerium.com/docs/identity-providers/ #
+# The keys required in this section vary depending on your IdP. See the          #
+# appropriate docs for your IdP to configure Pomerium accordingly.               #
+##################################################################################
+idp_provider: google
+idp_client_id: REPLACE_ME
+idp_client_secret: REPLACE_ME
+
+# Generate 256 bit random keys  e.g. `head -c32 /dev/urandom | base64`
+cookie_secret: V2JBZk0zWGtsL29UcFUvWjVDWWQ2UHExNXJ0b2VhcDI=
+
+# https://pomerium.com/reference/#routes
+routes:
+  - from: https://verify.localhost.pomerium.io
+    to: http://verify
+    policy:
+      - allow:
+          or:
+            - email:
+                is: user@example.com
+    pass_identity_headers: true

examples/docker/basic.docker-compose.yml

@@ -2,20 +2,17 @@ version: "3"
 services:
   pomerium:
     image: pomerium/pomerium:latest
-    environment:
-      # Generate new secret keys. e.g. `head -c32 /dev/urandom | base64`
-      - COOKIE_SECRET=V2JBZk0zWGtsL29UcFUvWjVDWWQ2UHExNXJ0b2VhcDI=
     volumes:
-      # Mount your domain's certificates : https://www.pomerium.com/docs/reference/certificates
+      ## Mount your domain's certificates : https://www.pomerium.com/docs/reference/certificates
-      - ~/.acme.sh/*.corp.beyondperimeter.com_ecc/fullchain.cer:/pomerium/cert.pem:ro
+      - ./_wildcard.localhost.pomerium.io.pem:/pomerium/cert.pem:ro
-      - ~/.acme.sh/*.corp.beyondperimeter.com_ecc/*.corp.beyondperimeter.com.key:/pomerium/privkey.pem:ro
+      - ./_wildcard.localhost.pomerium.io-key.pem:/pomerium/privkey.pem:ro
-      # Mount your config file : https://www.pomerium.com/docs/reference/
 
-      - ../config/config.minimal.yaml:/pomerium/config.yaml:ro
+      ## Mount your config file : https://www.pomerium.com/docs/reference/
+      - ./config.yaml:/pomerium/config.yaml:ro
     ports:
       - 443:443
 
-  # https://verify.corp.beyondperimeter.com --> Pomerium --> http://verify
+  ## https://verify.localhost.pomerium.io --> Pomerium --> http://verify
   verify:
     image: pomerium/verify:latest
     expose:

package.json

@@ -14,6 +14,7 @@
     "console:buildref": "node scripts/generate-console-pages.js"
   },
   "dependencies": {
-    "esm": "3.2.25"
+    "esm": "3.2.25",
+    "markdown-it-include": "^2.0.0"
   }
 }