mirror of
https://github.com/pomerium/pomerium.git
synced 2025-06-01 02:12:50 +02:00
docs: add build from source guide (#32)
This commit is contained in:
Bobby DeSimone
GitHub
parent
7e1d1a7896
commit
661fd89feb
3 changed files with 80 additions and 36 deletions
31
README.md
31
README.md
|
|
@ -1,11 +1,10 @@
|
|||
<img height="100" src="./docs/.vuepress/public/logo.svg" alt="logo" align="right" >
|
||||
<span>
|
||||
<img height="125" src="./docs/.vuepress/public/logo.svg" alt="logo" align="right">
|
||||
</span>
|
||||
|
||||
# Pomerium
|
||||
|
||||
[](https://travis-ci.org/pomerium/pomerium)
|
||||
[](https://goreportcard.com/report/github.com/pomerium/pomerium)
|
||||
[](https://github.com/pomerium/pomerium/blob/master/LICENSE)
|
||||
[](https://hub.docker.com/r/pomerium/pomerium/)
|
||||
[](https://travis-ci.org/pomerium/pomerium) [](https://goreportcard.com/report/github.com/pomerium/pomerium) [][godocs] [](https://github.com/pomerium/pomerium/blob/master/LICENSE)
|
||||
|
||||
Pomerium is a tool for managing secure access to internal applications and resources.
|
||||
|
||||
|
|
@ -16,24 +15,16 @@ Use Pomerium to:
|
|||
- deploy mutual authenticated encryption (mTLS).
|
||||
- aggregate logging and telemetry data.
|
||||
|
||||
To learn more about some problems Pomerium attempts to address, check out this repository of [resources] covering zero-trust and BeyondCorp.
|
||||
Check out [awesome-zero-trust] to learn more about some problems Pomerium attempts to address.
|
||||
|
||||
## Get started
|
||||
## Docs
|
||||
|
||||
For instructions on getting started using Pomerium, see our [quick start guide].
|
||||
To get started with pomerium, check out our [quick start guide].
|
||||
|
||||
## Start developing
|
||||
For comprehensive docs see our [documentation] and the [godocs].
|
||||
|
||||
Assuming you have a working [Go environment].
|
||||
|
||||
```sh
|
||||
$ go get -d github.com/pomerium/pomerium
|
||||
$ cd $GOPATH/src/github.com/pomerium/pomerium
|
||||
$ make
|
||||
$ source ./env # see env.example
|
||||
$ ./bin/pomerium -debug
|
||||
```
|
||||
|
||||
[resources]: https://github.com/pomerium/awesome-zero-trust
|
||||
[awesome-zero-trust]: https://github.com/pomerium/awesome-zero-trust
|
||||
[documentation]: https://www.pomerium.io/
|
||||
[go environment]: https://golang.org/doc/install
|
||||
[godocs]: https://godoc.org/github.com/pomerium/pomerium
|
||||
[quick start guide]: https://www.pomerium.io/guide/
|
||||
|
|
|
|||
|
|
@ -1,27 +1,78 @@
|
|||
# Quick start
|
||||
|
||||
|
||||
## Using Docker
|
||||
|
||||
* Install [docker] and [docker-compose].
|
||||
* Grab Pomerium's included example [`docker-compose.yml`](https://raw.githubusercontent.com/pomerium/pomerium/master/docker-compose.yml) directly or by cloning the repository.
|
||||
* Update `docker-compose.yml` to match your [identity provider] settings.
|
||||
* Copy your subdomain's wild-card TLS certificate next to the compose file. If you don't have one handy, the included [script] generates one from [LetsEncrypt].
|
||||
* Run docker-compose by runnig the command `$ docker-compose up`.
|
||||
* Pomerium is configured to delegate access to two test apps [helloworld] and [httpbin]. Navigate to `hello.corp.example.com` or `httpbin.corp.example.com`. You should see something like the following in your browser and in your terminal.
|
||||
- Install [docker] and [docker-compose].
|
||||
- Grab Pomerium's included example [`docker-compose.yml`](https://raw.githubusercontent.com/pomerium/pomerium/master/docker-compose.yml) directly or by cloning the repository.
|
||||
- Update `docker-compose.yml` to match your [identity provider] settings.
|
||||
- Copy your subdomain's wild-card TLS certificate next to the compose file. If you don't have one handy, the included [script] generates one from [LetsEncrypt].
|
||||
- Run docker-compose by runnig the command `$ docker-compose up`.
|
||||
- Pomerium is configured to delegate access to two test apps [helloworld] and [httpbin]. Navigate to `hello.corp.example.com` or `httpbin.corp.example.com`. You should see something like the following in your browser and in your terminal.
|
||||
|
||||
|
||||
|
||||
[](https://asciinema.org/a/tfbSWkUZgMRxHAQDqmcjjNwUg)
|
||||
|
||||
[docker-compose]: (https://docs.docker.com/compose/install/)
|
||||
[docker]: https://docs.docker.com/install/
|
||||
[download]: https://github.com/pomerium/pomerium/releases
|
||||
[kms]: https://en.wikipedia.org/wiki/Key_management
|
||||
## From source
|
||||
|
||||
### Get the code
|
||||
|
||||
Using [git](https://git-scm.com/), retrieve the latest copy of pomerium's source code by cloning the repository.
|
||||
|
||||
```bash
|
||||
# where `$HOME/pomerium` is the directory you want to save pomerium
|
||||
git clone https://github.com/pomerium/pomerium.git $HOME/pomerium
|
||||
```
|
||||
|
||||
Build pomerium from source in a single step using make.
|
||||
|
||||
```bash
|
||||
cd $HOME/pomerium
|
||||
make
|
||||
```
|
||||
|
||||
The command will run all the tests, some code linters, then build the binary. If all is good, you should now have a freshly built pomerium binary in the `pomerium/bin` directory.
|
||||
|
||||
### Configure
|
||||
|
||||
Make a copy of the [env.example] and name it something like `env`.
|
||||
|
||||
```bash
|
||||
cp env.example env
|
||||
```
|
||||
|
||||
Modify your `env` configuration to to match your [identity provider] settings.
|
||||
|
||||
```bash
|
||||
vim env
|
||||
```
|
||||
|
||||
### Run
|
||||
|
||||
Finally, source the the configuration `env` file and run pomerium.
|
||||
|
||||
```bash
|
||||
source ./env
|
||||
./bin/pomerium
|
||||
```
|
||||
|
||||
### All-in-one
|
||||
|
||||
Assuming your configuration file ready to go, you can simply use this one-liner.
|
||||
|
||||
```bash
|
||||
make && source ./env && ./bin/pomerium
|
||||
```
|
||||
|
||||
[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
|
||||
[docker]: https://docs.docker.com/install/
|
||||
[docker-compose]: (https://docs.docker.com/compose/install/)
|
||||
[download]: https://github.com/pomerium/pomerium/releases
|
||||
[env.example]: https://github.com/pomerium/pomerium/blob/master/env.example
|
||||
[helloworld]: https://hub.docker.com/r/tutum/hello-world
|
||||
[httpbin]: https://httpbin.org/
|
||||
[LetsEncrypt]: https://letsencrypt.org/
|
||||
[identity provider]: ./identity-providers.md
|
||||
[kms]: https://en.wikipedia.org/wiki/Key_management
|
||||
[letsencrypt]: https://letsencrypt.org/
|
||||
[script]: https://github.com/pomerium/pomerium/blob/master/scripts/generate_wildcard_cert.sh
|
||||
[source]: https://github.com/pomerium/pomerium#start-developing
|
||||
|
|
|
|||
|
|
@ -51,5 +51,7 @@ export IDP_CLIENT_SECRET="REPLACEME"
|
|||
# export SCOPE="openid email" # generally, you want the default OIDC scopes
|
||||
|
||||
# k/v seperated list of simple routes. If no scheme is set, HTTPS will be used.
|
||||
export ROUTES="example.corp.example.com=example.org"
|
||||
# Currently set to httpbin which is a handy utility letting you inspect requests recieved by
|
||||
# a client application
|
||||
export ROUTES="httpbin.corp.example.com=httpbin.org"
|
||||
# export ROUTES="https://weirdlyssl.corp.example.com=http://neverssl.com" #https to http!
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue