Skip to content

docs(getting-started): add Set Up a Model tutorial for API key and local paths#3502

Merged
dgageot merged 1 commit into
mainfrom
docs/3442-set-up-a-model-tutorial
Jul 7, 2026
Merged

docs(getting-started): add Set Up a Model tutorial for API key and local paths#3502
dgageot merged 1 commit into
mainfrom
docs/3442-set-up-a-model-tutorial

Conversation

@Sayt-0

@Sayt-0 Sayt-0 commented Jul 7, 2026

Copy link
Copy Markdown
Member

Phase 4 (docs tutorial) of #3442, the last remaining phase. Closes #3442.

New getting-started page "Set Up a Model" walking both model-setup paths end to end, linked from the README, the quickstart, the site navigation, and the Phase 1 error messages.

Issue expectation mapping

Phase 4 expectation Implemented by
New getting-started page "Set up a model (API key or local)" walking both paths end to end docs/getting-started/set-up-a-model/index.md: comparison table, Path A (get an API key, store it through a secret source, verify with docker agent doctor, run), Path B (install Docker Model Runner, pull, verify, run), pointer to the docker agent setup wizard, doctor section
Linked from README Install section paragraph and Documentation list
Linked from quickstart Options A/D Note under Option A, sentence under Option D (the two spots issue scenario 8 called out)
Linked from the Phase 1 messages Shared environment.ModelSetupDocsURL constant, appended to RequiredEnvError (model-credential variant), AutoModelFallbackError, and the first_available variant

Changes

File Change
docs/getting-started/set-up-a-model/index.md new page (canonical front matter, nav weight 25 between Installation and Quick Start)
docs/data/nav.yml nav entry
README.md links in install section and documentation list
docs/getting-started/quickstart/index.md Option A note, Option D sentence
docs/community/troubleshooting/index.md prose kept in sync with the new error-message links
pkg/environment/errors.go ModelSetupDocsURL constant, link in RequiredEnvError model variant
pkg/config/auto.go closing link in AutoModelFallbackError
pkg/config/first_available.go closing link in the first_available missing-env error
pkg/{environment,config}/*_test.go assertions that model errors carry the link and non-model errors do not

Message rendering after the change (combined with the Phase 3 wizard line):

No API key? Run a local model instead: docker agent run --model dmr/ai/qwen3 ...
(the model is pulled on first use; `docker model ls` shows models already pulled)
Or run `docker agent setup` to configure a provider or local model interactively.
Step-by-step model setup (API key or local): https://docs.docker.com/ai/docker-agent/getting-started/set-up-a-model/

Validation

Check Result
go build ./... ok
go test ./pkg/environment/ ./cmd/root/ and targeted pkg/config error tests pass
golangci-lint run pkg/environment/ pkg/config/ cmd/root/ 0 issues
markdownlint-cli2 (105 files) 0 errors
scripts/docs-check-canonical.sh (94 pages) ok
lychee offline relative-link check 0 errors
Hugo site build (refLinksErrorLevel: ERROR) ok, page emitted with nav entry

TestURLSource_Read_RejectsLocalAddresses and TestLoadExamples fail identically on a clean main in this environment (sandbox network restrictions, corrupted local DMR blob cache); unrelated to this change.

Issue status once merged

Phase Status
1, actionable errors shipped, #3452
2, docker agent doctor shipped, #3489
3, guided setup wizard shipped, #3499
4, docs tutorial this PR

…cal paths

Phase 4 of #3442. First contact with docker-agent on a machine without
provider credentials had no single page walking from "no API key" to a
working model: the quickstart assumed a model was already usable and the
credential errors pointed at scattered reference pages.

Add a getting-started page "Set Up a Model" covering both paths end to
end: cloud provider (get an API key, store it through a secret source,
verify with doctor, run) and local model (install Docker Model Runner,
pull a model, verify, run), with a comparison table, a pointer to the
docker agent setup wizard, and a doctor section.

Link the page from the README (install section and documentation list),
the quickstart Options A and D, the site navigation, and the Phase 1
error messages: RequiredEnvError (model credential variant),
AutoModelFallbackError, and the first_available variant now end with a
shared environment.ModelSetupDocsURL line. The troubleshooting page
prose is kept in sync.
@Sayt-0 Sayt-0 added the kind/docs Documentation-only changes label Jul 7, 2026
@Sayt-0 Sayt-0 requested a review from a team as a code owner July 7, 2026 10:17
@Sayt-0 Sayt-0 added area/docs Documentation changes kind/docs Documentation-only changes labels Jul 7, 2026
@dgageot dgageot merged commit 4bfc653 into main Jul 7, 2026
18 checks passed
@dgageot dgageot deleted the docs/3442-set-up-a-model-tutorial branch July 7, 2026 11:07
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area/docs Documentation changes kind/docs Documentation-only changes

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat(cli): guide users from "no API key" to a working model (actionable errors, doctor, setup, tutorial)

2 participants