search

openziti / ziti-doc

Documentation describing the usage of the Ziti platform.
https://openziti.io
Apache License 2.0
34 stars 40 forks source link

Use Vercel to review PRs #185

Closed dovholuknf closed 1 year ago

dovholuknf commented 1 year ago

vercel looks to support rendering PRs for review. I'd like to be able to put a ziti-doc PR up and have it rendered in vercel for review / comments

qrkourier commented 1 year ago

@dovholuknf Are you interested in Vercel only for reviewing PRs in rendered form, or also as a potential hosting platform for the Docusaurus site? I'm exploring Vercel today and will see if I can get it set up to publish my fork. Initially, there are some errors importing the site with Vercel's Docusaurus 2 plugin that I am analyzing.

dovholuknf commented 1 year ago

good question. No - i don't care WHAT automation is used for PR review I just want any PR opened against the repo to be rendered somewhere/somehow so people can look at and evaluate the changes before pushing into main

qrkourier commented 1 year ago

I too see that is a feature of Vercel. The problems I encountered with my fork are related to Docusaurus importing remote content, and so I think it's best if I go ahead and install the Vercel GitHub app in the openziti/ziti-doc repo. This change does not appear to be intrusive at all to the GitHub Actions or GitHub Pages, and will simply allow my Vercel instance to publish branch main and PRs.

qrkourier commented 1 year ago

For reference, Vercel for GitHub permissions are documented in https://vercel.com/docs/concepts/git/vercel-for-github#repository-permissions

qrkourier commented 1 year ago

I must've misunderstood the build problem I encountered when I linked up Vercel to my fork of ziti-doc because I see the same build error when I link up Vercel to the main repo openziti/ziti-doc. I do not encounter the same error when I do npm install && npm run build locally with Yarn v1.22.19. Vercel is running Yarn 1.22.17.

$ docusaurus build
[INFO] [en] Creating an optimized production build...
[info] [webpackbar] Compiling Client
[info] [webpackbar] Compiling Server
[success] [webpackbar] Client: Compiled with some errors in 38.47s
Module not found: Error: Can't resolve '../../_remotes/ziti-android-app/README.md' in '/vercel/path0/docusaurus/docs-guides/mobile'
[ERROR] Client bundle compiled with errors therefore further build is impossible.
error Command failed with exit code 1.
info Visit https://yarnpkg.com/en/docs/cli/run for documentation about this command.
Error: Command "yarn run build" exited with 1

Full build log from Vercel:

[14:10:44.110] Cloning github.com/openziti/ziti-doc (Branch: main, Commit: 35148af)
[14:10:45.303] Cloning completed: 1.193s
[14:10:45.682] Looking up build cache...
[14:10:45.819] Build Cache not found
[14:10:45.871] Running "vercel build"
[14:10:46.536] Vercel CLI 28.4.9
[14:10:46.917] Warning: Detected "engines": { "node": ">=16.14" } in your `package.json` that will automatically upgrade when a new major Node.js Version is released. Learn More: http://vercel.link/node-version
[14:10:46.920] Installing dependencies...
[14:10:47.358] yarn install v1.22.17
[14:10:47.481] [1/5] Validating package.json...
[14:10:47.484] [2/5] Resolving packages...
[14:10:48.137] [3/5] Fetching packages...
[14:11:07.049] [4/5] Linking dependencies...
[14:11:07.057] warning "@docusaurus/core > react-loadable-ssr-addon-v5-slorber@1.0.1" has unmet peer dependency "react-loadable@*".
[14:11:07.068] warning "@docusaurus/core > react-dev-utils > fork-ts-checker-webpack-plugin@6.5.2" has unmet peer dependency "typescript@>= 2.7".
[14:11:07.083] warning "@docusaurus/preset-classic > @docusaurus/theme-search-algolia > @docsearch/react > @algolia/autocomplete-preset-algolia@1.7.1" has unmet peer dependency "@algolia/client-search@^4.9.1".
[14:11:07.085] warning " > mdx-mermaid@1.3.2" has unmet peer dependency "unist-util-visit@^2.0.0".
[14:11:07.085] warning " > raw-loader@4.0.2" has unmet peer dependency "webpack@^4.0.0 || ^5.0.0".
[14:11:07.121] warning Workspaces can only be enabled in private projects.
[14:11:18.322] [5/5] Building fresh packages...
[14:11:20.616] Done in 33.27s.
[14:11:20.652] Running "yarn run build"
[14:11:20.878] yarn run v1.22.17
[14:11:20.927] $ docusaurus build
[14:11:23.171] [INFO] [en] Creating an optimized production build...
[14:11:24.343] [info] [webpackbar] Compiling Client
[14:11:24.374] [info] [webpackbar] Compiling Server
[14:12:02.813] [success] [webpackbar] Client: Compiled with some errors in 38.47s
[14:12:02.820] 
[14:12:02.820] 
[14:12:02.820] Module not found: Error: Can't resolve '../../_remotes/ziti-android-app/README.md' in '/vercel/path0/docusaurus/docs-guides/mobile'
[14:12:02.820] [ERROR] Client bundle compiled with errors therefore further build is impossible.
[14:12:02.877] error Command failed with exit code 1.
[14:12:02.878] info Visit https://yarnpkg.com/en/docs/cli/run for documentation about this command.
[14:12:02.896] Error: Command "yarn run build" exited with 1
qrkourier commented 1 year ago

I must've misunderstood the build problem I encountered when I linked up Vercel to my fork of ziti-doc because I see the same build error when I link up Vercel to the main repo openziti/ziti-doc. I do not encounter the same error when I do npm install && npm run build locally with Yarn v1.22.19. Vercel is running Yarn 1.22.17.

$ docusaurus build
[INFO] [en] Creating an optimized production build...
[info] [webpackbar] Compiling Client
[info] [webpackbar] Compiling Server
[success] [webpackbar] Client: Compiled with some errors in 38.47s
Module not found: Error: Can't resolve '../../_remotes/ziti-android-app/README.md' in '/vercel/path0/docusaurus/docs-guides/mobile'
[ERROR] Client bundle compiled with errors therefore further build is impossible.
error Command failed with exit code 1.
info Visit https://yarnpkg.com/en/docs/cli/run for documentation about this command.
Error: Command "yarn run build" exited with 1

Full build log from Vercel:

[14:10:44.110] Cloning github.com/openziti/ziti-doc (Branch: main, Commit: 35148af)
[14:10:45.303] Cloning completed: 1.193s
[14:10:45.682] Looking up build cache...
[14:10:45.819] Build Cache not found
[14:10:45.871] Running "vercel build"
[14:10:46.536] Vercel CLI 28.4.9
[14:10:46.917] Warning: Detected "engines": { "node": ">=16.14" } in your `package.json` that will automatically upgrade when a new major Node.js Version is released. Learn More: http://vercel.link/node-version
[14:10:46.920] Installing dependencies...
[14:10:47.358] yarn install v1.22.17
[14:10:47.481] [1/5] Validating package.json...
[14:10:47.484] [2/5] Resolving packages...
[14:10:48.137] [3/5] Fetching packages...
[14:11:07.049] [4/5] Linking dependencies...
[14:11:07.057] warning "@docusaurus/core > react-loadable-ssr-addon-v5-slorber@1.0.1" has unmet peer dependency "react-loadable@*".
[14:11:07.068] warning "@docusaurus/core > react-dev-utils > fork-ts-checker-webpack-plugin@6.5.2" has unmet peer dependency "typescript@>= 2.7".
[14:11:07.083] warning "@docusaurus/preset-classic > @docusaurus/theme-search-algolia > @docsearch/react > @algolia/autocomplete-preset-algolia@1.7.1" has unmet peer dependency "@algolia/client-search@^4.9.1".
[14:11:07.085] warning " > mdx-mermaid@1.3.2" has unmet peer dependency "unist-util-visit@^2.0.0".
[14:11:07.085] warning " > raw-loader@4.0.2" has unmet peer dependency "webpack@^4.0.0 || ^5.0.0".
[14:11:07.121] warning Workspaces can only be enabled in private projects.
[14:11:18.322] [5/5] Building fresh packages...
[14:11:20.616] Done in 33.27s.
[14:11:20.652] Running "yarn run build"
[14:11:20.878] yarn run v1.22.17
[14:11:20.927] $ docusaurus build
[14:11:23.171] [INFO] [en] Creating an optimized production build...
[14:11:24.343] [info] [webpackbar] Compiling Client
[14:11:24.374] [info] [webpackbar] Compiling Server
[14:12:02.813] [success] [webpackbar] Client: Compiled with some errors in 38.47s
[14:12:02.820] 
[14:12:02.820] 
[14:12:02.820] Module not found: Error: Can't resolve '../../_remotes/ziti-android-app/README.md' in '/vercel/path0/docusaurus/docs-guides/mobile'
[14:12:02.820] [ERROR] Client bundle compiled with errors therefore further build is impossible.
[14:12:02.877] error Command failed with exit code 1.
[14:12:02.878] info Visit https://yarnpkg.com/en/docs/cli/run for documentation about this command.
[14:12:02.896] Error: Command "yarn run build" exited with 1
qrkourier commented 1 year ago

