Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

quickstart: remove optionals settings for certificates, and cookie secrets #161

Merged
merged 1 commit into from
Nov 22, 2022
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added content/docs/install/img/user-details-page.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
27 changes: 18 additions & 9 deletions content/docs/install/quickstart.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -17,18 +17,16 @@ 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

1. Create a [configuration file] (e.g `config.yaml`) for defining Pomerium's configuration settings, routes, and access policies. Consider the following example:
1. Create a [configuration file] (e.g. `config.yaml`) for defining Pomerium's configuration settings, routes, and access policies. Consider the following example:

<ConfigDocker/>

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`.
Keep track of the path to this file, relative to the `docker-compose.yaml` file created in the next step. `docker-compose.yaml` will need the correct relative 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:
1. Create or copy the following `docker-compose.yaml` file and modify it to match your configuration, including the correct paths to your `config.yaml` and certificate files:

<DockerCompose/>

Expand All @@ -42,15 +40,26 @@ docker-compose up

Docker will automatically download the required [container images] for Pomerium and [verify]. Then, Pomerium will run with the configuration details set in the previous steps.

You should now be able access to the routes (e.g. `https://verify.localhost.pomerium.io`) as specified in your policy file.
You should now be able to access 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.localhost.pomerium.io/.pomerium/` to see your current user details.
### Handle self-signed certificate warning
When navigating to the `https://verify.localhost.pomerium.io` route defined in your policy, you may encouter the following self-signed certificate warning:

![currently logged in user](./img/logged-in-as.png)
![self-signed warning](./img/self-signed-warning.png)

To resolve this error:
1. Click anywhere inside the browser window
2. Type **thisisunsafe**
3. Make sure **Reload** is selected
3. Press **ENTER**

Your browser will redirect you to the route defined in your policy:

![user details page](./img/user-details-page.png)
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Heads up! There are tools like https://shottr.cc/ that make blurring out / calling out in screenshots much cleaner.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I installed Shottr, WAY cleaner. I'm updating the image.


## Next Steps

Now you can experiment with adding services to Docker and defining routes and policies for them in Pomerium. See [Guides](/docs/guides) for help or inspiration.
Now, you can experiment with adding services to Docker and defining routes and policies for them in Pomerium. See [Guides](/docs/guides) for help or inspiration.

:::caution 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.
Expand Down
18 changes: 11 additions & 7 deletions content/examples/config/config.docker.yaml.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,12 +6,12 @@
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 settings: https://www.pomerium.com/docs/reference/certificates #
# You do not need to generate your own certificates. We auto-generate and populate #
# the certificate variables below with an X.509 public and private key. #
####################################################################################
certificate_file: /pomerium/cert.pem
certificate_key_file: /pomerium/privkey.pem
# certificate_file: /pomerium/cert.pem
# certificate_key_file: /pomerium/privkey.pem

##################################################################################
# Identity provider settings : https://www.pomerium.com/docs/identity-providers/ #
Expand All @@ -22,8 +22,12 @@ 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=
##################################################################################
# Cookie secret settings: https://www.pomerium.com/docs/reference/cookie-secret #
# You do not need to generate a cookie secret. We auto-generate and populate the #
# cookie secret for you below to encrypt and sign session cookies. #
##################################################################################
# cookie_secret: V2JBZk0zWGtsL29UcFUvWjVDWWQ2UHExNXJ0b2VhcDI=

# https://pomerium.com/reference/#routes
routes:
Expand Down
10 changes: 7 additions & 3 deletions content/examples/docker/basic.docker-compose.yml.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,9 +4,13 @@ services:
pomerium:
image: pomerium/pomerium:latest
volumes:
## Mount your domain's certificates : https://www.pomerium.com/docs/reference/certificates
- ./_wildcard.localhost.pomerium.io.pem:/pomerium/cert.pem:ro
- ./_wildcard.localhost.pomerium.io-key.pem:/pomerium/privkey.pem:ro
#################################################################################
# Certificate settings: https://www.pomerium.com/docs/reference/certificates #
# You do not need to mount your certificate files. We auto-generate certificate #
# files in your config.yaml file that will mount on your Docker container. #
#################################################################################
# - ./_wildcard.localhost.pomerium.io.pem:/pomerium/cert.pem:ro
# - ./_wildcard.localhost.pomerium.io-key.pem:/pomerium/privkey.pem:ro

## Mount your config file : https://www.pomerium.com/docs/reference/
- ./config.yaml:/pomerium/config.yaml:ro
Expand Down