mirror of
https://github.com/kevinveenbirkenbach/computer-playbook.git
synced 2026-11-06 10:59:59 +00:00
kevinveenbirkenbachandClaude Opus 5.5
f9e25b0387
The update moved the documentation source to v0.165.0 and the builder to hugomods/hugo:exts-0.154.5. That is the newest tag hugomods publishes, and the source of v0.165.0 does not render with it. The image build ended with "can't evaluate field Locale in type *langs.Language" in layouts/baseof.html. The builder is now ghcr.io/gohugoio/hugo, which Hugo publishes for every release, pinned to v0.165.0 like the source. That image runs as an unprivileged user, so the build stage switches to root for the steps that write to /src and /public. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
51 lines
2.4 KiB
Markdown
51 lines
2.4 KiB
Markdown
# Hugo: Administration
|
|
|
|
## Force a rebuild
|
|
|
|
The Hugo site is built into the custom Docker image at `compose build` time. The build is content-keyed via the cloned `services/repository/` tree, so:
|
|
|
|
- **A change in `services.hugo.source_version`** invalidates the clone, which invalidates `COPY ./services/repository/` in the Dockerfile, which triggers a fresh `hugo` build on the next deploy.
|
|
- **A force rebuild** without a source-version change can be triggered by clearing the role's image cache:
|
|
|
|
```bash
|
|
make compose-exec cmd="docker compose -f /opt/docker/web-app-hugo/docker-compose.yml build --no-cache"
|
|
```
|
|
|
|
The next `make compose-deploy mode=update apps=web-app-hugo` will pull the image, restart nginx, and serve the freshly rendered output.
|
|
|
|
## Bumping the source version
|
|
|
|
1. Pick the new tag/commit in the upstream repository (default: [gohugoio/hugoDocs releases](https://github.com/gohugoio/hugoDocs/releases)).
|
|
2. Update `roles/web-app-hugo/meta/services.yml`:
|
|
|
|
```yaml
|
|
hugo:
|
|
source_version: <new-tag>
|
|
```
|
|
|
|
3. Re-deploy:
|
|
|
|
```bash
|
|
make compose-deploy mode=update apps=web-app-hugo
|
|
```
|
|
|
|
4. Verify in the browser that the content reflects the new version.
|
|
|
|
## Debugging a failed Hugo build
|
|
|
|
The Hugo build runs inside `docker compose build`. If `hugo` exits non-zero, the play fails and the previous image keeps serving. To inspect the failure log:
|
|
|
|
```bash
|
|
make compose-exec cmd="docker compose -f /opt/docker/web-app-hugo/docker-compose.yml build --progress=plain --no-cache web-app-hugo 2>&1 | tail -200"
|
|
```
|
|
|
|
Common causes:
|
|
|
|
- **`hugo` reports unknown content / module errors**: the upstream repository moved a directory or a Hugo Module. Pin to a known-good tag in `source_version`.
|
|
- **`hugo` reports template execution errors**: the theme's templates are incompatible with the bundled Hugo binary. Bump `services.hugo.builder_version` (e.g. to a newer `v<version>` tag) or pin the source repo to a tag known to build with the current Hugo.
|
|
- **Module fetch fails (`go.mod` resolution)**: Hugo modules pull from `proxy.golang.org`. Network egress to that host must be allowed by the local firewall / proxy.
|
|
|
|
## Rotating the Hugo binary
|
|
|
|
To upgrade the extended Hugo binary independently of the content repo, edit `services.hugo.builder_version` in `meta/services.yml` (e.g. `v0.166.0`). The change invalidates only the builder layer, not the cloned repo, so the next `compose build` reuses the same content but with the new binary.
|