influxdata / influxdata/docs-v2
Hugo extended binary fails to install in proxied/sandboxed environments
- Dominant language
- JavaScript
- Stars
- 82
- Forks
- 326
- Avg merge
- 1d 1h
- Merged PRs (30d)
- 82
Description
## Problem
Fresh `yarn install` in sandboxed environments (Claude Code web sessions, some CI runners) leaves `node_modules/hugo-extended/bin/` empty. Subsequent `npx hugo` calls fail with:
```
⚠ Hugo is missing, reinstalling now...
☁️ Downloading hugo_extended_0.157.0_linux-amd64.tar.gz...
✖ Hugo installation failed. :(
Failed to initialize Hugo: fetch failed
```
## Root cause
The `hugo-extended` npm package's postinstall script (`node_modules/hugo-extended/dist/lib/install.mjs`) uses Node's native `fetch()` (undici) to download the Hugo binary from GitHub releases.
**Node ≤23's built-in `fetch()` does not honor `HTTPS_PROXY` / `HTTP_PROXY` environment variables by default.** Undici requires an explicit `EnvHttpProxyAgent` to be set as the global dispatcher. In environments where outbound traffic must go through a proxy:
- `git clone` / `git push` work (git honors proxy env vars)
- `curl https://github.com/gohugoio/hugo/releases/...` works (curl honors proxy env vars)
- `yarn install` metadata/tarball fetches work (yarn honors proxy env vars)
- `hugo-extended` postinstall **silently times out** on `github.com:443` because it makes raw `fetch()` calls
### Evidence
```
$ node -e "(async () => { const r = await fetch('https://github.com/gohugoio/hugo/releases/download/v0.157.0/hugo_extended_0.157.0_linux-amd64.tar.gz'); })()"
error: fetch failed Connect Timeout Error (attempted address: github.com:443, timeout: 10000ms)
```
vs.
```
$ curl -sL https://github.com/gohugoio/hugo/releases/download/v0.157.0/hugo_extended_0.157.0_linux-amd64.tar.gz -o /tmp/hugo.tar.gz
$ file /tmp/hugo.tar.gz
/tmp/hugo.tar.gz: gzip compressed data, max compression, original size modulo 2^32 57265664
```
## Proposed fix
Add a curl-based fallback in `scripts/setup-local-bin.js` postinstall (or a new `scripts/install-hugo.js`). Priority order:
1. `$HUGO_BIN_PATH` if set and valid → use
2. `hugo` on system PATH → use as-is
3. `node_modules/hugo-extended/bin/hugo` (hugo-extended's own installer succeeded) → use
4. **Fallback:** parse Hugo version from `node_modules/hugo-extended/package.json`, fetch via `curl`:
```sh
curl -sSL --proto '=https' --tlsv1.2 \
"https://github.com/gohugoio/hugo/releases/download/v${VERSION}/hugo_extended_${VERSION}_${OS}-${ARCH}.tar.gz" \
| tar -xz -C node_modules/.bin/ hugo
chmod +x node_modules/.bin/hugo
```
5. Verify SHA-256 checksum against `checksums.txt` from the same release
## Why this is the right fix
- **Works everywhere:** sandbox (via proxy), local dev (direct), CI runners (both). `curl` is universally available.
- **No new npm dependencies.**
- **No Node version requirement change** — `NODE_USE_ENV_PROXY=1` requires Node 24+; repo supports ≥16.
- **Graceful fallthrough:** uses hugo-extended's own binary when it succeeded; only runs curl when needed.
- **Checksum verification** preserves supply-chain integrity.
## Rejected alternatives
- `NODE_USE_ENV_PROXY=1` — Node 24+ only, breaks compatibility floor
- `global-agent` preload — doesn't patch undici's fetch
- `HUGO_BIN_PATH` documentation only — not a fix, just a workaround
- Upstream fix to `hugo-extended` — out of our control, slow to land
## Acceptance criteria
- [ ] Fresh `yarn install` produces a working `npx hugo` in sandboxed environments
- [ ] Fresh `yarn install` still works on macOS/Linux dev machines (regression guard)
- [ ] CI still works
- [ ] Checksum is verified before the binary is used
- [ ] Script is idempotent (running twice doesn't redownload if binary is valid)
## Context
Discovered while working on #7089 in a Claude Code web session, where the sandbox uses an HTTP proxy that node fetch can't reach through.
Contributor guide
No contributing guide indexed for this repository
Research direction
Start by reading scripts/setup-local-bin.js and the hugo-extended package metadata, then reproduce the failure with a fresh yarn install in a proxied or sandboxed environment. Done means npx hugo works there and on macOS/Linux, CI remains functional, checksum verification occurs before use, and repeated setup does not redownload a valid binary.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- javascript, node.js
- Domain
- build-system, tooling
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 65/100