deployment : add docker support, docker-compose example, & quick-start guide.

2025-04-28 18:06:34 +02:00 · 2019-01-17 00:22:10 -08:00 · 2019-01-17 00:22:10 -08:00 · 929a1ca7b0
commit 929a1ca7b0
parent 1dac8e56d0 60afad1bd7
5 changed files with 132 additions and 58 deletions
--- a/.gitignore
+++ b/.gitignore
@ -1,4 +1,4 @@
-
+.docker-compose.yml
 pem
 env
 coverage.txt
@ -16,7 +16,7 @@ _test
 # Architecture specific extensions/prefixes
 *.[568vq]
 [568vq].out
-
+ 
 *.cgo1.go
 *.cgo2.c
 _cgo_defun.c
--- a/README.md
+++ b/README.md
@ -15,11 +15,11 @@ Use Pomerium to:
 - deploy mutual authenticated encryption (mTLS).
 - aggregate logging and telemetry data.

+To learn more about the problems Pomerium attempts to address, check out this repository of [resources] covering zero-trust and BeyondCorp.
+
 ## Get started

-For instructions on getting started using Pomerium, see our [docs].
-
-To learn more about zero-trust and BeyondCorp, check out [awesome-zero-trust].
+For instructions on getting started using Pomerium, see our [quick start guide].

 ## Start developing

@ -33,6 +33,6 @@ $ source ./env # see env.example
 $ ./bin/pomerium -debug
 ```

-[awesome-zero-trust]: https://github.com/pomerium/awesome-zero-trust
+[resources] : https://github.com/pomerium/awesome-zero-trust
 [go environment]: https://golang.org/doc/install
-[docs]: https://www.pomerium.io
+[quick start guide]: https://www.pomerium.io/guide/
--- a/docker-compose.yml
+++ b/docker-compose.yml
@ -0,0 +1,97 @@
+# Example Pomerium configuration.
+#
+# NOTE! Change IDP_* settings to match your identity provider settings!
+# NOTE! Generate new SHARED_SECRET and COOKIE_SECRET keys!
+# NOTE! Replace `corp.beyondperimeter.com` with whatever your domain is
+# NOTE! Make sure certificate files (cert.pem/privkey.pem) are in the same directory as this file
+version: "3"
+services:
+  # NGINX routes to pomerium's services depending on the request.
+  nginx-proxy:
+    image: jwilder/nginx-proxy:latest
+    ports:
+      - "443:443"
+    volumes:
+      # NOTE!!! : nginx must be supplied with your wildcard certificates. And it expects
+      # it in the format of whatever your wildcard domain name is in.
+      # see : https://github.com/jwilder/nginx-proxy#wildcard-certificates
+      # So, if your subdomain is corp.beyondperimeter.com, you'd have the following :
+      - ./cert.pem:/etc/nginx/certs/corp.beyondperimeter.com.crt:ro
+      - ./privkey.pem:/etc/nginx/certs/corp.beyondperimeter.com.key:ro
+      - /var/run/docker.sock:/tmp/docker.sock:ro
+
+  pomerium-authenticate:
+    image: pomerium/pomerium:latest
+    environment:
+      - SERVICES=authenticator
+      # auth settings
+      - REDIRECT_URL=https://sso-auth.corp.beyondperimeter.com/oauth2/callback
+      # Identity Provider Settings (Must be changed!)
+      - IDP_PROVIDER="google"
+      - IDP_PROVIDER_URL=https://accounts.google.com
+      - IDP_CLIENT_ID=851877082059-bfgkpj09noog7as3gpc3t7r6n9sjbgs6.apps.googleusercontent.com
+      - IDP_CLIENT_SECRET=P34wwijKRNP3skP5ag5I12kz
+      - SCOPE="openid email"
+      - PROXY_ROOT_DOMAIN=beyondperimeter.com
+      - ALLOWED_DOMAINS=*
+      # shared service settings
+      # Generate 256 bit random keys  e.g. `head -c32 /dev/urandom | base64`
+      - SHARED_SECRET=aDducXQzK2tPY3R4TmdqTGhaYS80eGYxcTUvWWJDb2M=
+      - COOKIE_SECRET=V2JBZk0zWGtsL29UcFUvWjVDWWQ2UHExNXJ0b2VhcDI=
+
+      # if passing certs as files
+      # - CERTIFICATE_KEY=corp.beyondperimeter.com.crt
+      # - CERTIFICATE_KEY_FILE=corp.beyondperimeter.com.key
+      # Or, you can pass certifcates as bas64 encoded values. e.g. `base64 -i cert.pem`
+      # - CERTIFICATE=
+      # - CERTIFICATE_KEY=
+
+      # nginx settings
+      - VIRTUAL_PROTO=https
+      - VIRTUAL_HOST=sso-auth.corp.beyondperimeter.com
+      - VIRTUAL_PORT=443
+    volumes: # volumes is optional; used if passing certificates as files
+      - ./cert.pem:/pomerium/cert.pem:ro
+      - ./privkey.pem:/pomerium/privkey.pem:ro
+    expose:
+      - 443
+
+  pomerium-proxy:
+    image: pomerium/pomerium:latest
+    environment:
+      - SERVICES=proxy
+      # proxy settings
+      - AUTHENTICATE_SERVICE_URL=https://sso-auth.corp.beyondperimeter.com
+      - ROUTES=https://httpbin.corp.beyondperimeter.com=http://httpbin,https://hello.corp.beyondperimeter.com=http://hello-world/
+      # Generate 256 bit random keys  e.g. `head -c32 /dev/urandom | base64`
+      - SHARED_SECRET=aDducXQzK2tPY3R4TmdqTGhaYS80eGYxcTUvWWJDb2M=
+      - COOKIE_SECRET=V2JBZk0zWGtsL29UcFUvWjVDWWQ2UHExNXJ0b2VhcDI=
+
+      # if passing certs as files
+      # - CERTIFICATE_KEY=corp.beyondperimeter.com.crt
+      # - CERTIFICATE_KEY_FILE=corp.beyondperimeter.com.key
+      # Or, you can pass certifcates as bas64 encoded values. e.g. `base64 -i cert.pem`
+      # - CERTIFICATE=
+      # - CERTIFICATE_KEY=
+
+      # nginx settings
+      - VIRTUAL_PROTO=https
+      - VIRTUAL_HOST=*.corp.beyondperimeter.com
+      - VIRTUAL_PORT=443
+    volumes: # volumes is optional; used if passing certificates as files
+      - ./cert.pem:/pomerium/cert.pem:ro
+      - ./privkey.pem:/pomerium/privkey.pem:ro
+    expose:
+      - 443
+
+  # https://httpbin.corp.beyondperimeter.com
+  httpbin:
+    image: kennethreitz/httpbin:latest
+    expose:
+      - 80
+  # Simple hello world
+  # https://hello.corp.beyondperimeter.com
+  hello-world:
+    image: tutum/hello-world:latest
+    expose:
+      - 80
--- a/docs/guide/identity-providers.md
+++ b/docs/guide/identity-providers.md
@ -41,11 +41,11 @@ Your `Client ID` and `Client Secret` will be displayed:
 Set `Client ID` and `Client Secret` in Pomerium's settings. Your [environmental variables] should look something like this.

 ```bash
-export REDIRECT_URL="https://sso-auth.corp.beyondperimeter.com/oauth2/callback"
-export IDP_PROVIDER="google"
-export IDP_PROVIDER_URL="https://accounts.google.com"
-export IDP_CLIENT_ID="yyyy.apps.googleusercontent.com"
-export IDP_CLIENT_SECRET="xxxxxx"
+REDIRECT_URL="https://sso-auth.corp.beyondperimeter.com/oauth2/callback"
+IDP_PROVIDER="google"
+IDP_PROVIDER_URL="https://accounts.google.com"
+IDP_CLIENT_ID="yyyy.apps.googleusercontent.com"
+IDP_CLIENT_SECRET="xxxxxx"
 ```

 ## Okta
@ -78,11 +78,11 @@ Go to the **General** page of your app and scroll down to the **Client Credentia
 At this point, you will configure the integration from the Pomerium side. Your [environmental variables] should look something like this.

 ```bash
-export REDIRECT_URL="https://sso-auth.corp.beyondperimeter.com/oauth2/callback"
-export IDP_PROVIDER="okta"
-export IDP_PROVIDER_URL="https://dev-108295-admin.oktapreview.com/"
-export IDP_CLIENT_ID="0oairksnr0C0fEJ7l0h7"
-export IDP_CLIENT_SECRET="xxxxxx"
+REDIRECT_URL="https://sso-auth.corp.beyondperimeter.com/oauth2/callback"
+IDP_PROVIDER="okta"
+IDP_PROVIDER_URL="https://dev-108295-admin.oktapreview.com/"
+IDP_CLIENT_ID="0oairksnr0C0fEJ7l0h7"
+IDP_CLIENT_SECRET="xxxxxx"
 ```

 ## Azure
@ -151,11 +151,11 @@ At this point, you will configure the integration from the Pomerium side. Your [

 ```bash
 # Azure
