Mention libvips/sharp gotcha in setup instructions

[duijf]

In order to document some stuff about Studio, I wanted to set up dvc.org for local development. I ran into this gotcha, and wanted to mention it in the setup instructions to save others some time.

Gatsby has a dependency on the native libvips library via the sharp NPM package. Sharp by default uses the system libvips if it's available, but that can lead to compatibility problems if there is a version mismatch (or build options are different).

On my system I have libvips installed for something else. This led to the following error when running yarn develop:

ERROR #11321  PLUGIN

"gatsby-plugin-manifest" threw an error while running the onPostBootstrap lifecycle:

Input file contains unsupported image format

[ long stacktrace ]

The fix is to make sharp ignore the system libvips. This needs to be done at dependency install time, as documented in this Gatsby issue: gatsbyjs/gatsby#20698

After removing node_modules and running yarn with this env var, the problem went away.

[duijf]

Link to the changed page on the preview environment: https://dvc-org-clarify-build-i-leauh2.herokuapp.com/doc/user-guide/contributing/docs#development-environment

[rogermparent]

Great catch! I've run into this before as well, it's related to us using old Gatsby packages that have been left behind by more recent versions of libvips. I'd suggest a minor change to the text that makes it read better to me:

⚠️ Do you get an error from gatsby-plugin-manifest about unsupported image
formats? You may be running into
this issue. You can fix it
by reinstalling node_modules with a flag that forces sharp to ignore your
globally installed libvips:

Someone on the docs team might have a different/better suggestion. Other than that, thanks for the contribution!

[duijf]

Thanks for the suggestion @rogermparent! Indeed reads better to me. I've updated the PR :)

[iesahin]

I think it might be better to have a Troubleshooting section header and put this in a bullet list. WDYT @jorgeorpinel ?

[jorgeorpinel]

I've run into this before as well, it's related to us using old Gatsby packages that have been left behind by more recent versions of libvips

So maybe we should make an issue to update Gatsby paks instead @rogermparent ? It's great to be aware of this but documenting it means we don't have a solution.

might be better to have a Troubleshooting section header

@iesahin I think Troubleshooting should be about the products, not about the docs engine.

[jorgeorpinel]

If we must have this, let's keep it very very short 🙂

Suggested change

	> formats? You may be running into
	> [this issue](https://github.com/gatsbyjs/gatsby/issues/20698). You can fix it
	> by reinstalling `node_modules` with a flag that forces `sharp` to ignore your
	> globally installed `libvips`:
	>
	> ```dvc
	> $ rm -r node_modules
	> $ SHARP_IGNORE_GLOBAL_LIBVIPS=true yarn
	> ```
	> formats? You may be running into
	> [this issue](https://github.com/gatsbyjs/gatsby/issues/20698#issuecomment-576353427).

☝️ direct link to the solution

[jorgeorpinel]

In fact I'd move this note after the paragraph below.

[jorgeorpinel]

Hmmmm. There's a strange link checker error too: https://github.com/iterative/dvc.org/pull/2932/checks?check_run_id=3958726103. Do you think that's coming from master @rogermparent ? Thanks

[rogermparent]

So maybe we should make an issue to update Gatsby paks instead @rogermparent ? It's great to be aware of this but documenting it means we don't have a solution.

#2851 (merged shortly after this issue was made) actually did upgrade these packages, so I believe we shouldn't run into this anymore.

Hmmmm. There's a strange link checker error too: https://github.com/iterative/dvc.org/pull/2932/checks?check_run_id=3958726103. Do you think that's coming from master

I'm not sure where it's coming from, usually this happens on massive diffs- it seems the action is having trouble finding merge bases so it's working off of the plain diff from master, which seems to be too big for it to handle (definitely a thing we need to handle when addressing link check in general)

[jorgeorpinel]

#2851 (merged shortly after this issue was made) actually did upgrade these packages, so I believe we shouldn't run into this anymore.

Thanks! @duijf any chance you can try again from scratch with the latest repo? If you don't have the issue again I think we can close the PR.

[duijf]

Tried again from scratch on ad40ef3 and this is indeed no longer an issue 😄

[rogermparent]

Great to hear that it works now!

I'm trying to get a replication of the link-check bug, but can't get one from a new branch even if I clone this one- reopening to hopefully get to the bottom of this.

[rogermparent]

Alright, managed to replicate and solve the issue here. It was indeed fetch-depth.

[jorgeorpinel]

Thanks again for the report @duijf and for looking into this @rogermparent 👍