mirror of
https://github.com/pomerium/pomerium.git
synced 2025-05-23 05:57:19 +02:00
* 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>
This commit is contained in:
Alex Fornuto
GitHub
parent
bd513a84df
commit
1164e10b48
8 changed files with 108 additions and 61 deletions
|
|
@ -27,6 +27,11 @@ module.exports = {
|
|||
],
|
||||
markdown: {
|
||||
externalLinkSymbol: false,
|
||||
extendMarkdown:(md) => {
|
||||
md.use(require('markdown-it-include'), {
|
||||
root: './docs/partials/'
|
||||
})
|
||||
},
|
||||
},
|
||||
themeConfig: {
|
||||
home: false,
|
||||
|
|
|
|||
|
|
@ -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:
|
||||
|
||||
```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.
|
||||
!!!include(install-mkcert.md)!!!
|
||||
|
||||
## 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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
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
|
||||
<<< @/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.
|
||||
|
||||
|
||||
|
||||
## 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
|
||||
|
|
@ -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
|
||||
# Install mkcert.
|
||||
go get -u filippo.io/mkcert
|
||||
# Bootstrap mkcert's root certificate into your operating system's trust store.
|
||||
mkcert -install
|
||||
# Create your wildcard domain.
|
||||
# *.localhost.pomerium.io is helper domain we've hard-coded to route to localhost
|
||||
mkcert "*.localhost.pomerium.io"
|
||||
```
|
||||
1. Install mkcert.
|
||||
|
||||
:::: tabs
|
||||
::: tab Go
|
||||
```bash
|
||||
go get -u filippo.io/mkcert
|
||||
```
|
||||
:::
|
||||
::: 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
|
||||
|
||||
|
|
|
|||
14
docs/partials/install-mkcert.md
Normal file
14
docs/partials/install-mkcert.md
Normal file
|
|
@ -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
|
||||
36
examples/config/config.docker.yaml
Normal file
36
examples/config/config.docker.yaml
Normal file
|
|
@ -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
|
||||
|
|
@ -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
|
||||
- ~/.acme.sh/*.corp.beyondperimeter.com_ecc/fullchain.cer:/pomerium/cert.pem:ro
|
||||
- ~/.acme.sh/*.corp.beyondperimeter.com_ecc/*.corp.beyondperimeter.com.key:/pomerium/privkey.pem:ro
|
||||
# Mount your config file : https://www.pomerium.com/docs/reference/
|
||||
## 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
|
||||
|
||||
- ../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:
|
||||
|
|
|
|||
|
|
@ -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"
|
||||
}
|
||||
}
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue