Skip to content

docs(deployment): match the Coolify quickstart to the panel's actual flow - #274

Merged
jouwdan merged 2 commits into
mainfrom
claude/coolify-deployment-onboarding-kuzjm4
Aug 27, 2026
Merged

docs(deployment): match the Coolify quickstart to the panel's actual flow#274
jouwdan merged 2 commits into
mainfrom
claude/coolify-deployment-onboarding-kuzjm4

Conversation

@jouwdan

@jouwdan jouwdan commented Aug 27, 2026

Copy link
Copy Markdown
Collaborator

Walking the Coolify quickstart against a real panel turned up four places where the page describes something the UI does not do. This fixes those, and renames the scaffold's compose file so the one field the page promises you never have to touch is actually already correct.

Step 3 described a resource type Coolify does not have

New Resource → Docker Compose → Public Repository is now the flow the panel really has: New Resource → Public Git repository, paste the URL, press Check repository, then a field table covering Branch, Build pack → Docker Compose (flagged as the one field on that screen you have to change), Base directory and Compose file, then Continue.

Deploying is likewise on the resource's own Actions, not a bare "press deploy", and the page now says to leave it until the domain and MEITH_IMAGE are both in.

docker-compose.ymldocker-compose.yaml

Coolify's Compose file field is prefilled with /docker-compose.yaml, so the old name meant editing a field both this page and Self-hosting claimed you never had to. The scaffold now writes docker-compose.yaml, and board:eject, the deploy-kit smoke script, the generated create-board.sh and the docs follow the same name.

The meith-dev/template repository still carries the old name and needs regenerating from the scaffold — it is outside this repo, so it is not in this change.

The template route skipped the value step 3 needs

The "Use this template" bullet said to skip straight to step 3, which stepped over the note telling you to collect MEITH_IMAGE from the finished build. It now sends you to the end of step 2 instead, and that note opens by naming the wait: the Actions tab, the Build and push run, and what its Summary prints.

Package visibility is a check, not a chore

A build from a public repository usually publishes a public package already, so "make the package public (it starts private)" sent people to change a setting that was often already right. It now says to check it, and to change it only if it says Private. Same correction in the docs, the scaffolded README and the build workflow's own Summary text, so the three agree.

:latest is the quickstart's choice, and now says why

The page recommended :latest with no reason while the build workflow's Summary told the same operator to prefer the sha — the two disagreed at the moment of pasting. The quickstart now gives the reason: :latest follows main, so installing a plugin later is a push and a Redeploy with nothing on the resource to edit, and the commit-sha value is where to move once the board is settled and you want upgrades only when you choose. The troubleshooting row for a board on a newer version than deployed says the same rather than treating it as a fault.

The Summary and the scaffolded README still lead with the sha, which their own tests require, but neither instructs against the quickstart any more: both print the two values, what each does, and which the quickstart takes.

Validation

pnpm verify passes. The scaffold tree digests moved for Dockerfile, docker-entrypoint.sh, README.md and .github/workflows/build.yml, and apps/web/public/create-board.sh was regenerated with pnpm board-installer:gen.

claude added 2 commits August 27, 2026 13:21
…flow

Step 3 described a resource type Coolify does not have. Follow what the
panel does: Public Git repository, Check repository, Docker Compose as the
build pack, Continue, and Deploy from the resource's own Actions once the
domain and MEITH_IMAGE are in.

Rename the scaffold's compose file to docker-compose.yaml, the path
Coolify's Compose file field already carries, so it stays the field
nobody has to type — the eject kit, the deploy-kit smoke script, the
generated create-board.sh and the docs follow the same name.

The template route no longer jumps straight to step 3: its build starts on
its own and step 3 needs what that build prints. The package-visibility
step now says to check rather than change — a build from a public
repository usually publishes a public package already — in the docs, the
scaffolded README and the build workflow's own Summary.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TVkvGWYwMi96TwzozqYvmy
The quickstart already recommended :latest without a reason, while the
build workflow's Summary told the same operator to prefer the sha — so the
one paragraph and the page they copy from disagreed at the moment of
pasting.

The quickstart now gives the reason: :latest follows main, so installing a
plugin later is a push and a Redeploy with nothing on the resource to edit,
and the commit-sha value is where to move once the board is settled. The
troubleshooting row for a board on a newer version than deployed says the
same thing rather than treating it as a fault.

The Summary and the scaffolded README still lead with the sha, which their
own tests require, but neither instructs against the quickstart any more:
both print the two values, what each does, and which one the quickstart
takes.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01TVkvGWYwMi96TwzozqYvmy
@jouwdan
jouwdan merged commit edd740f into main Aug 27, 2026
15 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants