The quickstart could not work on a clean machine - #9
Open
krlex wants to merge 3 commits into
Open
Conversation
nginx terminates TLS and refuses to start when the certificate it is
configured with is missing. nginx/ssl/ ships empty (just a .gitkeep), and
nothing in the compose path puts anything there, so a clean
git clone && cp .env.example .env && docker compose up -d
left nginx in a restart loop with nothing serving on 80 or 443 -- the whole
stack was up and unreachable. The instructions for producing a certificate
exist, but in README-prod.md, which the quickstart never sends you to.
Generate a self-signed pair on first start when nginx/ssl/ is empty, and
say so loudly in the log. A certificate that is already there is never
touched, so this changes nothing for an operator who supplies a real one.
.env.example pinned 2026.07.0, which predates 0cb32fe. On that image the
node registers as `control` instead of the requested `hybrid`, and the
`default` queue is created as a Kubernetes container group. On Compose
there is no Kubernetes, so project updates fail with
unknown work type kubernetes-incluster-auth
and every job launched afterwards sits in `pending` forever. The env var
asking for a hybrid node was simply ignored.
2026.07.1 is not a fix either: it was published for the backend only, so
pinning it makes the frontend image unresolvable. 2026.07.2-rc1 is the
lowest tag that exists for both images and contains the fix.
Also add FORAIL_TLS_CN for the generated certificate.
Two things the Quick Start asserted were not true on a clean machine. It said every service should report healthy after `docker compose up -d`; nginx could not, because no certificate existed. And it never mentioned that job execution is off by default -- so a reader who followed it exactly got an API and a UI where projects never sync and jobs never leave `pending`, with nothing pointing at why. Say where the UI is and how to log in, describe the self-signed certificate, and document FORAIL_TASK_PRIVILEGED together with the reason it defaults to off.
krlex
force-pushed
the
fix/quickstart-cannot-work-on-a-clean-machine
branch
from
August 20, 2026 17:53
2ce69a1 to
bdc2cac
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Measured by actually running it: fresh clone,
cp .env.example .env, fill in the fourchangemevalues,docker compose up -d. Three things were broken.nginx never started. It terminates TLS,
nginx/ssl/ships empty, and nothing generates a certificate — so it sat in a restart loop and nothing served on 80 or 443. The whole stack was up and unreachable. Instructions for making a certificate exist, but only inREADME-prod.md, which the quickstart never points at. Now a self-signed pair is generated on first start when the directory is empty, with a loud warning; an operator-supplied certificate is never touched.No job could ever run.
.env.examplepinned2026.07.0, which predates 0cb32fe. On that image the node registers ascontrolrather than thehybridthe env var asks for, anddefaultbecomes a Kubernetes container group — on Compose that fails project updates withunknown work type kubernetes-incluster-authand leaves every later job inpendingforever.2026.07.1does not help: it was published for the backend only, so the frontend image does not resolve.2026.07.2-rc1is the lowest tag present for both images that carries the fix.The Quick Start said things that were not true — that every service would report healthy, and nothing at all about job execution being off by default. Both corrected, with
FORAIL_TASK_PRIVILEGEDdocumented next to the reason it is off (H4).Verified
Fresh copy of this branch, empty
nginx/ssl/, only the four secrets filled in:docker compose up -d→ healthyhttps://localhost/http://→ 301)/api/v2/ping/, admin loginnode_type=hybrid, capacity 300controlplaneanddefault, both regular, capacity 300With
FORAIL_TASK_PRIVILEGED=true FORAIL_TASK_CGROUP=host, a project synced from git and a job template ranhello_world.ymltosuccessful.Follow-up, not in this PR
Pinning the quickstart to an
-rc1is a stopgap.2026.07.2should be released properly for both images, and this pin moved to it.