1. The content repository — your GitLab project. Markdown or typed content tags, images, one pages.config.js, a Dockerfile of a few lines and a three-line CI file. No node_modules, no lock file, no build configuration.
2. The builder image — builder-www for landing pages or builder-docs for knowledge bases. The engine (Astro 7, Starlight for docs, Tailwind 4, the markdown pipeline) with every dependency installed and locked. Your Dockerfile starts FROM it.
3. The pipeline — a shared GitLab CI template. It builds your Dockerfile, pushes the resulting image to your project’s registry and rolls it out to a Kubernetes cluster with a certificate. A push to master is production; any other branch is a preview on its own address.
4. The runtime image — nginx with the serving rules already inside: pre-compressed files, cache headers, clean URLs, a 404 page and an optional password. The build result is copied in; nothing is configured.

FROM node:26-alpine AS dependencies
WORKDIR /src
RUN npm install -g pnpm@10
COPY package.json pnpm-workspace.yaml pnpm-lock.yaml .npmrc ./
COPY packages/markdown-preset/package.json packages/markdown-preset/
COPY apps/docs/package.json apps/docs/
COPY apps/www/package.json apps/www/
RUN pnpm install --frozen-lockfile
COPY . .

# --- docs builder: content repos start FROM this image ---
FROM dependencies AS builder-docs
WORKDIR /src/apps/docs
# smoke-build with fixture content validates the image and warms caches
RUN pnpm run build

# --- www builder: content repos start FROM this image ---
FROM dependencies AS builder-www
WORKDIR /src/apps/www
RUN pnpm run build

# --- runner: content repos COPY their dist into this image ---
FROM nginx:alpine AS nginx-runner
RUN apk add --no-cache openssl
COPY nginx/default.conf.template /etc/nginx/templates/default.conf.template
COPY nginx/docker-entrypoint.d/ /docker-entrypoint.d/

The engine’s CI tags each target with the version from its package.json and moves latest: h.gitt.one/pages/engine-astro/builder-www:0.24.3 and …:latest are the same image today. The image paths are a public contract — they do not move.

The shared preset is a small package in the engine. On top of Astro’s defaults (GitHub-flavored markdown and Shiki) it adds exactly what GitLab does differently from a plain renderer:

// - GitLab links: `page.md` → `/page`, `README.md` → `/`, `assets/…` → `/assets/…`
// - GitLab math: $`…`$ and ```math → server-side SVG (rehype-mathjax, no CSS,
//   no fonts — Lighthouse stays at 100). Plain `$…$` / `$$` are NOT math:
//   GitLab 15.5 prints them literally, so does the site.
// - emoji shortcodes `:rocket:` → 🚀 (remark-emoji, gemoji names = GitLab's)
// - raw HTML: what GitLab's sanitizer removes, the site removes (rehype-gitlab-html)
// - task-list checkboxes get an accessible name (rehype-task-list-labels)
// - alerts `> [!note]` — the forward-compatible admonition syntax

const remarkCommon = [remarkGitlabLinks, remarkGitlabMath, remarkEmoji, remarkAlertMarkerCase];
const rehypeCommon = [[rehypeRaw, { passThrough: MDX_NODES }], rehypeGitlabHtml, rehypeMathjax, rehypeTaskListLabels];

export const docsMarkdownConfig = {
  remarkPlugins: [...remarkCommon, [remarkGithubAdmonitionsToDirectives, { mapping: STARLIGHT_ASIDES }]],
  rehypePlugins: rehypeCommon,
};

The consequences for an author: links between .md files keep working after publishing, README.md is the front page, files under assets/ are downloadable from the site, a heading’s anchor is the same slug GitLab makes, and HTML that GitLab strips — <script>, <iframe>, inline style — is stripped on the site too. The full table of what is identical, what differs and what is unsupported is in the documentation.

include:
  - project: 'commons/ci'
    file: 'simpledeploy-master.yml'
  - project: 'commons/ci'
    file: 'simpledeploy-branch.yml'

version: '3.5'
services:
  router:
    image: h.gitt.one/${CI_PROJECT_PATH}:${CI_COMMIT_SHORT_SHA:-latest}
    build: .
    environment:
      BASIC_AUTH_HTPASSWD: ${BASIC_AUTH_HTPASSWD}
    ports:
      - "80:80"

The compose file is the whole deployment description. image: names where the pipeline pushes the result — the project’s own container registry, tagged with the commit’s short SHA — and build: . points at the Dockerfile above. The shared template, abridged:

build_container:
  stage: build
  script:
    - docker-compose build      # your Dockerfile, FROM the builder image
    - docker-compose push       # → h.gitt.one/<project>:<short sha>
  only: [master, main]

deploy_master:
  stage: deploy
  variables:
    NAMESPACE: master
    VHOST: ${HOST}
  script:
    - /usr/local/bin/simpledeploy
  environment:
    name: master
    url: https://${HOST}
  only: [master, main]

simpledeploy converts the compose file into Kubernetes resources — a Deployment, a Service and an Ingress for HOST with a certificate from Let’s Encrypt — and applies them to the cluster named by K8S_CLUSTER. Kubernetes pulls the new tag and swaps the pod; the previous one keeps serving until the new one is ready. Two things follow from the tag being the commit SHA:

• Re-running an old pipeline does not redeploy. It rebuilds the same tag; a Deployment whose image tag did not change does not roll. A new commit is what rolls the site — including an empty one, when the point is to pick up a newer engine.
• HOST must exist before the first pipeline. Without it the build still succeeds and the image is still pushed, but the deploy starts a pod with no Ingress — and is green about it.

The branch template does the same for every other branch, with the namespace and the host derived from the branch name: pr-pricing on www.example.com becomes pr-pricing.www.example.com, with its own certificate, and a manual undeploy job removes it.

deploy_feature:
  stage: deploy
  variables:
    NAMESPACE: ${CI_COMMIT_REF_SLUG}
  before_script:
    - export VHOST="${CI_COMMIT_REF_SLUG}.${HOST%%,*}"
  script:
    - /usr/local/bin/simpledeploy
  environment:
    name: feature/$CI_COMMIT_REF_SLUG
    url: https://${CI_COMMIT_REF_SLUG}.${HOST}
    on_stop: undeploy
  only: [/^pr-.*/, dev]

server {
    listen 80;
    gzip on;
    gzip_static on;                # serve the .gz twins made by the build

    root /usr/share/nginx/html;
    index index.html;

    # intranet mode: `off` unless BASIC_AUTH_HTPASSWD is set — declared at
    # server level so every location inherits it, /_astro/ included
    auth_basic ${PAGES_AUTH_REALM};
    auth_basic_user_file /etc/nginx/auth.htpasswd;

    error_page 404 /404.html;

    # hashed assets are immutable; html must always be revalidated
    location /_astro/ { add_header Cache-Control "public, max-age=31536000, immutable"; }
    location ~* \.html$ { add_header Cache-Control "public, max-age=0, must-revalidate"; }

    # search index chunks are pre-compressed and hashed; loaders are not
    location ~* /pagefind/.*\.(pf_index|pf_fragment|pf_meta)$ {
      gzip off;
      add_header Cache-Control "public, max-age=31536000, immutable";
    }

    # /page answers directly, as Astro publishes it and as the sitemap says
    location / { try_files $uri $uri/index.html =404; }
}

Four decisions live here. Pre-compressed delivery: the build made .gz files, nginx just picks them. Cache correctness: files under /_astro/ carry a content hash in their name and are cached forever; HTML is revalidated on every request, so a deploy is visible immediately. Clean URLs: /page serves /page/index.html without a redirect, so the canonical address matches the sitemap. Real 404s: an unknown path answers 404 with the site’s own page, not a soft redirect to the front page.

The password is the fifth, and it is decided at container start rather than at build time:

if [ -n "${BASIC_AUTH_HTPASSWD:-}" ]; then
    echo "admin:$(openssl passwd -apr1 "$BASIC_AUTH_HTPASSWD")" > /etc/nginx/auth.htpasswd
    export PAGES_AUTH_REALM='"Restricted"'
else
    export PAGES_AUTH_REALM=off
fi

The CI variable BASIC_AUTH_HTPASSWD reaches the container through the compose file’s environment:. If it is set, the password is hashed on start and the whole site — pages, assets, search index — asks for it; if it is empty, auth_basic off is rendered and the site is public. The same image serves both cases, and the plaintext never lands in an image layer.

1. project — a GitLab project is created in the user’s namespace with the user’s token.
2. template — every file of the landing-page template is committed into it as a copy, not a fork, so the site is not tied to the template. The commit is marked [skip ci]: building the untouched template would be a wasted deploy.
3. configure — HOST and K8S_CLUSTER are set as protected CI variables, the deploy token for the registry is created, dev and pr-* are protected. This happens before any pipeline, because a pipeline that starts without HOST deploys an ingress with an empty host.
4. content — the same agent that later edits the site writes its first version on master from the description. Its commits trigger the first real pipeline. The description and the answer are stored as chat, so the editor opens on a conversation that already happened.
5. dev — the preview branch is created from master, which starts the preview pipeline.
6. ci — the run waits for both pipelines to finish.
7. https — the run requests the site and the preview over a verified TLS connection until both answer 200; before Let’s Encrypt issues the certificate the ingress answers with a self-signed one, which is exactly what verification rejects.

Then the site is activated in the user’s list. A failed run leaves the project in place and says which step stopped and why.