## 1. Project Overview & Quickstart (envoyproxy/envoy)

## File: README.md

[Cloud-native high-performance edge/middle/service proxy](https://www.envoyproxy.io/)

Envoy is hosted by the [Cloud Native Computing Foundation](https://cncf.io) (CNCF). If you are a
company that wants to help shape the evolution of technologies that are container-packaged,
dynamically-scheduled and microservices-oriented, consider joining the CNCF. For details about who's
involved and how Envoy plays a role, read the CNCF
[announcement](https://www.cncf.io/blog/2017/09/13/cncf-hosts-envoy/).

[](https://bestpractices.coreinfrastructure.org/projects/1266)
[](https://securityscorecards.dev/viewer/?uri=github.com/envoyproxy/envoy)
[](https://clomonitor.io/projects/cncf/envoy)

## Documentation

* [Official documentation](https://www.envoyproxy.io/)
* [FAQ](https://www.envoyproxy.io/docs/envoy/latest/faq/overview)
* [Example documentation](https://github.com/envoyproxy/examples/)
* [Blog](https://medium.com/@mattklein123/envoy-threading-model-a8d44b922310) about the threading model
* [Blog](https://medium.com/@mattklein123/envoy-hot-restart-1d16b14555b5) about hot restart
* [Blog](https://medium.com/@mattklein123/envoy-stats-b65c7f363342) about stats architecture
* [Blog](https://medium.com/@mattklein123/the-universal-data-plane-api-d15cec7a) about universal data plane API
* [Blog](https://medium.com/@mattklein123/lyfts-envoy-dashboards-5c91738816b1) on Lyft's Envoy dashboards

## Related

* [data-plane-api](https://github.com/envoyproxy/data-plane-api): v2 API definitions as a standalone
  repository. This is a read-only mirror of [api](api/).
* [envoy-perf](https://github.com/envoyproxy/envoy-perf): Performance testing framework.
* [envoy-filter-example](https://github.com/envoyproxy/envoy-filter-example): Example of how to add new filters
  and link to the main repository.

## Contact

* [envoy-announce](https://groups.google.com/forum/#!forum/envoy-announce): Low frequency mailing
  list where we will email announcements only.
* [envoy-security-announce](https://groups.google.com/forum/#!forum/envoy-security-announce): Low frequency mailing
  list where we will email security related announcements only.
* [envoy-users](https://groups.google.com/forum/#!forum/envoy-users): General user discussion.
* [envoy-dev](https://groups.google.com/forum/#!forum/envoy-dev): Envoy developer discussion (APIs,
  feature design, etc.).
* [envoy-maintainers](https://groups.google.com/forum/#!forum/envoy-maintainers): Use this list
  to reach all core Envoy maintainers.
* [Twitter](https://twitter.com/EnvoyProxy/): Follow along on Twitter!
* [Slack](https://envoyproxy.slack.com/): Slack, to get invited go [here](https://www.envoyproxy.io/slack).
  * NOTE: Response to user questions is best effort on Slack. For a "guaranteed" response please email
    envoy-users@ per the guidance in the following linked thread.

Please see [this](https://groups.google.com/forum/#!topic/envoy-announce/l9zjYsnS3TY) email thread
for information on email list usage.

## Contributing

Contributing to Envoy is fun and modern C++ is a lot less scary than you might think if you don't
have prior experience. To get started:

* [Contributing guide](CONTRIBUTING.md)
* [Beginner issues](https://github.com/envoyproxy/envoy/issues?q=is%3Aopen+is%3Aissue+label%3Abeginner)
* [Build/test quick start using docker](ci#building-and-running-tests-as-a-developer)
* [Developer guide](DEVELOPER.md)
* Consider installing the Envoy [development support toolchain](https://github.com/envoyproxy/envoy/blob/main/support/README.md), which helps automate parts of the development process, particularly those involving code review.
* Please make sure that you let us know if you are working on an issue so we don't duplicate work!

## Community Meeting

The Envoy team has a scheduled meeting time twice per month on Tuesday at 9am PT. The public
Google calendar is [here](https://goo.gl/PkDijT).  The meeting will only be held
if there are agenda items listed in the [meeting
minutes](https://goo.gl/5Cergb).  Any member of the community should be able to
propose agenda items by adding to the minutes.  The maintainers will either confirm
the additions to the agenda, or will cancel the meeting within 24 hours of the scheduled
date if there is no confirmed agenda.

## Security

### Security Audit

There has been several third party engagements focused on Envoy security:
* In 2018 Cure53 performed a security audit, [full report](docs/security/audit_cure53_2018.pdf).
* In 2021 Ada Logics performed an audit on our fuzzing infrastructure with recommendations for improvements, [full report](docs/security/audit_fuzzer_adalogics_2021.pdf).

### Reporting security vulnerabilities

If you've found a vulnerability or a potential vulnerability in Envoy, please
[open a GitHub Security Advisory](https://github.com/envoyproxy/envoy/security/advisories/new).
This is the preferred reporting channel, as the reports can be triaged directly on GitHub.

Alternatively, you may email [envoy-security@googlegroups.com](mailto:envoy-security@googlegroups.com).

For further details please see our complete [security release process](SECURITY.md).

### OSS fuzzing

[](https://bugs.chromium.org/p/oss-fuzz/issues/list?sort=-opened&can=1&q=proj:envoy)

### ppc64le builds

Builds for the ppc64le architecture are not covered by the envoy security policy. The ppc64le architecture is currently best-effort and not maintained by the Envoy maintainers.

[](https://powerci.osuosl.org/job/build-envoy-static-master/)

### Other builds

[](https://ibmz-ci.osuosl.org/job/Envoy_IBMZ_CI/)

## Releases

For further details please see our [release process](https://github.com/envoyproxy/envoy/blob/main/RELEASES.md).

---

## File: docs/README.md

# Building documentation locally

There are two methods to build the documentation, described below.

In both cases, the generated output can be found in `generated/docs`.

## Building in an existing Envoy development environment

If you have an [existing Envoy development environment](https://github.com/envoyproxy/envoy/tree/main/bazel#quick-start-bazel-build-for-developers), you should have the necessary dependencies and requirements and be able to build the documentation directly.

If using the Docker build container, you can run:

```bash
./ci/do_ci.sh docs
```

By default configuration examples are going to be validated during build. To disable validation,
set `SPHINX_SKIP_CONFIG_VALIDATION` environment variable to `true`:

```bash
SPHINX_SKIP_CONFIG_VALIDATION=true ./ci/do_ci.sh docs
```

If not using the Docker build container, you can run:

```bash
bazel run --@envoy//tools/tarball:target=//:html @envoy//tools/tarball:unpack "$PWD"/generated/docs/
```

## Using the Docker build container to build the documentation

If you *do not* have an existing development environment, you may wish to use the Docker build
image that is used in continuous integration.

This can be done as follows:

```
./ci/run_envoy_docker.sh './ci/do_ci.sh docs'
```

To use this method you will need a minimum of 4-5GB of disk space available to accommodate the build image.

# Creating a Pull Request with documentation changes

When you create a Pull Request the documentation is rendered by Azure Pipelines.

To do this:
1. Open docs job in Azure Pipelines.
2. Navigate to "Upload Docs to GCS" log.
3. Click on the link there.

# How the Envoy website and docs are updated


The docs are published dynamically by Netlify on every commit to main. This process is handled by the
[envoy-website repo](https://github.com/envoyproxy/envoy-website)

For tagged commits the docs are built statically by the [archive repo](https://github.com/envoyproxy/archive),
which in turn triggers a rebuild of the website.

## 2. Official Technical Reference & Guides (envoyproxy/envoy-website)

# Envoy website

This is the repo for the [Envoy website](https://www.envoyproxy.io).

The website is built with bazel using Pelican and Sphinx.

The site is deployed to Netlify.

Envoy's documentation for release versions is stored in https://github.com/envoyproxy/archive/.


## Contribute content to the website

### Site data

Site data is stored (or created) in yaml files in the [site/data](./site/data)  directory.

### Add adopter logo

Envoy is happy to recognize projects that use the software in production.

These are not intended to be an advertisement, but a show of support for the project.

All supporting organizations will be listed in alphabetical order.

To be added to our adopter list, you must meet at least 2 of these criteria:

*   Be a participant and active contributor in the community, eg:
    - contributing code
    - raising or resolving issues
    - sponsoring EnvoyCon
*   Publicly disclose your usage of Envoy, eg:
    - [talk](https://www.youtube.com/watch?v=4x5WjxAMvKY)
    - [blog](https://monzo.com/blog/2019/04/03/deploying-envoy-proxy)
    - [CNCF case study](https://www.cncf.io/newsroom/case-studies/?_sft_cstudies_project=envoy)
    - [social media](https://twitter.com/suhailpatel/status/1113425967144476672)
*   Have an existing Envoy maintainer vouch for and approve your pull request

To add your logo, please send a [pull request](https://github.com/envoyproxy/envoy-website/pulls).


## Envoy website development

Sphinx is used to build the latest docs, and Pelican is used to assemble the static files into a site.

The build process is **managed by bazel** to ensure reproducible builds and manage external data.

All content, data and customizations are stored in the [site directory](https://github.com/envoyproxy/envoy-website/tree/main/site)

### Build using Docker

**This is the recommended way to build the site.**

The [composition](docker-compose.yml) is designed to make use of a Bazel cache on your host system.

#### Docker: export your `UID`

By default Docker cannot see your user's `UID`, so you need to export it to run the container build.

This ensures that any files created inside the container - the site build and any cache files - are owned
by the host user.

```console
$ export UID
```

#### Docker: build the website

```console
$ docker compose up --build -d website
```

This will take some time on first run - you can tail the logs with:

```console
$ docker compose logs -f
```

Once the build has completed the website should be available at http://localhost:8000.

If you are not running the [automatic rebuild](#automatically-rebuild-during-development) and you make changes you can rebuild the site with:

```console
$ docker compose run build
```

### Build the site on your host machine

If you would prefer not to use Docker you can build directly on your host machine.

#### Host: install bazel

The expected version of Bazel can be seen in [.bazelversion](.bazelversion).

It is [recommended to install Bazel with Bazelisk](https://bazel.build/install/bazelisk) as this will pull in the
correct Bazel version.

If you have Yarn installed you can install Bazelisk with that.

From inside your local copy of the envoy-website repository, run:

```console
$ yarn
```

#### Host: install a compiler

You will need a compiler (clang or GCC) and some related dev tools installed to **build the docs**.

For example, on a Debian-based system, these can be installed with:

```console
$ apt get install build-essential
```

If you [build without the docs](#build-without-the-docs), you can ignore this requirement.

#### Host: build the website

```console
$ ./build-website.sh
```

### Tips for site development

#### Automatically rebuild during development

The site can be made to auto-rebuild when changes occur in the `site/` directory.

If you are using Docker you can trigger this by setting the following in your environment,
before bringing up the Docker composition:

```console
$ export BUILDER=live
$ docker compose up --build -d website
```

If you are building on your host you can just run the rebuild script directly:

```console
$ ./rebuild.sh ./site ./build-website.sh
```

#### Build without the docs

If you only need the non-docs parts of the website to be built, set the following environment
variable.

Set this before building in Docker **or** on your host:

```console
$ export BAZEL_BUILD_OPTIONS="--config=nodocs"
```

#### Debug build

You can enable richer logging.

Set the following environment variable before building in Docker **or** on your host:

```console
$ export DEBUG=1
```

#### Put frequently used env vars in `.env`

Docker compose will source the `.env` file before running.

For example, if you always want the site to build "live", add the following to `.env`

```sh
export BUILDER=live
```