docs: update for v0.1.0 release

CHANGELOG.md

@@ -1,6 +1,6 @@
 # Pomerium Changelog
 
-## vUNRELEASED
+## v0.1.0
 
 ### NEW
 
@@ -15,17 +15,18 @@
 - Proxy's sign out handler `{}/.pomerium/sign_out` now accepts an optional `redirect_uri` parameter which can be used to specify a custom redirect page, so long as it is under the same top-level domain. [GH-183]
 - Policy configuration can now be empty at startup. [GH-190]
 - Websocket support is now set per-route instead of globally. [GH-204]
-- golint removed from amd64 container
+- Golint removed from amd64 container. [GH-215]
+- Pomerium will error if a session cookie is over 4096 bytes, instead of failing silently. [GH-212]
 
 ### FIXED
 
-- Fixed HEADERS environment variable parsing [GH-188]
-- Fixed Azure group lookups [GH-190]
+- Fixed HEADERS environment variable parsing. [GH-188]
+- Fixed Azure group lookups. [GH-190]
 - If a session is too large (over 4096 bytes) Pomerium will no longer fail silently. [GH-211]
-- Internal URLs like dashboard now start auth process to login a user if no session is found [GH-205].
+- Internal URLs like dashboard now start auth process to login a user if no session is found. [GH-205].
 - When set,`CookieDomain` lets a user set the scope of the user session. CSRF cookies will still always be scoped at the individual route level. [GH-181]
 
-  ## v0.0.5
+## v0.0.5
 
 ### NEW
 

docs/docs/examples/config/config.example.yaml

@@ -66,27 +66,17 @@ authorize_service_url: https://authorize.corp.beyondperimeter.com
 
 # Proxied routes and per-route policies are defined in a policy block
 policy:
-  - from: httpbin.corp.beyondperimeter.com
+  - from: https://httpbin.corp.beyondperimeter.com
     to: http://httpbin
     allowed_domains:
       - pomerium.io
     cors_allow_preflight: true
     timeout: 30s
-  - from: external-httpbin.corp.beyondperimeter.com
-    to: httpbin.org
+  - from: https://external-httpbin.corp.beyondperimeter.com
+    to: https://httpbin.org
     allowed_domains:
       - gmail.com
-  - from: weirdlyssl.corp.beyondperimeter.com
-    to: http://neverssl.com
-    allowed_users:
-      - bdd@pomerium.io
-    allowed_groups:
-      - admins
-      - developers
-  - from: hello.corp.beyondperimeter.com
+  - from: https://hello.corp.beyondperimeter.com
     to: http://hello:8080
     allowed_groups:
-      - admins
-  - from: external-search.corp.beyondperimeter.com
-    to: google.com
-    allow_public_unauthenticated_access: true
+      - admins@pomerium.io

docs/docs/examples/config/config.minimal.yaml

@@ -8,10 +8,10 @@ idp_client_id: REPLACE_ME
 idp_client_secret: REPLACE_ME
 
 policy:
-  - from: httpbin.corp.beyondperimeter.com
+  - from: https://httpbin.corp.beyondperimeter.com
     to: http://httpbin
     allowed_domains:
       - pomerium.io
-  - from: external-httpbin.corp.beyondperimeter.com
+  - from: https://external-httpbin.corp.beyondperimeter.com
     to: https://httpbin.org
     allow_public_unauthenticated_access: true

docs/docs/examples/config/policy.example.yaml

@@ -7,25 +7,25 @@
 
 # Proxied routes and per-route policies are defined in a policy block
 # NOTA BENE: You must uncomment the bellow 'policy' key if you are loading policy as a file.
-# policy: 
-  - from: httpbin.corp.beyondperimeter.com
-    to: http://localhost:8000
-    allowed_domains:
-      - pomerium.io
-    cors_allow_preflight: true
-    timeout: 30s
-  - from: external-httpbin.corp.beyondperimeter.com
-    to: httpbin.org
-    allowed_domains:
-      - gmail.com
-  - from: weirdlyssl.corp.beyondperimeter.com
-    to: http://neverssl.com
-    allowed_users:
-      - bdd@pomerium.io
-    allowed_groups:
-      - admins
-      - developers
-  - from: hello.corp.beyondperimeter.com
-    to: http://localhost:8080
-    allowed_groups:
-      - admins@pomerium.io
+# policy:
+- from: https://httpbin.corp.beyondperimeter.com
+  to: http://localhost:8000
+  allowed_domains:
+    - pomerium.io
+  cors_allow_preflight: true
+  timeout: 30s
+- from: https://external-httpbin.corp.beyondperimeter.com
+  to: https://httpbin.org
+  allowed_domains:
+    - gmail.com
+- from: https://weirdlyssl.corp.beyondperimeter.com
+  to: http://neverssl.com
+  allowed_users:
+    - bdd@pomerium.io
+  allowed_groups:
+    - admins
+    - developers
+- from: https://hello.corp.beyondperimeter.com
+  to: http://localhost:8080
+  allowed_groups:
+    - admins@pomerium.io

docs/docs/examples/docker/basic.docker-compose.yml

@@ -1,11 +1,9 @@
 version: "3"
 services:
   pomerium:
-    image: pomerium/pomerium:v0.0.5
+    image: pomerium/pomerium:latest
     environment:
-      - SERVICES=all
       # Generate new secret keys. e.g. `head -c32 /dev/urandom | base64`
-      - SHARED_SECRET=aDducXQzK2tPY3R4TmdqTGhaYS80eGYxcTUvWWJDb2M=
       - COOKIE_SECRET=V2JBZk0zWGtsL29UcFUvWjVDWWQ2UHExNXJ0b2VhcDI=
     volumes:
       # Mount your domain's certificates : https://www.pomerium.io/docs/certificates.html
@@ -20,4 +18,4 @@ services:
   httpbin:
     image: kennethreitz/httpbin:latest
     expose:
-      - 80
+      - 80

docs/docs/examples/docker/nginx.docker-compose.yml

@@ -19,9 +19,9 @@ services:
       # NOTE!: Replace with your identity provider settings https://www.pomerium.io/docs/identity-providers.html
       # - IDP_PROVIDER=google
       # - IDP_PROVIDER_URL=https://accounts.google.com
-      # - IDP_CLIENT_ID=REPLACE_ME.apps.googleusercontent.com
-      # - IDP_CLIENT_SECRET=REPLACE_ME
+      # - IDP_CLIENT_ID=REPLACE_ME
       # - IDP_CLIENT_SECRET=REPLACE_ME
+      # - IDP_SERVICE_ACCOUNT=REPLACE_ME
       # NOTE! Generate new secret keys! e.g. `head -c32 /dev/urandom | base64`
       # Generated secret keys must match between services
 

docs/docs/examples/kubernetes/proxy.deploy.yml

@@ -30,7 +30,7 @@ spec:
             - name: AUTHENTICATE_SERVICE_URL
               value: https://authenticate.corp.beyondperimeter.com
             - name: AUTHENTICATE_INTERNAL_URL
-              value: "pomerium-authenticate-service.pomerium.svc.cluster.local"
+              value: "https://pomerium-authenticate-service.pomerium.svc.cluster.local"
             - name: OVERRIDE_CERTIFICATE_NAME
               value: "*.corp.beyondperimeter.com"
             - name: SHARED_SECRET

docs/docs/upgrading.md

@@ -7,9 +7,47 @@ description: >-
 
 # Overview
 
+## Since 0.0.5
+
+This page contains the list of deprecations and important or breaking changes for pomerium `v0.1.0` compared to `v0.0.5`. Please read it carefully.
+
+### Semantic versioning changes
+
+Starting with `v0.1.0` we've changed our [releases](https://semver.org/) are versioned (`MAJOR.MINOR.PATCH+GITHASH`). Planned, monthly releases will now bump `MINOR` and any security or stability releases required prior will bump `PATCH`.
+
+Please note however that we are still pre `1.0.0` so breaking changes can and will happen at any release though we will do our best to document them.
+
+### Breaking: Policy must be valid URLs
+
+Previously, it was allowable to define a policy without a schema (e.g. `http`/`https`). Starting with version `v0.1.0` all `to` and `from` [policy] URLS must contain valid schema and host-names. For example:
+
+```yaml
+policy:
+  - from: httpbin.corp.domain.example
+    to: http://httpbin
+    allowed_domains:
+      - pomerium.io
+  - from: external-httpbin.corp.domain.example
+    to: https://httpbin.org
+    allow_public_unauthenticated_access: true
+```
+
+Should now be:
+
+```yaml
+policy:
+  - from: https://httpbin.corp.domain.example
+    to: http://httpbin
+    allowed_domains:
+      - pomerium.io
+  - from: https://external-httpbin.corp.domain.example
+    to: https://httpbin.org
+    allow_public_unauthenticated_access: true
+```
+
 ## Since 0.0.4
 
-This page contains the list of deprecations and important or breaking changes for pomerium `v0.0.4` compared to `v0.0.5`. Please read it carefully.
+This page contains the list of deprecations and important or breaking changes for pomerium `v0.0.5` compared to `v0.0.4`. Please read it carefully.
 
 ### Breaking: POLICY_FILE removed
 
@@ -48,3 +86,5 @@ Usage of the POLICY_FILE envvar is no longer supported. Support for file based p
 ### Authenticate Internal Service Address
 
 The configuration variable [Authenticate Internal Service URL](https://www.pomerium.io/reference/#authenticate-internal-service-url) must now be a valid [URL](https://golang.org/pkg/net/url/#URL) type and contain both a hostname and valid `https` schema.
+
+[policy]: ../reference/readme.md#policy

docs/guide/binary.md

@@ -31,7 +31,7 @@ Create a config file (`config.yaml`). This file will be used to determine Pomeri
 
 ### Environmental Variables
 
-As mentioned above, Pomerium supports mixing and matching  configuration. For example, we can specify our secret values and domains certificates as [environmental configuration variables], and set the rest as part of the configuration file.
+As mentioned above, Pomerium supports mixing and matching configuration. For example, we can specify our secret values and domains certificates as [environmental configuration variables], and set the rest as part of the configuration file.
 
 <<< @/docs/docs/examples/config/config.minimal.env
 

docs/guide/from-source.md

@@ -8,12 +8,12 @@ meta:
 
 # Building Pomerium From Source
 
-The following quick-start guide covers how to retrieve and build Pomerium directly from it's source-code as well as how to run Pomerium using a minimal but complete configuration. One of the benefits of compiling from source is that Go supports building static binaries for a [wide array of architectures and operating systems](https://gist.github.com/asukakenji/f15ba7e588ac42795f421b48b8aede63) — some of which may not yet be supported by Pomerium's official images or binaries. 
+The following quick-start guide covers how to retrieve and build Pomerium from its source-code as well as how to run Pomerium using a minimal but complete configuration. One of the benefits of compiling from source is that Go supports building static binaries for a [wide array of architectures and operating systems](https://gist.github.com/asukakenji/f15ba7e588ac42795f421b48b8aede63) -- some of which may not yet be supported by Pomerium's official images or binaries.
 
 ## Prerequisites
 
--  [git](https://git-scm.com/) 
--  [go](https://golang.org/doc/install) programming language
+- [git](https://git-scm.com/)
+- [go](https://golang.org/doc/install) programming language
 - A configured [identity provider]
 - A [wild-card TLS certificate]
 
@@ -63,7 +63,7 @@ source ./env
 
 ## Navigate
 
-Browse to `external-httpbin.your.domain.example`. Connections between you and [httpbin] will now be proxied and managed by Pomerium. 
+Browse to `external-httpbin.your.domain.example`. Connections between you and [httpbin] will now be proxied and managed by Pomerium.
 
 [configuration variables]: ../reference/readme.md
 [download]: https://github.com/pomerium/pomerium/releases

docs/guide/readme.md

@@ -24,7 +24,7 @@ Download the following `docker-compose.yml` file and modify it to:
 
 - generate new secrets
 - mount your [wild-card TLS certificate]
-- mount Pomerium's `config.yaml` [configuration file]
+- mount your `config.yaml` [configuration file]
 
 <<< @/docs/docs/examples/docker/basic.docker-compose.yml
 

docs/guide/synology.md

@@ -6,7 +6,7 @@ Using Pomerium on your Synology DSM device enables:
 
 - Secure remote access to docker and synology web-applications without a VPN.
 - Unified, multi-factor authentication with your identity provider of choice.
-- Access to services by sub-domain (e.g. `plex.int.nas.example.com` or `wiki.int.nas.example.com`)
+- Access to services by sub-domain (e.g. `plex.int.nas.example` or `wiki.int.nas.example`)
 - TLS everywhere.
 
 Pomerium is lightweight, can easily handle hundreds of concurrent requests, and a single instance typically uses <20MB of memory and very little CPU.
@@ -52,7 +52,7 @@ Destination Port     | 32443
 
 ![Synology setup nginx reverse proxy](./synology/synology-reverse-proxy.png)
 
-This will forward any incoming HTTPS traffic to the Pomerium service that is (not yet) running on port **32433**.
+This will forward any incoming HTTPS traffic to the Pomerium service that is (not yet) running on port **32443**.
 
 ### Certificates
 
@@ -69,8 +69,8 @@ Once the certificate is showing on the list of certificates screen we need to te
 **Click configure**
 
 Services | Certificate
--------- | -----------------------
-*:8443   | `*.int.nas.example.com`
+-------- | -------------------
+*:8443   | `*.int.nas.example`
 
 ![Synology assign wildcard certificate](./synology/synology-certifciate-assignment.png)
 
@@ -98,11 +98,11 @@ We'll also need a test application to manage access to. For this guide we'll use
 
 ### Policy
 
-We will create an extremely basic policy where `httpbin.int.nas.example.com` is replaced with the subdomain you want to use for the httpbin service, and `your.email.address@gmail.com` is replaced with your email address. All other users will be denied, and all other routes will be `404`.
+We will create an extremely basic policy where `httpbin.int.nas.example` is replaced with the subdomain you want to use for the httpbin service, and `your.email.address@gmail.com` is replaced with your email address. All other users will be denied, and all other routes will be `404`.
 
 ```yaml
 # policy.yaml
-- from: httpbin.int.nas.example.com
+- from: https://httpbin.int.nas.example
   to: http://httpbin
   allowed_users:
   - your.email.address@gmail.com
@@ -142,7 +142,7 @@ Click **Advanced Settings**
 
 Go to **Port Settings** tab.
 
-Add an entry where the **Local Port** is **32433** and the container port is **443** and the type is **TCP**.
+Add an entry where the **Local Port** is **32443** and the container port is **443** and the type is **TCP**.
 
 ![Synology pomerium port settings docker](./synology/synology-docker-port-settings.png)
 
@@ -163,22 +163,22 @@ These are the minimum set of configuration settings to get Pomerium running in t
 Go to **Environment** tab.
 
 Field                     | Value
-------------------------- | ---------------------------------------------------------------
+------------------------- | ----------------------------------------------------------------------------------------
 POLICY                    | output of `base64 -i policy.yaml`
-CERTIFICATE               | output of `base64 -i "$HOME/.acme.sh/*.int.nas.bdd.io_ecc/fullchain.cer"`
-CERTIFICATE_KEY           | output of `base64 -i "$HOME/.acme.sh/*.int.nas.bdd.io_ecc/*.int.nas.bdd.io.key"`
-CERTIFICATE_AUTHORITY     | output of `base64 -i "$HOME/.acme.sh/*.int.nas.bdd.io_ecc/ca.cer"`
-OVERRIDE_CERTIFICATE_NAME | `*.int.nas.example.com`
+CERTIFICATE               | output of `base64 -i "$HOME/.acme.sh/*.int.nas.example.io_ecc/fullchain.cer"`
+CERTIFICATE_KEY           | output of `base64 -i "$HOME/.acme.sh/*.int.nas.example.io_ecc/*.int.nas.example.io.key"`
+CERTIFICATE_AUTHORITY     | output of `base64 -i "$HOME/.acme.sh/*.int.nas.example.io_ecc/ca.cer"`
+OVERRIDE_CERTIFICATE_NAME | `*.int.nas.example`
 IDP_CLIENT_SECRET         | Values from setting up your [identity provider]
 IDP_CLIENT_ID             | Values from setting up your [identity provider]
 IDP_PROVIDER              | Values from setting up your [identity provider] (e.g. `google`)
-COOKIE_SECRET             | output of `head -c32 /dev/urandom | base64`
-SHARED_SECRET             | output of `head -c32 /dev/urandom | base64`
+COOKIE_SECRET             | output of `head -c32 /dev/urandom                                                        | base64`
+SHARED_SECRET             | output of `head -c32 /dev/urandom                                                        | base64`
 AUTHORIZE_SERVICE_URL     | `https://localhost`
-AUTHENTICATE_SERVICE_URL  | `https://authenticate.int.nas.example.com`
+AUTHENTICATE_SERVICE_URL  | `https://authenticate.int.nas.example`
 AUTHENTICATE_INTERNAL_URL | `https://localhost`
 
-For a detailed explanation, and additional options, please refer to the [configuration variable docs].
+For a detailed explanation, and additional options, please refer to the [configuration variable docs]. Also note, though not covered in this guide, settings can be made via a mounted configuration file.
 
 Click **Launch**.
 
@@ -190,7 +190,7 @@ If something goes wrong, click the **Logs** tab.
 
 ## Try it out
 
-Navigate to your new service. `https://httpbin.int.nas.example.com`
+Navigate to your new service. `https://httpbin.int.nas.example`
 
 You should be redirected to your identity provider.
 

docs/readme.md

@@ -1,13 +1,12 @@
 ---
 home: true
 heroImage: logo.svg
-heroText:  "latest"
-tagline: "Pomerium is a context and identity aware access proxy." 
+heroText: latest
+tagline: Pomerium is a context and identity aware access proxy.
 ---
 
+# Earlier Versions
 
-
-### Earlier Versions
-
+- [v0.1.0](https://v0-1-0.docs.pomerium.io)
 - [v0.0.5](https://v0-0-5.docs.pomerium.io)
-- [v0.0.4](https://v0-0-4.docs.pomerium.io)
+- [v0.0.4](https://v0-0-4.docs.pomerium.io)

docs/reference/readme.md

@@ -181,9 +181,7 @@ grpc_client_request_duration_ms | Histogram | GRPC client request duration by se
 - Environmental Variable: `POLICY`
 - Config File Key: `policy`
 - Type: [base64 encoded] `string` or inline policy structure in config file
-- Required
-
-  - Required to forward traffic. Pomerium will safely start without a policy configured, but will be unable to authorize or proxy traffic until the configuration is updated to contain a policy.
+- **Required** However, pomerium will safely start without a policy configured, but will be unable to authorize or proxy traffic until the configuration is updated to contain a policy.
 
 Policy contains route specific settings, and access control details. If you are configuring via POLICY environment variable, just the contents of the policy needs to be passed. If you are configuring via file, the policy should be present under the policy key. For example,
 
@@ -194,18 +192,18 @@ A list of policy configuration variables follows.
 #### From
 
 - `yaml`/`json` setting: `from`
-- Type: `string` domain
+- Type: `URL` (must contain a scheme and hostname)
 - Required
-- Example: `httpbin.corp.example.com`
+- Example: `https://httpbin.corp.example.com`
 
 `From` is externally accessible source of the proxied request.
 
 #### To
 
 - `yaml`/`json` setting: `to`
-- Type: `string` domain
+- Type: `URL` (must contain a scheme and hostname)
 - Required
-- Example: `httpbin` , `192.1.20.12:20`, `http://neverssl.com`
+- Example: `http://httpbin` , `https://192.1.20.12:8080`, `http://neverssl.com`
 
 `To` is the destination of a proxied request. It can be an internal resource, or an external resource.