The "missing" README.md file does exist in the expected location, and it's definitely organized under the Docusaurus root directory named "docusaurus".

❯ ll ./docusaurus/docs-guides/mobile/../../_remotes/ziti-android-app/README.md 
-rw-r--r-- 1 root root 1.2K Sep 27 13:42 docusaurus/docs-guides/mobile/../../_remotes/ziti-android-app/README.md

❯ readlink -f ./docusaurus/docs-guides/mobile/../../_remotes/ziti-android-app/README.md
/home/kbingham/Sites/netfoundry/github/ziti-doc/docusaurus/_remotes/ziti-android-app/README.md
qrkourier commented 1 year ago

Now I'm able to reproduce the error locally by first deleting /docusaurus/_remotes which is apparently created by some other process and is not tracked in Git. The clue was the files are owned by root on my computer.

❯ yarn run build
yarn run v1.22.19
$ docusaurus build
[INFO] [en] Creating an optimized production build...

✖ Client
  Compiled with some errors in 4.28s

● Server █████████████████████████ building (64%) 1/1 entries 2401/2401 dependencies 755/755 modules 0 active 

Module not found: Error: Can't resolve '../../_remotes/ziti-android-app/README.md' in '/home/kbingham/Sites/netfoundry/github/ziti-doc/docusaurus/docs-guides/mobile'
[ERROR] Client bundle compiled with errors therefore further build is impossible.
error Command failed with exit code 1.
info Visit https://yarnpkg.com/en/docs/cli/run for documentation about this command.
dovholuknf commented 1 year ago

I wondered if we were going to have to stub files like that out at some point. Sounds like maybe it's a yes

qrkourier commented 1 year ago

The problem was that Vercel was running docusaurus build, but our project needs to run that with the wrapper script ../gendoc.sh -d -l in order to fetch the missing remote sites and skip generating linked docs e.g. the C SDK docs with Doxygen.

With that change the Vercel build succeeds, but it was also necessary to change the Docusaurus config to use baseUrl: "/" which is in conflict with the current preview organization of parallel DocFx / and Docusaurus /docusaurus HTTP routes in GitHub pages.

The main branch of my fork with these changes is rendered here: https://qrkourier-ziti-doc.vercel.app/

Whenever a branch is pushed to GitHub then Vercel additionally performs a "preview deployment" of that branch. Here's an example: https://qrkourier-ziti-doc-git-troubleshoot-docusaurus-main-qrkourier.vercel.app/