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

[stale[bot]]

This issue has been automatically marked as inactive because it has not had any activity in the last 30 days.

[anderseknert]

@charlieegan3 how much of this is relevant for the new docs? Obviously, being able to easily build the docs remains relevant :) But probably not most of the details here. Do we feel this is still needed?

(Also sorry for bumping this 5 years later, @patrick-east 😄)

[stale[bot]]

This issue has been automatically marked as inactive because it has not had any activity in the last 30 days. Although currently inactive, the issue could still be considered and actively worked on in the future. More details about the use-case this issue attempts to address, the value provided by completing it or possible solutions to resolve it would help to prioritize the issue.

[charlieegan3]

Yeah we’re no longer dependent on a specific Hugo binary. All the tools needed are installed with npm. Running the website locally has been much simplified with the new site so I think this can be closed.