-export REDIRECT_URL="https://sso-auth.corp.beyondperimeter.com/oauth2/callback"
-export IDP_PROVIDER="azure"
-export IDP_PROVIDER_URL="https://login.microsoftonline.com/{REPLACE-ME-SEE-ABOVE}/v2.0"
-export IDP_CLIENT_ID="REPLACE-ME"
-export IDP_CLIENT_SECRET="REPLACE-ME"
+REDIRECT_URL="https://sso-auth.corp.beyondperimeter.com/oauth2/callback"
+IDP_PROVIDER="azure"
+IDP_PROVIDER_URL="https://login.microsoftonline.com/{REPLACE-ME-SEE-ABOVE}/v2.0"
+IDP_CLIENT_ID="REPLACE-ME"
+IDP_CLIENT_SECRET="REPLACE-ME"

 ```

--- a/docs/guide/readme.md
+++ b/docs/guide/readme.md
@ -1,47 +1,24 @@
 # Quick start

-1.  [Download] pre-built binaries or build Pomerium from source.
-1.  Generate a wild-card certificate for a test domain like `corp.example.com`. For convenience, an included [script] can generate a free one using LetsEncrypt and [certbot].

-    Once complete, move the generated public and private keys (`cert.pem`/`privkey.pem`) next to the pomerium binary. Certificates can also be set as environmental variables or dynamically with a [KMS].
+## Using Docker

-1.  Next, set configure your [identity provider](./identity-providers.md) by generating an OAuth **Client ID** and **Client Secret** as well as setting a **Redirect URL** endpoint. The Redirect URL endpoint will be called by the identity provider following user authentication.
+* Install [docker](https://docs.docker.com/install/).
+* Install [docker-compose](https://docs.docker.com/compose/install/).
+* Save Pomerium's example [`docker-compose.yml`]().
+* Inspect the `docker-compose.yml` file. In addition to specifying Pomerium's configuration settings, and services, you'll see that there are other included services to give you a feel for how pomerium works. 
+* Update the compose file with your [identity provider] settings. 
+* Copy your subdomain's wild-card TLS certificate next to the compose file. See included [script] to generate one from LetsEncrypt.
+* Run docker compose by runnig the command `$ docker-compose up`. 
+* If you navigate to `https://hello.corp.beyondperimeter.com` or `https://httpbin.corp.beyondperimeter.com` where "corp.beyondperimeter.com" is your subdomain in your browser, you should see something like the following in your browser and in your terminal. 

-1.  Pomerium is configured using [environmental variables]. A minimal configuration is as follows.
+![Getting started](./get-started.gif)

-    ```bash
-    # file : env
-    # The URL that the identity provider will call back after authenticating the user
-    export REDIRECT_URL="https://sso-auth.corp.example.com/oauth2/callback"
-    # Generate 256 bit random keys  e.g. `head -c32 /dev/urandom | base64`
-    export SHARED_SECRET=REPLACE_ME
-    export COOKIE_SECRET=REPLACE_ME
-    # Allow users with emails from the following domain post-fix (e.g. example.com)
-    export ALLOWED_DOMAINS=*
-    ## Identity Provider Settings
-    export IDP_PROVIDER="google"
-    export IDP_PROVIDER_URL="https://accounts.google.com" # optional for google
-    export IDP_CLIENT_ID="YOU_GOT_THIS_FROM_STEP-3.apps.googleusercontent.com"
-    export IDP_CLIENT_SECRET="YOU_GOT_THIS_FROM_STEP-3"
-    # key/value list of simple routes.
-    export ROUTES='http.corp.example.com=httpbin.org'
-    ```
-
-    You can also view the [env.example] configuration file for a more comprehensive list of options.
-
-1.  For a first run, I suggest setting the debug flag which provides user friendly logging.
-
-        ```bash
-        source ./env
-        ./pomerium -debug
-        ```
-
-1.  You should now get the following when you try to access one of your `corp` routes.
-    ![Getting started](./get-started.gif)
+[![asciicast](https://asciinema.org/a/tfbSWkUZgMRxHAQDqmcjjNwUg.svg)](https://asciinema.org/a/tfbSWkUZgMRxHAQDqmcjjNwUg)

 [download]: https://github.com/pomerium/pomerium/releases
-[environmental variables]: https://12factor.net/config
-[env.example]: https://github.com/pomerium/pomerium/blob/master/env.example
 [kms]: https://en.wikipedia.org/wiki/Key_management
 [certbot]: https://certbot.eff.org/docs/install.html
 [script]: https://github.com/pomerium/pomerium/blob/master/scripts/generate_wildcard_cert.sh
+[source]: https://github.com/pomerium/pomerium#start-developing
+[identity provider]: ./identity-providers.md