Opa: docs: OPA should provide a container with the correct versions of tools to build the website

[patrick-east]

We document the tools required in https://github.com/open-policy-agent/opa/tree/master/docs#full-site-preview and briefly mention that the version of Hugo used is in the netlify config file... what we don't mention is that it really should be exactly that version of hugo if you want to be able to reproduce the build locally.

To make matters even worse it is currently not a simple process to install the "correct" Hugo version on a local machine. The official instructions for Hugo on OSX say to use homebrew, but you cannot just brew install [email protected], so a user is left to go find the binary and install it manually or hack around the homebrew formulas to install the older one.

Almost all of this could be solved if we had a container image that contained the required tools (hugo, node, netlify, etc etc).

[gaga5lala]

@patrick-east Can I take up this?

[patrick-east]

@gaga5lala go for it! 👍

If you run into any issues feel free to reach out to me.

[gaga5lala]

@patrick-east I plan to solve this issue with following steps

1. Setup the environments on my laptop and runmake docs-preview-build, make docs-serve-local
2. After successfully execute step 1, prepare a docker image contained the required tools

$ sw_vers
ProductName:    Mac OS X
ProductVersion: 10.15.5
BuildVersion:   19F101

$ go version
go version go1.14 darwin/amd64

$ node --version
v12.16.3

$ hugo version
Hugo Static Site Generator v0.55.0-4333CC77F/extended darwin/amd64 BuildDate: 2019-04-08T17:03:33Z

$ netlify --version
netlify-cli/2.54.0 darwin-x64 node-v12.16.3

Occur issue when running $ make docs-preview-build

Found OPA version v0.15.1, available at /Users/gaga/github/opa/docs/website/scripts/live-blocks/opa_versions/v0.15.1-darwin
Processing ../../public/docs/v0.14.2/index.html...
Locating OPA version v0.14.2...
Found OPA version v0.14.2, available at /Users/gaga/github/opa/docs/website/scripts/live-blocks/opa_versions/v0.14.2-darwin
Processing ../../public/docs/latest/index.html...
Locating OPA version latest...
Found OPA version latest, available at /Users/gaga/github/opa/docs/website/scripts/live-blocks/opa_versions/latest-darwin
Processing ../../public/docs/edge/index.html...
Locating OPA version edge...

--- Errors for ../../public/docs/edge/index.html ---
ChainedError: example/final evaluation failed for an unexpected, possibly internal reason (check for additional logs): binary for edge is not a
vailable at path /Users/gaga/github/opa/opa_darwin_amd64, ensure it has been built for the current platform
    at /Users/gaga/github/opa/docs/website/scripts/live-blocks/src/preprocess/index.js:213:13
(caused by) Error: binary for edge is not available at path /Users/gaga/github/opa/opa_darwin_amd64, ensure it has been built for the current p
latform
    at /Users/gaga/github/opa/docs/website/scripts/live-blocks/src/preprocess/acquireOPAVersion.js:59:15
    at async handleLater (/Users/gaga/github/opa/docs/website/scripts/live-blocks/src/helpers.js:151:13)
ChainedError: example/logical_or/partial_set evaluation failed for an unexpected, possibly internal reason (check for additional logs): binary
for edge is not available at path /Users/gaga/github/opa/opa_darwin_amd64, ensure it has been built for the current platform
    at /Users/gaga/github/opa/docs/website/scripts/live-blocks/src/preprocess/index.js:213:13
(caused by) Error: binary for edge is not available at path /Users/gaga/github/opa/opa_darwin_amd64, ensure it has been built for the current p
latform

Fixed it by simply copy a binary to the expected locale (cp /Users/gaga/github/opa/docs/website/scripts/live-blocks/opa_versions/v0.20.5-darwin /Users/gaga/github/opa/opa_darwin_amd64). Now I can run make docs-serve-local and see the docs at http://localhost:8888.

Does the script has a bug doesn't generate the binary at expected path or I missed something?

I will continue to do step 2 later.

[patrick-east]

Error: binary for edge is not available at path /Users/gaga/github/opa/opa_darwin_amd64, ensure it has been built for the current platform

You'll need to run make build first for it to work. Try:

make build docs-live-blocks-install-deps docs-generate docs-preview-build

For the canonical reference take a look at the netlify make target(s): https://github.com/open-policy-agent/opa/blob/fa5e302fbaaa7ef7a0d38da27534d7095e251dc6/Makefile#L280-L284