From f10cd386fd85386303253287d3e0c5e2a7d52124 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 2 Sep 2026 21:07:32 -0500 Subject: Use the go meta-port instead of a hand-rolled go/gofmt symlink FreeBSD's lang/go is a real meta-port (installs as package name "go") that depends on whichever goNNN is current and installs the go/gofmt symlinks itself, tracked and upgradeable - `pkg install go` replaces both the go125 install and the manual `ln -sf` steps in one command. Verified against a real base image and rebuild: same resulting symlinks, now pkg-owned instead of orphaned files pkg doesn't know about. Docs updated to check for an unversioned meta-port first, falling back to a manual symlink only when a toolchain doesn't have one. Co-Authored-By: Claude Sonnet 5 --- USER_GUIDE.md | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) (limited to 'USER_GUIDE.md') diff --git a/USER_GUIDE.md b/USER_GUIDE.md index 00c0f0e..d81ae5d 100644 --- a/USER_GUIDE.md +++ b/USER_GUIDE.md @@ -236,9 +236,10 @@ this in a hurry - it's more destructive than "undo." is already in FreeBSD base (bmake), so it's never something you need to install separately. Watch for versioned port names - FreeBSD's `go125`, `python312`, etc. install as that literal binary, not a bare - `go`/`python3`; symlink a default into the base image's - `/usr/local/bin` if a Makefile invokes the unversioned name. The build - step also needs real outbound network access from inside the jail + `go`/`python3`. Check for an unversioned meta-port first (`go` itself + is one - see [ZFS layout](#1-zfs-layout)); only symlink a default by + hand if no meta-port exists for what you need. The build step also + needs real outbound network access from inside the jail (module/package downloads) - see the `--ip` note under [Provisioning a new app](#provisioning-a-new-app). - `jail_enable="YES"` in `/etc/rc.conf`: @@ -277,17 +278,16 @@ wants `/dev/null` and `/dev/random`.) Now install whatever your apps' Makefiles actually need to build: ``` -# pkg -c /skiff/base install -y go125 +# pkg -c /skiff/base install -y go ``` -Watch for versioned port names - FreeBSD installs `go125` as literally -`go125`, not `go`, so a Makefile invoking the bare command needs a default -symlinked in: - -``` -# ln -sf go125 /skiff/base/usr/local/bin/go -# ln -sf gofmt125 /skiff/base/usr/local/bin/gofmt -``` +FreeBSD's versioned language ports (`go125`, `python312`, ...) install as +that literal binary name, not a bare `go`/`python3` - a Makefile invoking +the unversioned command needs one. Check for an unversioned meta-port +first: `go` is exactly that - it depends on whichever `goNNN` is current +and installs the `go`/`gofmt` symlinks itself (`pkg install -y go`, not +`go125` directly, is the whole fix). If no meta-port exists for what you +need, symlink a default into `/usr/local/bin` by hand instead. Unmount devfs and snapshot once the image can actually build and run apps: @@ -602,7 +602,7 @@ Carried over from the project's own README, plus what testing surfaced: | `git push` says `Everything up-to-date` but you wanted to retry a failed deploy | The git ref already advanced despite the deploy failing - nothing new to push | New commit (`git commit --allow-empty`), or on the host: `skiff deploy --app --new --ref refs/heads/main` | | `build: \`make\` did not produce ./app` | Your Makefile's default target ran (or was skipped as "up to date") without ultimately leaving a file named `app` in the repo root | Run `make -B` locally in a clean checkout and confirm `./app` exists after; check the target actually named `app` (or a dependency of the default target) writes there | | Health check fails and you're not sure why | - | `jexec sockstat -4 -l` to check for a listener; `jexec ps aux` to see if the process is even running; try `jexec /app/current/app` directly to see startup errors that daemon(8) would otherwise swallow | -| Build fails inside the jail with a missing command (`go: not found`, etc.) even though it's installed on the host | The base jail image itself is missing it, or FreeBSD installed it under a versioned name (`go125`, not `go`) | `jexec which `; if it's there under a versioned name, symlink a default into the base image's `/usr/local/bin`, re-snapshot, and `skiff rebuild --app --base-snapshot ` | +| Build fails inside the jail with a missing command (`go: not found`, etc.) even though it's installed on the host | The base jail image itself is missing it, or FreeBSD installed it under a versioned name (`go125`, not `go`) | `jexec which `; if it's there under a versioned name, check for an unversioned meta-port (`pkg -c /skiff/base install -y go`, not `go125`) before symlinking one by hand; re-snapshot and `skiff rebuild --app --base-snapshot ` either way | | Build fails inside the jail on any network call (module download, `pkg install`), or `pkg`/`fetch`/`go mod` just time out | The app's `--ip` doesn't actually route from this host - classic jails share the host's routing table, but an out-of-subnet address (e.g. `10.0.0.5` on a host whose real subnet is `192.168.1.0/24`) can send packets that silently never get a response behind some NAT/bridged setups | `jexec fetch -T5 -o /dev/null https://` to confirm; if it hangs, re-provision with an `--ip` in the same subnet as the host's own address on `--iface` (see [Provisioning a new app](#provisioning-a-new-app)) | | `skiff domains add` fails with a certbot/ACME error | Most likely DNS isn't pointed at the app's `--ip` yet; less commonly, the app's `--ip` doesn't route outbound from this host (see above) | Fix DNS, then re-run `skiff domains add` with the same hostname - safe to retry, the app stays on plain HTTP in the meantime and nothing is left half-configured | -- cgit v1.3