influxdata / influxdata/docs-v2

Hugo extended binary fails to install in proxied/sandboxed environments

Open
#7,093 0 comments 0 reactions 0 assignees View on GitHub
area:ci
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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.