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.

Sign up for GitHub

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

repo: Docker and readme cleanups #354

Merged
merged 1 commit into from
Feb 7, 2025
Merged

repo: Docker and readme cleanups #354

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
182 changes: 101 additions & 81 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,153 +1,173 @@
# Envoy Proxy Website
# Envoy website

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

This website is built using Jekyll and Sphinx to generate static html files, which are then deployed
with netlify.
The website is built with bazel using Pelican and Sphinx.

### Using Bazel on your host development system
The site is deployed to Netlify.

If you have Bazel installed on your host system you can use that to manage and develop
the site directly.
Envoy's documentation for release versions is stored in https://github.com/envoyproxy/archive/.

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

If you use Bazel directly on your host, you will need some minimum system requirements. These
requirements can be seen for a Ubuntu-based system in the provided [Dockerfile](docker/Dockerfile).
## Contribute content to the website

### Using Bazel in a Docker container
### Site data

You can also run the necessary Bazel commands inside a Docker container.
Site data is stored (or created) in yaml files in the [site/data](./site/data) directory.

A [docker-compose](docker-compose.yml) file has been provided for your convenience, which uses a [Docker image](docker/Dockerfile) containing the system requirements expected by Bazel.
### Add adopter logo

The [composition](docker-compose.yml) is designed to make use of the Bazel cache on your host system.
Envoy is happy to recognize projects that use the software in production.

You may need to export the `UID` of your user to run the container.
These are not intended to be an advertisement, but a show of support for the project.

```console
$ export UID
```
All supporting organizations will be listed in alphabetical order.

### The Bazel Ruby toolchain
To be added to our adopter list, you must meet at least 2 of these criteria:

As Ruby is required to build the website, a Ruby toolchain is included in the Bazel rules.
* 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

This will look for any available Ruby binaries in its environment.
To add your logo, please send a [pull request](https://github.com/envoyproxy/envoy-website/pulls).

If it finds a version matching the one specified in [.ruby-version](.ruby-version) it will use that one.

Otherwise, it will compile the required Ruby version, caching the binary for further use.
## Envoy website development

If you run Bazel commands inside a Docker container it will need to compile Ruby unless it finds a previously compiled and cached version.
Sphinx is used to build the latest docs, and Pelican is used to assemble the static files into a site.

### Running the live site locally (Bazel)
The build process is **managed by bazel** to ensure reproducible builds and manage external data.

```console
$ bazel run //site:live
```
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 site should now be available by visiting http://localhost:4000.
The [composition](docker-compose.yml) is designed to make use of a Bazel cache on your host system.

By default only the website and not the documentation is served by this environment.
#### Docker: export your `UID`

You can view the entire site, built with the latest documentation, with the following:
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 ENVOY_COMMIT="$(bazel run //docs:latest_version)"
$ bazel run --action_env=ENVOY_COMMIT //site:live_docs
$ export UID
```

Changes made to content in the underscore-prefixed jekyll folders will trigger an immediate server reload.
#### Docker: build the website

### Running the site locally (Docker)
```console
$ docker compose up --build -d website
```

You can run the website inside a Docker container with the provided [compose recipe](docker-compose.yml).
This will take some time on first run - you can tail the logs with:

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

By default only the website and not the documentation is served by this environment.
Once the build has completed the website should be available at http://localhost:8000.

You can view the entire site, built with the latest documentation, with the following:
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 up live_docs
$ docker compose run build
```

Changes made to content in the underscore-prefixed jekyll folders will trigger an immediate server reload.
### Build the site on your host machine

### Building the site locally (Bazel)
If you would prefer not to use Docker you can build directly on your host machine.

The Bazel target to build the entire website is:
#### Host: install bazel

```console
$ export ENVOY_COMMIT="$(bazel run //docs:latest_version)"
$ bazel build --action_env=ENVOY_COMMIT //site:html
```
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.

There is a convenience script (as used in CI) that will build into a `_site` folder in the current
directory:
If you have Yarn installed you can install Bazelisk with that.

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

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

### Building the site locally (Docker)
#### Host: install a compiler

The following command will build the entire website, including all documentation, into a `_site` folder in the current
directory:
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
$ docker-compose run build
$ apt get install build-essential
```

### Running Bazel commands inside a container.
If you [build without the docs](#build-without-the-docs), you can ignore this requirement.

To drop into a Docker container, with the port mappings configured in the [composition](docker-compose.yml) file:
#### Host: build the website

```console
$ docker-compose run -p 4000:4000 live bash
$ ./build-website.sh
```

From there you can run Bazel commands directly, for example:
### 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
```

username@73deecbfaf55:/src/workspace/envoy-website$ bazel run //docs:latest_version
...
b200312ddcbc4d237cd197a42cdd8c66cc8c6af0
If you are building on your host you can just run the rebuild script directly:

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

### Site content
#### Build without the docs

Item | Path
:----|:----
Home page content | [`_data/home.yml`](./_data/home.yml)
Nav links on the main page | [`_data/nav.yml`](./_data/nav.yml)
Documentation (auto-generated) | [`docs`](./docs)
If you only need the non-docs parts of the website to be built, set the following environment
variable.

### Creating New Pages
Set this before building in Docker **or** on your host:

To create a new page, all you need to do is create a new file in the root directory. This file can be either a Markdown
file or an HTML file.
```console
$ export BAZEL_BUILD_OPTIONS="--config=nodocs"
```

The new file should contain what Jekyll calls [front matter](https://jekyllrb.com/docs/frontmatter/), which is essentially
YAML markup that lets you set options like the template, the permalink, and the title of the page.
#### Debug build

### Add Envoy Adopter Logo
You can enable richer logging.

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 these criteria:
Set the following environment variable before building in Docker **or** on your host:

* Be a participant and active contributor in the community, this can be contributing code, issues or sponsoring EnvoyCon
* Publicly disclose your usage of Envoy via a [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) or [social media](https://twitter.com/suhailpatel/status/1113425967144476672)
* Submit a high quality grayscale vector SVG logo, we scale the height to 52px (see [example](https://d33wubrfki0l68.cloudfront.net/c814eec20d8e4de39697c7b5790284babe86b248/d1091/img/logos/lyft.svg))
* Have an existing Envoy maintainer vouch for and approve your pull request
```console
$ export DEBUG=1
```

To add your logo, please send a [pull request](https://github.com/envoyproxy/envoy-website) (see this as an [example](https://github.com/envoyproxy/envoy-website/pull/102)).
#### Put frequently used env vars in `.env`

### The Envoy blog
Docker compose will source the `.env` file before running.

The official Envoy blog is hosted on [Medium](https://medium.com) at https://blog.envoyproxy.io.
For example, if you always want the site to build "live", add the following to `.env`

```sh
export BUILDER=live
```
Loading