From 04090927f90693e2f2d21a3cdbc91fea403d8b2b Mon Sep 17 00:00:00 2001 From: Karlos <73657806+krls2020@users.noreply.github.com> Date: Fri, 28 Aug 2026 14:01:30 +0200 Subject: [PATCH] =?UTF-8?q?chore(guides):=20update=203=20guide(s)=20?= =?UTF-8?q?=E2=80=94=20choose-runtime-base,=20deployment-lifecycle,=20zero?= =?UTF-8?q?ps-yaml-advanced?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- apps/docs/content/guides/choose-runtime-base.mdx | 4 +++- apps/docs/content/guides/deployment-lifecycle.mdx | 2 +- apps/docs/content/guides/zerops-yaml-advanced.mdx | 7 ++++--- 3 files changed, 8 insertions(+), 5 deletions(-) diff --git a/apps/docs/content/guides/choose-runtime-base.mdx b/apps/docs/content/guides/choose-runtime-base.mdx index 3f028d9f..c181b883 100644 --- a/apps/docs/content/guides/choose-runtime-base.mdx +++ b/apps/docs/content/guides/choose-runtime-base.mdx @@ -3,7 +3,9 @@ title: "Choosing a Runtime Base on Zerops" description: "**Use Alpine** as the default base for all services. Use Ubuntu only when you need system packages not available in Alpine. Use Docker only for pre-built images." --- -**Use Alpine** as the default base for all services. Switch to Ubuntu only for **glibc** needs (musl incompatibility): CGO-enabled Go, glibc-built Python/C-extension wheels, or the **Deno** runtime (no Alpine build). Needing a package is NOT itself a reason — both bases install packages (`sudo apk add` / `sudo apt-get install`). Use Docker only for pre-built images. +The OS is part of the base identifier, never a separate field: `alpine/@` or `ubuntu/@` — the same value in the import `type` and in both `build.base` and `run.base` of zerops.yaml. Always write the prefix: a bare `@` is legacy and resolves differently per file (import → Ubuntu, zerops.yaml → Alpine), and `run.base` rewrites the service OS on every deploy. + +**Prefer Alpine** for standard apps. Switch to Ubuntu only for **glibc** needs (musl incompatibility): CGO-enabled Go, glibc-built Python/C-extension wheels, or the **Deno** runtime (Ubuntu image only). Needing a package is NOT itself a reason — both bases install packages (`sudo apk add` / `sudo apt-get install`). Use Docker only for pre-built images. ## Decision Matrix diff --git a/apps/docs/content/guides/deployment-lifecycle.mdx b/apps/docs/content/guides/deployment-lifecycle.mdx index 149edc73..4393e129 100644 --- a/apps/docs/content/guides/deployment-lifecycle.mdx +++ b/apps/docs/content/guides/deployment-lifecycle.mdx @@ -15,7 +15,7 @@ The build container is **temporary** -- created on demand, destroyed after compl **Step-by-step execution order:** -1. **Container creation** -- base environment from `build.base` + `build.os` (default Alpine) +1. **Container creation** -- base environment from `build.base` (`/@`; the prefix selects Alpine or Ubuntu, a bare value resolves to Alpine) 2. **Source code download** -- from GitHub, GitLab, or zcli push to `/var/www` 3. **Cache restoration** -- cached files moved to `/build/source` (no-clobber, source wins) 4. **prepareCommands** -- install additional tools/packages (skipped if cache valid) diff --git a/apps/docs/content/guides/zerops-yaml-advanced.mdx b/apps/docs/content/guides/zerops-yaml-advanced.mdx index d9b0c704..c499f8ae 100644 --- a/apps/docs/content/guides/zerops-yaml-advanced.mdx +++ b/apps/docs/content/guides/zerops-yaml-advanced.mdx @@ -132,9 +132,10 @@ Configuration is **merged at the section level** -- child values override parent Available runtimes and versions are listed in **Service Stacks (live)** -- injected by `zerops_knowledge` and workflow responses. Some key rules: -- PHP: build `php@X`, run `php-nginx@X` or `php-apache@X` (different bases) -- Deno: REQUIRES `os: ubuntu` (no Alpine build exists). Gleam runs on both Alpine and Ubuntu. -- Static sites: build `nodejs@latest`, run `static` +- The OS is part of the base value — `ubuntu/nodejs@22` or `alpine/nodejs@22` — with no separate `os:` field; use the same prefix in `build.base` and `run.base` (a bare `nodejs@22` resolves to Alpine, and `run.base` rewrites the service OS on deploy) +- PHP: build `/php@X`, run `/php-nginx@X` or `/php-apache@X` (different bases) +- Deno: ships only as `ubuntu/deno@X` (no Alpine image). Gleam runs on both Alpine and Ubuntu. +- Static sites: build `alpine/nodejs@latest`, run `static` - `@latest` = newest stable version ---