From eed91f40c8b6df5293292759fe7a6d97fc588009 Mon Sep 17 00:00:00 2001 From: Madraka <8898640+Madraka@users.noreply.github.com> Date: Sun, 8 Nov 2026 01:40:25 +0300 Subject: [PATCH 1/3] ci: Docker image on ghcr.io (#143) deploy/docker: a multi-stage Dockerfile on node:24-bookworm-slim that installs @cloudhal/cli and create-cloudhal from npm (CLOUDHAL_VERSION) or from packed tarballs (edge) with the blog starter's dependencies next to them, non-root, tini, a /data volume, port 8787, a HEALTHCHECK on /api/health and an entrypoint running `cloudhal studio --init-if-empty`; `site-build` writes the public site to /data/dist; compose.yml with an optional Caddy profile (automatic TLS, Studio proxied, the built site served), .env.example and a Caddyfile. .github/workflows/docker.yml: called by release.yml after the npm publish, by workflow_dispatch (a version, or edge) and nightly (edge from the repository's own tarballs, scripts/pack-packages.ts); linux/amd64 + linux/arm64, SBOM, provenance, a build attestation, the smoke test of scripts/docker-smoke.ts and a Trivy gate; a pull request that touches the image builds and tests it without pushing. Dependabot watches the base image and the compose file. docs/guides/self-host.md, README, CONTRIBUTING "Releasing" step 5. Co-Authored-By: Claude Fable 5.1 Signed-off-by: Madraka <8898640+Madraka@users.noreply.github.com> --- .github/dependabot.yml | 7 ++ .github/workflows/docker.yml | 146 ++++++++++++++++++++++++++++++++ .github/workflows/release.yml | 15 ++++ .gitignore | 3 + CONTRIBUTING.md | 1 + README.md | 2 +- apps/docs/src/lib/site-pages.ts | 1 + deploy/docker/.dockerignore | 8 ++ deploy/docker/.env.example | 29 +++++++ deploy/docker/Caddyfile | 19 +++++ deploy/docker/Dockerfile | 51 +++++++++++ deploy/docker/README.md | 19 +++++ deploy/docker/bin/entrypoint | 11 +++ deploy/docker/bin/site-build | 13 +++ deploy/docker/compose.yml | 49 +++++++++++ deploy/docker/install.mjs | 83 ++++++++++++++++++ docs/guides/self-host.md | 116 +++++++++++++++++++++++++ scripts/docker-smoke.ts | 125 +++++++++++++++++++++++++++ scripts/pack-packages.ts | 52 ++++++++++++ 19 files changed, 749 insertions(+), 1 deletion(-) create mode 100644 .github/workflows/docker.yml create mode 100644 deploy/docker/.dockerignore create mode 100644 deploy/docker/.env.example create mode 100644 deploy/docker/Caddyfile create mode 100644 deploy/docker/Dockerfile create mode 100644 deploy/docker/README.md create mode 100755 deploy/docker/bin/entrypoint create mode 100755 deploy/docker/bin/site-build create mode 100644 deploy/docker/compose.yml create mode 100644 deploy/docker/install.mjs create mode 100644 docs/guides/self-host.md create mode 100644 scripts/docker-smoke.ts create mode 100644 scripts/pack-packages.ts diff --git a/.github/dependabot.yml b/.github/dependabot.yml index 68619fe5..c4606424 100644 --- a/.github/dependabot.yml +++ b/.github/dependabot.yml @@ -18,3 +18,10 @@ updates: - package-ecosystem: github-actions directory: / schedule: { interval: weekly } + # The self-host image's base image and the compose file's Caddy (docs/guides/self-host.md). + - package-ecosystem: docker + directory: /deploy/docker + schedule: { interval: weekly } + - package-ecosystem: docker-compose + directory: /deploy/docker + schedule: { interval: weekly } diff --git a/.github/workflows/docker.yml b/.github/workflows/docker.yml new file mode 100644 index 00000000..876188af --- /dev/null +++ b/.github/workflows/docker.yml @@ -0,0 +1,146 @@ +name: Docker image + +# The official self-host image, ghcr.io/cloudhal-dev/cloudhal (issue #143, docs/guides/self-host.md). +# Built from the npm release, never from the tree, so the image is exactly what npm users get: +# - release.yml calls this after a successful npm publish (`workflow_call` with the version): +# tags X.Y.Z, X.Y, latest and sha-; +# - Actions › Docker image › Run workflow with a version re-publishes or backfills it (X.Y.Z, X.Y +# and sha-; `latest` never moves on a dispatch, so a backfill cannot point it at an +# older release); with no version it builds `edge`; +# - nightly, `edge` is built from main's own packed tarballs (scripts/pack-packages.ts): tagged +# edge and sha- only, never latest; +# - a pull request that touches the image builds it for linux/amd64 without pushing and runs the +# same smoke test and scan. +# Every push is linux/amd64 + linux/arm64 with an SBOM, buildx provenance and a GitHub build +# attestation; scripts/docker-smoke.ts then runs the amd64 image (empty volume, health check, the +# first owner through the API, a publish, `site-build`), and Trivy fails the job on a CRITICAL +# vulnerability with a fix. Versions before 0.6.3 have no `--init-if-empty`: the image needs it. + +on: + workflow_call: + inputs: + version: + description: Cloudhal version on npm, x.y.z + type: string + required: true + workflow_dispatch: + inputs: + version: + description: Cloudhal version on npm, x.y.z (empty builds edge from this ref) + type: string + required: false + default: "" + schedule: + - cron: "41 3 * * *" + pull_request: + paths: + - "deploy/docker/**" + - ".github/workflows/docker.yml" + - "scripts/docker-smoke.ts" + - "scripts/pack-packages.ts" + +permissions: {} + +concurrency: + group: docker-${{ github.event_name == 'pull_request' && github.ref || inputs.version || 'edge' }} + cancel-in-progress: ${{ github.event_name == 'pull_request' }} + +env: + IMAGE: ghcr.io/${{ github.repository_owner }}/cloudhal + +jobs: + image: + name: ${{ inputs.version && format('Image {0}', inputs.version) || 'Image edge' }} + runs-on: ubuntu-latest + timeout-minutes: 90 + permissions: + contents: read + packages: write + id-token: write + attestations: write + env: + VERSION: ${{ inputs.version || '' }} + PUSH: ${{ github.event_name != 'pull_request' }} + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0 + with: + node-version: 24 + + # edge: the packages of this ref, built and packed the way the release job packs them + - if: env.VERSION == '' + uses: pnpm/action-setup@ea17c68df8912ef543352723c149a84f56e3d413 # v6.1.0 + - if: env.VERSION == '' + run: pnpm install --frozen-lockfile + - if: env.VERSION == '' + run: node scripts/pack-packages.ts deploy/docker/tarballs + + - if: env.PUSH == 'true' + uses: docker/login-action@8aa5831fb8d48d8f76594c7ddde61ae58019f550 # v4.8.0 + with: + registry: ghcr.io + username: ${{ github.actor }} + password: ${{ secrets.GITHUB_TOKEN }} + - id: meta + uses: docker/metadata-action@dc802804100637a589fabce1cb79ff13a1411302 # v6.2.0 + with: + images: ${{ env.IMAGE }} + flavor: latest=false + tags: | + type=semver,pattern={{version}},value=v${{ env.VERSION }},enable=${{ env.VERSION != '' }} + type=semver,pattern={{major}}.{{minor}},value=v${{ env.VERSION }},enable=${{ env.VERSION != '' }} + type=raw,value=latest,enable=${{ env.VERSION != '' && github.event_name != 'workflow_dispatch' }} + type=raw,value=edge,enable=${{ env.VERSION == '' }} + type=sha,prefix=sha- + labels: | + org.opencontainers.image.title=Cloudhal + org.opencontainers.image.description=Agent-native site platform: Studio, API and MCP server, self-hosted + org.opencontainers.image.documentation=https://github.com/cloudhal-dev/cloudhal/blob/main/docs/guides/self-host.md + org.opencontainers.image.vendor=Cloudhal + org.opencontainers.image.version=${{ env.VERSION || 'edge' }} + - if: env.PUSH == 'true' + uses: docker/setup-qemu-action@99012661954931238ded8c8b007157a8430204e1 # v4.4.0 + - uses: docker/setup-buildx-action@f87e5991a6d7451dcb8d9637bfbc97413f497069 # v4.4.1 + - id: build + uses: docker/build-push-action@c3c9e263c25d99ce0380d002d59b67737d91b0dc # v7.4.0 + with: + context: deploy/docker + platforms: ${{ env.PUSH == 'true' && 'linux/amd64,linux/arm64' || 'linux/amd64' }} + push: ${{ env.PUSH == 'true' }} + load: ${{ env.PUSH != 'true' }} + tags: ${{ steps.meta.outputs.tags }} + labels: ${{ steps.meta.outputs.labels }} + build-args: CLOUDHAL_VERSION=${{ env.VERSION }} + cache-from: type=gha + cache-to: type=gha,mode=max + # attestations need a registry push; a loaded local image takes none + sbom: ${{ env.PUSH == 'true' }} + provenance: ${{ env.PUSH == 'true' && 'mode=max' || 'false' }} + - if: env.PUSH == 'true' + uses: actions/attest-build-provenance@4d101475d8b20a2381f78447822ac1eab6504dd8 # v4.2.2 + with: + subject-name: ${{ env.IMAGE }} + subject-digest: ${{ steps.build.outputs.digest }} + push-to-registry: true + + - id: ref + run: | + if [ "$PUSH" = "true" ]; then echo "image=$IMAGE@$DIGEST" >> "$GITHUB_OUTPUT" + else echo "image=$FIRST_TAG" >> "$GITHUB_OUTPUT"; fi + env: + DIGEST: ${{ steps.build.outputs.digest }} + FIRST_TAG: ${{ fromJSON(steps.meta.outputs.json).tags[0] }} + - name: Smoke test (linux/amd64) + run: node scripts/docker-smoke.ts --image "$SMOKE_IMAGE" + env: + SMOKE_IMAGE: ${{ steps.ref.outputs.image }} + - name: Trivy scan + uses: aquasecurity/trivy-action@ed142fd0673e97e23eac54620cfb913e5ce36c25 # v0.36.0 + with: + image-ref: ${{ steps.ref.outputs.image }} + severity: CRITICAL + ignore-unfixed: true + exit-code: "1" + format: table diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 2003e472..2a572bd0 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -9,6 +9,8 @@ name: Release # npm trusted publishing (OIDC, provenance), and creates one `v` tag and GitHub Release. # 4. `template`: after publishing, template-sync.yml opens or updates the cloudhal-template PR # (the Deploy to Cloudflare button's repository; CONTRIBUTING.md "Releasing"). +# 5. `docker`: after publishing, docker.yml builds the self-host image from the npm release and +# pushes ghcr.io/cloudhal-dev/cloudhal:, : and :latest (issue #143). # npm's trusted-publisher entry for each package names this file and the `npm-publish` # environment: renaming either breaks publishing. @@ -110,4 +112,17 @@ jobs: version: ${{ needs.plan.outputs.version }} secrets: TEMPLATE_SYNC_APP_PRIVATE_KEY: ${{ secrets.TEMPLATE_SYNC_APP_PRIVATE_KEY }} + + docker: + name: Docker image ${{ needs.plan.outputs.version }} + needs: [plan, publish] + if: needs.publish.result == 'success' + permissions: + contents: read + packages: write + id-token: write + attestations: write + uses: ./.github/workflows/docker.yml + with: + version: ${{ needs.plan.outputs.version }} # crates.io publishing is added once cloudhal-schema reaches 0.1 (see docs/adr/0006). diff --git a/.gitignore b/.gitignore index 1b41aa15..72e91414 100644 --- a/.gitignore +++ b/.gitignore @@ -32,3 +32,6 @@ starters/**/*.cloudhal # Translation exchange files (`pnpm i18n:export`, ADR-0034) .i18n/ + +# Packed tarballs for the edge Docker image (scripts/pack-packages.ts) +deploy/docker/tarballs/ diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5fba5b80..cb9b2f44 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -54,6 +54,7 @@ All publishable packages (`@cloudhal/*` and `create-cloudhal`) share one version - **cloudhal-template** (the Deploy to Cloudflare button): the workflow's `template` job (`.github/workflows/template-sync.yml`) opens `chore: Cloudhal X.Y.Z and the X.Y.Z starter theme` from `cloudhal/vX.Y.Z`, with `src/`, `public/`, `astro.config.mjs` and `tsconfig.json` from the published starter, `@cloudhal/*` at `^X.Y.Z` and a lockfile that installs exactly `X.Y.Z`. Merge it once its `cloudhal/template-check` status is green: the same run installs a copy of the synced template with `npm ci` and runs `cloudhal deploy --dry-run` with `WORKERS_CI=1`. To sync again, run Actions › Template sync › Run workflow. Without the `TEMPLATE_SYNC_APP_CLIENT_ID` variable and the `TEMPLATE_SYNC_APP_PRIVATE_KEY` secret (a GitHub App installed on cloudhal-template only, with Contents, Pull requests and Commit statuses write) the job only logs a notice; Dependabot's `@cloudhal/*` PR on the template is the fallback, and it brings dependencies only, no theme. - **cloudhal.com**: Dependabot opens the `@cloudhal/*` PR the next morning (06:00 Europe/Istanbul). A patch release merges itself after its check; a minor bump waits for a person. - **try.cloudhal.com** (`cloudhal-dev/try`): by hand. Bump its exact `@cloudhal/*` pins, then `pnpm install` and `pnpm run deploy`. + - **The Docker image** (`ghcr.io/cloudhal-dev/cloudhal`, [self-host guide](docs/guides/self-host.md)): the workflow's `docker` job (`.github/workflows/docker.yml`) builds it from the npm release and pushes `X.Y.Z`, `X.Y` and `latest` for linux/amd64 and linux/arm64, with an SBOM, provenance and a smoke test. The image never carries a version of its own: one release, one version everywhere. To rebuild a version (a base-image fix) run Actions › Docker image › Run workflow with it; that re-tags `X.Y.Z` and `X.Y` and leaves `latest` alone. `edge` is built nightly from `main`. **If something fails:** use **Re-run failed jobs** on the failed run. The script skips packages npm already has and an existing tag or release, so it finishes a half-done release. A new run (Actions › Release › Run workflow) does not: once npm has every package, `plan` skips `publish`, so a missing tag or GitHub Release stays missing. To redo only the template PR, run Actions › Template sync › Run workflow. npm's trusted-publisher entry for each package names `release.yml` and the `npm-publish` environment: renaming either breaks publishing. diff --git a/README.md b/README.md index f377b044..3cb4ae9a 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ Blogs and newsrooms first; documentation sites and research or data documentatio - **Safe change loop** — Intent → Agent → Snapshot → Diff → Preview → Approve → Publish → Rollback. - **Policy-first** — humans and agents are the same kind of actor; the policy engine checks every tool call against scopes, not the skill's good intentions. - **MCP-native** — the agent surface is a Model Context Protocol server (spec 2026-07-28), usable from Claude, Cursor, Codex or any MCP client. -- **Self-hostable, Cloudflare-ready** — runs offline on SQLite + filesystem; deploys to Cloudflare Workers/D1/R2 with the same storage interface. +- **Self-hostable, Cloudflare-ready** — runs offline on SQLite + filesystem; deploys to Cloudflare Workers/D1/R2 with the same storage interface. On your own server: the official image `ghcr.io/cloudhal-dev/cloudhal` (Studio, API and MCP in one container, your data on one volume, `docker compose up`); see the [self-host guide](docs/guides/self-host.md). - **Analytics without cookies** — page views, sources, countries, devices and Core Web Vitals from one first-party script, in Studio, in each article's editor and for agents (read-only MCP tools). No personal data by default; see the [privacy guide for site owners](docs/guides/analytics-privacy.md). - **Reader comments, moderated** — first-party comments on articles: a plain form that works without JavaScript, a cookie-less proof of work instead of a CAPTCHA (Cloudflare Turnstile optional), every guest comment held for a person, agents that label and hide but never approve, erasure and DSA reports built in. Comments live in your database, outside snapshots. Off for each site until you turn them on; see the [guide for site owners](docs/guides/comments.md). - **Schedules** — publish later as releases that pin the exact versions a person approved; embargoes and expiries the site enforces on every request, with no scheduler needed; one every-minute tick on Cloudflare (cron, or a Durable Object alarm when no cron slot is free) and on Node; built-in checks and scheduled agent tasks with their own keys, run windows, budgets and a taint rule. No language model runs inside Cloudhal; see the [schedules guide](docs/guides/schedules.md). diff --git a/apps/docs/src/lib/site-pages.ts b/apps/docs/src/lib/site-pages.ts index fee7e7e3..a3d50474 100644 --- a/apps/docs/src/lib/site-pages.ts +++ b/apps/docs/src/lib/site-pages.ts @@ -75,6 +75,7 @@ const docsIndex: SitePage = { - [Installation](/docs/start/installation): Node 24, npm, pnpm, Yarn or Bun. - [Quickstart](/docs/start/quickstart): create a site, open Studio, connect an agent, publish, deploy. - [Deploy to Cloudflare with one click](/docs/guides/deploy-button), with nothing installed. +- [Self-host with Docker](/docs/guides/self-host): the official image, compose, a reverse proxy, upgrades and backups. ## Agents diff --git a/deploy/docker/.dockerignore b/deploy/docker/.dockerignore new file mode 100644 index 00000000..c33805ba --- /dev/null +++ b/deploy/docker/.dockerignore @@ -0,0 +1,8 @@ +# The build context is this folder: the installer, the entrypoint scripts and, for edge builds, +# the packed tarballs. Nothing else is needed in the image. +README.md +compose.yml +Caddyfile +.env.example +.env +.DS_Store diff --git a/deploy/docker/.env.example b/deploy/docker/.env.example new file mode 100644 index 00000000..4e334718 --- /dev/null +++ b/deploy/docker/.env.example @@ -0,0 +1,29 @@ +# Copy to .env next to compose.yml. No secrets live here: Better Auth's secret is created on the +# volume at first start (/data/.cloudhal/auth-secret), and invites are printed to the logs. + +# The image tag. `latest` follows every release; pin the minor (`0.6`) in production. +CLOUDHAL_TAG=latest + +# Where Studio is reached. Without a reverse proxy: this machine. Behind one (the caddy profile): +# the public https origin, and CLOUDHAL_BEHIND_PROXY=1 so the proxy's X-Forwarded-* headers count. +CLOUDHAL_BASE_URL=http://localhost:8787 +CLOUDHAL_BEHIND_PROXY=0 +# Which address and port of this machine publish the container's port 8787 (0.0.0.0 to expose it +# directly; keep 127.0.0.1 with the caddy profile). +CLOUDHAL_BIND=127.0.0.1 +CLOUDHAL_PORT=8787 + +# The public site, served by Caddy from `site-build`'s output (caddy profile only). +CLOUDHAL_SITE_URL=https://www.example.com + +# The first start on an empty volume creates a project from this starter with this site name. +CLOUDHAL_INIT=blog +CLOUDHAL_SITE_NAME=My site + +# Scheduled automations (`off` stops them; releases and gates go on). +CLOUDHAL_AUTOMATIONS=on +# Extra origins the API accepts browser requests from, comma-separated (normally empty). +CLOUDHAL_TRUSTED_ORIGINS= +# Workers AI over REST for Build chat (RFC-0016): both or neither. +CLOUDHAL_AI_TOKEN= +CLOUDFLARE_ACCOUNT_ID= diff --git a/deploy/docker/Caddyfile b/deploy/docker/Caddyfile new file mode 100644 index 00000000..14ca2920 --- /dev/null +++ b/deploy/docker/Caddyfile @@ -0,0 +1,19 @@ +# Caddy for the compose file's `caddy` profile: automatic TLS for both hosts (the DNS of each must +# point at this machine, ports 80 and 443 open). Studio and the API at CLOUDHAL_BASE_URL, proxied +# with X-Forwarded-Proto/Host (set CLOUDHAL_BEHIND_PROXY=1); the public site, as `site-build` +# wrote it, at CLOUDHAL_SITE_URL. +{$CLOUDHAL_BASE_URL} { + reverse_proxy cloudhal:8787 +} + +{$CLOUDHAL_SITE_URL} { + root * /srv/cloudhal/dist + encode zstd gzip + try_files {path} {path}/ {path}.html + file_server + handle_errors { + @notfound expression {err.status_code} == 404 + rewrite @notfound /404.html + file_server + } +} diff --git a/deploy/docker/Dockerfile b/deploy/docker/Dockerfile new file mode 100644 index 00000000..324c944a --- /dev/null +++ b/deploy/docker/Dockerfile @@ -0,0 +1,51 @@ +# The official self-host image (docs/guides/self-host.md, issue #143): `cloudhal studio` — the API, +# the Studio UI and the MCP endpoint — on Node, with SQLite and the project's files on the /data +# volume. Built from the npm release (`CLOUDHAL_VERSION=x.y.z`), or from packed tarballs in +# `tarballs/` next to this file for the nightly `edge` tag (.github/workflows/docker.yml). +# +# docker build --build-arg CLOUDHAL_VERSION=0.6.2 -t cloudhal:local deploy/docker +# docker run --rm -p 127.0.0.1:8787:8787 -v cloudhal-data:/data cloudhal:local +# +# No compiler is installed: better-sqlite3 comes as a prebuilt binary for linux/amd64 and +# linux/arm64. The public site is `cloudhal build` output (`site-build` in the container) that a +# web server such as the compose file's Caddy serves from the same volume. + +FROM node:24-bookworm-slim AS build +ARG CLOUDHAL_VERSION="" +COPY . /ctx +RUN node /ctx/install.mjs /ctx /opt/cloudhal \ + && npm cache clean --force \ + && rm -rf /root/.npm /tmp/* + +FROM node:24-bookworm-slim +ARG CLOUDHAL_VERSION="" +LABEL org.opencontainers.image.title="Cloudhal" \ + org.opencontainers.image.description="Agent-native site platform: Studio, API and MCP server, self-hosted" \ + org.opencontainers.image.source="https://github.com/cloudhal-dev/cloudhal" \ + org.opencontainers.image.documentation="https://github.com/cloudhal-dev/cloudhal/blob/main/docs/guides/self-host.md" \ + org.opencontainers.image.url="https://cloudhal.dev" \ + org.opencontainers.image.vendor="Cloudhal" \ + org.opencontainers.image.licenses="Apache-2.0" \ + org.opencontainers.image.version="${CLOUDHAL_VERSION}" +# tini reaps and forwards signals as PID 1; certificates for Workers AI (REST) and media imports. +RUN apt-get update \ + && apt-get install -y --no-install-recommends tini ca-certificates \ + && rm -rf /var/lib/apt/lists/* \ + && mkdir -p /data && chown node:node /data +COPY --from=build --chown=node:node /opt/cloudhal /opt/cloudhal +COPY --chown=node:node bin/ /opt/cloudhal/bin/ +ENV NODE_ENV=production \ + PATH="/opt/cloudhal/bin:/opt/cloudhal/node_modules/.bin:${PATH}" \ + CLOUDHAL_HOST=0.0.0.0 \ + CLOUDHAL_INIT=blog \ + CLOUDHAL_SITE_NAME="My site" +USER node +WORKDIR /data +VOLUME ["/data"] +EXPOSE 8787 +# /api/health is public and answers once the store is open and migrated; the first start on an +# empty volume scaffolds the project first, hence the start period. +HEALTHCHECK --interval=30s --timeout=5s --start-period=90s --retries=3 \ + CMD ["node", "-e", "fetch('http://127.0.0.1:8787/api/health').then(r=>process.exit(r.ok?0:1),()=>process.exit(1))"] +ENTRYPOINT ["tini", "--", "/opt/cloudhal/bin/entrypoint"] +CMD ["studio"] diff --git a/deploy/docker/README.md b/deploy/docker/README.md new file mode 100644 index 00000000..092f7d1c --- /dev/null +++ b/deploy/docker/README.md @@ -0,0 +1,19 @@ +# Cloudhal in Docker + +The official self-host image, `ghcr.io/cloudhal-dev/cloudhal`, built from each npm release (issue #143). The guide is [docs/guides/self-host.md](../../docs/guides/self-host.md); this folder holds what it refers to: + +- `Dockerfile` — `node:24-bookworm-slim`, `@cloudhal/cli` installed with npm (`CLOUDHAL_VERSION`), the blog starter's dependencies next to it, non-root, `/data` volume, port 8787, a health check on `/api/health`. `install.mjs` is its build stage. +- `bin/entrypoint` — `cloudhal studio --init-if-empty` in `/data`; `bin/site-build` — the public site as static HTML into `/data/dist`. +- `compose.yml`, `.env.example`, `Caddyfile` — Studio alone, or with Caddy (profile `caddy`) serving Studio and the built site with automatic TLS. + +Build it yourself from a release, or from this checkout's packages (`edge`): + +```bash +docker build --build-arg CLOUDHAL_VERSION=0.6.3 -t cloudhal:local deploy/docker +``` + +```bash +node scripts/pack-packages.ts deploy/docker/tarballs && docker build -t cloudhal:local deploy/docker +``` + +`node scripts/docker-smoke.ts --image cloudhal:local` runs what CI runs after every build (`.github/workflows/docker.yml`). diff --git a/deploy/docker/bin/entrypoint b/deploy/docker/bin/entrypoint new file mode 100755 index 00000000..e81b920e --- /dev/null +++ b/deploy/docker/bin/entrypoint @@ -0,0 +1,11 @@ +#!/bin/sh +# The image's entrypoint: `studio` (the default command) runs `cloudhal studio` in /data and +# scaffolds the project first when the volume is empty; anything else runs as given, so +# `docker run … cloudhal export` or `docker compose exec cloudhal site-build` work too. +set -eu +cd /data +if [ "${1:-studio}" = "studio" ]; then + [ $# -gt 0 ] && shift + exec cloudhal studio --init-if-empty "$@" +fi +exec "$@" diff --git a/deploy/docker/bin/site-build b/deploy/docker/bin/site-build new file mode 100755 index 00000000..4bf97f7a --- /dev/null +++ b/deploy/docker/bin/site-build @@ -0,0 +1,13 @@ +#!/bin/sh +# Builds the public site: static HTML from the published snapshot into /data/dist, which a web +# server (the compose file's Caddy) serves. The project's dependencies are the image's +# node_modules, linked into the project on first use, so no install and no network is needed. +# docker compose exec cloudhal site-build +set -eu +cd /data +if [ ! -f cloudhal.json ]; then + echo "site-build: no project in /data yet; start the container once first" >&2 + exit 1 +fi +[ -e node_modules ] || ln -s /opt/cloudhal/node_modules node_modules +exec cloudhal build "$@" diff --git a/deploy/docker/compose.yml b/deploy/docker/compose.yml new file mode 100644 index 00000000..c0596046 --- /dev/null +++ b/deploy/docker/compose.yml @@ -0,0 +1,49 @@ +# Cloudhal self-hosted (docs/guides/self-host.md): Studio, the API and the MCP endpoint in one +# container, every file on the `cloudhal-data` volume. Copy .env.example to .env, then +# docker compose up -d Studio on http://localhost:8787 +# docker compose --profile caddy up -d + Caddy with automatic TLS for CLOUDHAL_BASE_URL +# (Studio) and CLOUDHAL_SITE_URL (the built site) +services: + cloudhal: + image: ghcr.io/cloudhal-dev/cloudhal:${CLOUDHAL_TAG:-latest} + restart: unless-stopped + # Bound to this machine unless CLOUDHAL_BIND says otherwise; with the caddy profile the proxy + # is the way in. + ports: + - "${CLOUDHAL_BIND:-127.0.0.1}:${CLOUDHAL_PORT:-8787}:8787" + environment: + CLOUDHAL_BASE_URL: ${CLOUDHAL_BASE_URL:-http://localhost:8787} + CLOUDHAL_BEHIND_PROXY: ${CLOUDHAL_BEHIND_PROXY:-0} + CLOUDHAL_INIT: ${CLOUDHAL_INIT:-blog} + CLOUDHAL_SITE_NAME: ${CLOUDHAL_SITE_NAME:-My site} + CLOUDHAL_AUTOMATIONS: ${CLOUDHAL_AUTOMATIONS:-on} + CLOUDHAL_TRUSTED_ORIGINS: ${CLOUDHAL_TRUSTED_ORIGINS:-} + CLOUDHAL_AI_TOKEN: ${CLOUDHAL_AI_TOKEN:-} + CLOUDFLARE_ACCOUNT_ID: ${CLOUDFLARE_ACCOUNT_ID:-} + volumes: + - cloudhal-data:/data + + caddy: + profiles: [caddy] + image: caddy:2.11 + restart: unless-stopped + depends_on: + - cloudhal + ports: + - "80:80" + - "443:443" + - "443:443/udp" + environment: + CLOUDHAL_BASE_URL: ${CLOUDHAL_BASE_URL:?set CLOUDHAL_BASE_URL in .env} + CLOUDHAL_SITE_URL: ${CLOUDHAL_SITE_URL:?set CLOUDHAL_SITE_URL in .env} + volumes: + - ./Caddyfile:/etc/caddy/Caddyfile:ro + # the built site (`site-build` writes /data/dist), read-only + - cloudhal-data:/srv/cloudhal:ro + - caddy-data:/data + - caddy-config:/config + +volumes: + cloudhal-data: + caddy-data: + caddy-config: diff --git a/deploy/docker/install.mjs b/deploy/docker/install.mjs new file mode 100644 index 00000000..11aa5030 --- /dev/null +++ b/deploy/docker/install.mjs @@ -0,0 +1,83 @@ +/** + * The image's build stage (Dockerfile): installs `@cloudhal/cli` and `create-cloudhal` with plain + * npm, then the blog starter's own dependencies next to them, so a project scaffolded on the + * volume can run `cloudhal build` with the image's node_modules (no install at run time, no + * network). Two sources: + * + * - a release: `CLOUDHAL_VERSION=x.y.z` in the environment, every package from the npm registry; + * - edge: `/tarballs/index.json` (written by scripts/pack-packages.ts) naming a packed + * tarball per package; direct dependencies point at them and `overrides` catch the rest, as + * scripts/smoke-pack.ts installs them. + * + * node install.mjs + */ +import { execFileSync } from "node:child_process"; +import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"; +import path from "node:path"; + +const [ctx = "/ctx", target = "/opt/cloudhal"] = process.argv.slice(2); +const version = process.env.CLOUDHAL_VERSION?.trim() || undefined; +const index = path.join(ctx, "tarballs", "index.json"); + +/** Package name → npm spec for every `@cloudhal/*` package and create-cloudhal. */ +function specs() { + if (existsSync(index)) { + const files = JSON.parse(readFileSync(index, "utf8")); + return Object.fromEntries( + Object.entries(files).map(([name, file]) => [ + name, + `file:${path.join(ctx, "tarballs", String(file))}`, + ]), + ); + } + if (!version) + throw new Error("set CLOUDHAL_VERSION (an npm version) or provide tarballs/index.json"); + return { "@cloudhal/cli": version, "create-cloudhal": version }; +} + +/** Dependencies as given, with `overrides` for the packages not among them (npm forbids both). */ +function manifest(dependencies, all) { + const overrides = Object.fromEntries( + Object.entries(all).filter(([name]) => !(name in dependencies)), + ); + return { + name: "cloudhal-image", + private: true, + dependencies, + ...(Object.keys(overrides).length ? { overrides } : {}), + }; +} + +function install(dir, pkg) { + mkdirSync(dir, { recursive: true }); + writeFileSync(path.join(dir, "package.json"), `${JSON.stringify(pkg, null, 2)}\n`); + execFileSync("npm", ["install", "--omit=dev", "--no-audit", "--no-fund", "--loglevel=error"], { + cwd: dir, + stdio: "inherit", + }); +} + +const all = specs(); +// 1. the CLI (and create-cloudhal, so `npm create cloudhal` works inside the container too) +const cli = { "@cloudhal/cli": all["@cloudhal/cli"], "create-cloudhal": all["create-cloudhal"] }; +install(target, manifest(cli, all)); + +// 2. the blog starter's runtime dependencies (the CLI itself and the Cloudflare adapter left out: +// the CLI is already here, and deploying to Cloudflare is not the container's job) +const starter = JSON.parse( + readFileSync( + path.join(target, "node_modules/@cloudhal/cli/dist/assets/starters/blog/package.json"), + "utf8", + ), +); +const site = {}; +for (const [name, range] of Object.entries(starter.dependencies ?? {})) { + if (name === "@cloudhal/cli" || name === "@astrojs/cloudflare") continue; + site[name] = all[name] ?? range; +} +install(target, manifest({ ...cli, ...site }, all)); + +const installed = JSON.parse( + readFileSync(path.join(target, "node_modules/@cloudhal/cli/package.json"), "utf8"), +); +console.log(`installed @cloudhal/cli ${installed.version} with ${Object.keys(site).join(", ")}`); diff --git a/docs/guides/self-host.md b/docs/guides/self-host.md new file mode 100644 index 00000000..cec461e5 --- /dev/null +++ b/docs/guides/self-host.md @@ -0,0 +1,116 @@ +# Self-host with Docker: a guide for operators + +Cloudhal runs on your own server from one container: `ghcr.io/cloudhal-dev/cloudhal` holds the `cloudhal` CLI as npm publishes it, and `cloudhal studio` inside it serves the Studio UI, the REST API that Studio and the CLI use, and the MCP endpoint agents connect to. Everything the installation owns — the project (`cloudhal.json`, the starter theme), its SQLite database, media and the built site — lives on one volume mounted at `/data`. The image is built from each npm release, for `linux/amd64` and `linux/arm64`, by [`.github/workflows/docker.yml`](https://github.com/cloudhal-dev/cloudhal/blob/main/.github/workflows/docker.yml); its files are in [`deploy/docker/`](https://github.com/cloudhal-dev/cloudhal/tree/main/deploy/docker). + +Cloudflare is still the deployment Cloudhal is built for ([quickstart](../start/quickstart.md), [one-click deploy](deploy-button.md)): there the site renders on demand from D1 and R2 and publishing needs no rebuild. Self-hosting is for people who want their data on their own machine; its site is static HTML that a web server serves (see [the public site](#the-public-site)). + +## Requirements + +- A server with Docker Engine 24 or later and the compose plugin (`docker compose`), 1 GB of memory, a few GB of disk. +- For Studio beyond `localhost`: a DNS name pointing at the server, and either the compose file's Caddy (ports 80 and 443 open; it fetches TLS certificates itself) or a reverse proxy of your own. + +## Quick start + +```bash +mkdir cloudhal && cd cloudhal +curl -fsSLO https://raw.githubusercontent.com/cloudhal-dev/cloudhal/main/deploy/docker/compose.yml +curl -fsSL https://raw.githubusercontent.com/cloudhal-dev/cloudhal/main/deploy/docker/.env.example -o .env +docker compose up -d +``` + +Open http://localhost:8787. The first start on the empty volume creates a project from the blog starter (`CLOUDHAL_INIT`, named after `CLOUDHAL_SITE_NAME`) and runs the migrations; the first account that signs up is the Owner, after which sign-up closes and everyone else joins by invite. Invites and password-reset links are printed to the container's logs (`docker compose logs cloudhal`), not sent: mail is a follow-up for self-hosting. + +Agents connect to the MCP endpoint at `/mcp` with an agent key made in Studio, as for a Cloudflare deployment ([connect an agent](../agents/clients.md)). + +## Beyond localhost: a public origin + +Studio's sign-in cookies and the API's origin checks are tied to the URL browsers use, so once Studio is reached through a DNS name, tell the container: + +| Variable | What it does | +| --- | --- | +| `CLOUDHAL_BASE_URL` | The public origin, e.g. `https://studio.example.com`: Better Auth's base URL (its cookies become `Secure`), a trusted origin for the API, and the URL the log prints. Origin only, no path. | +| `CLOUDHAL_BEHIND_PROXY` | `1` when a reverse proxy terminates TLS in front of the container: each request's scheme and host are then taken from the proxy's `X-Forwarded-Proto` / `X-Forwarded-Host`. Set it only when the proxy is the only way in, since the headers are then trusted. | +| `CLOUDHAL_HOST` | The address the server binds inside the container; the image sets `0.0.0.0`. | + +With the compose file's **`caddy` profile** both are handled for you: set `CLOUDHAL_BASE_URL` (Studio) and `CLOUDHAL_SITE_URL` (the public site) in `.env`, `CLOUDHAL_BEHIND_PROXY=1`, keep `CLOUDHAL_BIND=127.0.0.1`, point both names at the server and run + +```bash +docker compose --profile caddy up -d +``` + +Caddy obtains and renews certificates for both hosts, proxies the Studio host to the container with the forwarded headers, and serves the built site for the site host. + +With a **reverse proxy of your own** (nginx, Traefik, a cloud load balancer): proxy the Studio host to port 8787, pass `X-Forwarded-Proto` and `X-Forwarded-Host`, set `CLOUDHAL_BASE_URL` and `CLOUDHAL_BEHIND_PROXY=1`, and serve `/data/dist` from the volume for the site host. + +## Environment + +All of these are read by `cloudhal studio` in the container (`.env.example` lists them with their defaults): + +| Variable | Default | Meaning | +| --- | --- | --- | +| `CLOUDHAL_TAG` (compose) | `latest` | The image tag; see [upgrades](#upgrades). | +| `CLOUDHAL_BASE_URL` | `http://localhost:8787` | The public origin, as above. | +| `CLOUDHAL_BEHIND_PROXY` | `0` | Trust `X-Forwarded-*`. | +| `CLOUDHAL_BIND`, `CLOUDHAL_PORT` (compose) | `127.0.0.1`, `8787` | Which address and port of the host publish the container's port 8787. | +| `CLOUDHAL_SITE_URL` (caddy profile) | — | The public site's origin, served by Caddy. | +| `CLOUDHAL_INIT` | `blog` | The starter a first start on an empty volume scaffolds. | +| `CLOUDHAL_SITE_NAME` | `My site` | The name of that first site. | +| `CLOUDHAL_AUTOMATIONS` | `on` | `off` stops scheduled automations; releases and gates go on ([schedules](schedules.md)). | +| `CLOUDHAL_TRUSTED_ORIGINS` | empty | Extra origins the API accepts browser requests from, comma-separated. | +| `CLOUDHAL_AI_TOKEN`, `CLOUDFLARE_ACCOUNT_ID` | empty | Workers AI over REST for Build chat (both or neither); the token is never stored. | + +Better Auth's secret is created on the volume at first start (`/data/.cloudhal/auth-secret`); set `BETTER_AUTH_SECRET` to supply your own. + +## The public site + +`cloudhal studio` serves Studio and the API, not the site. The site is `cloudhal build` output, static HTML of the published snapshot, which the image writes to `/data/dist` with + +```bash +docker compose exec cloudhal site-build +``` + +and Caddy (or your web server) serves from the volume. Run it after each publish; a cron line on the host (`*/15 * * * * docker compose -f /path/to/compose.yml exec -T cloudhal site-build`) keeps the site at most that far behind. Drafts, previews and scheduled releases are visible in Studio at once; the public pages change when the next build runs. Rebuilding on publish from inside the container is a follow-up issue; serving the site live from the snapshot, as the Cloudflare deployment does, is an RFC of its own. + +The project's dependencies for the build (Astro, the renderer, Tailwind) are the image's own `node_modules`, linked into the project on the first `site-build`: no install, no network, and an image upgrade upgrades them. + +## Upgrades + +The image carries the same version as the npm packages: `0.6.3` is `@cloudhal/cli@0.6.3`. Tags: `X.Y.Z`, `X.Y` (the newest patch of a minor), `latest` (the newest release) and `edge` (nightly from `main`, for trying what is coming; never for a site you care about). `latest` follows patch releases; **pin the minor in production** (`CLOUDHAL_TAG=0.6`), since in 0.x a minor bump is a breaking change ([releasing](https://github.com/cloudhal-dev/cloudhal/blob/main/CONTRIBUTING.md#releasing)). + +```bash +docker compose pull && docker compose up -d +``` + +Database migrations run when the container starts, as they do on every `cloudhal studio` start. Going back to an older image over a newer database is not supported: take a backup first. + +## Backup and restore + +The volume is the installation: stop the container and copy it (`docker run --rm -v cloudhal-data:/data -v "$PWD":/backup alpine tar czf /backup/cloudhal-data.tgz -C /data .`), or restore the same way into an empty volume. For one site rather than the installation, `cloudhal export` writes a portable `.cloudhal` archive of its graph, snapshots and media (never accounts, comments or secrets) and `cloudhal import` reads it back ([site archives](site-archives.md)): + +```bash +docker compose exec cloudhal cloudhal export --out /data/backup.cloudhal +``` + +```bash +docker compose cp cloudhal:/data/backup.cloudhal . +``` + +## Health + +`GET /api/health` answers `{ "ok": true }` without signing in, once the database is open and migrated; the image's `HEALTHCHECK` asks it every 30 s (`docker compose ps` shows `healthy`). The scheduler's state is at `GET /api/scheduler` for signed-in people and in `cloudhal schedules status`. + +## Limits + +- **Mail** is printed to the logs; there is no SMTP sender yet. +- **`render_page`** (the agents' screenshot tool) needs Chrome, which the image does not carry: the tool reports itself unavailable. A `-chrome` variant is a possible follow-up. +- **One process.** `cloudhal studio` runs the scheduler's tick, the comments job and analytics rollups itself, on the project's SQLite file; several containers on one volume are not supported. +- **The site is static** between builds, as above. +- **Deploying to Cloudflare** from the container is not set up (the Cloudflare adapter is not installed); use the CLI on your machine for that. + +## Building the image yourself + +```bash +docker build --build-arg CLOUDHAL_VERSION=0.6.3 -t cloudhal:local deploy/docker +``` + +builds a release version from npm; `node scripts/pack-packages.ts deploy/docker/tarballs` followed by the same build without the argument builds `edge` from a checkout. `node scripts/docker-smoke.ts --image cloudhal:local` runs what CI runs: an empty volume, the health check, the first owner through the API, a publish and `site-build`. diff --git a/scripts/docker-smoke.ts b/scripts/docker-smoke.ts new file mode 100644 index 00000000..93a14850 --- /dev/null +++ b/scripts/docker-smoke.ts @@ -0,0 +1,125 @@ +/** + * What a self-hoster gets (docs/guides/self-host.md, #143): runs the image with an empty volume, + * waits for its HEALTHCHECK, then — through the API, as Studio would — creates the first owner, + * lists the scaffolded site, publishes it, builds the public site with `site-build` and reads the + * built home page. Run by .github/workflows/docker.yml after every build, and by hand: + * + * node scripts/docker-smoke.ts [--image ] [--port ] [--keep] + */ +import { execFileSync, spawnSync } from "node:child_process"; + +const arg = (name: string): string | undefined => { + const i = process.argv.indexOf(`--${name}`); + return i === -1 ? undefined : process.argv[i + 1]; +}; +const image = arg("image") ?? "cloudhal:local"; +const port = Number(arg("port") ?? 18787); +const keep = process.argv.includes("--keep"); +const name = `cloudhal-smoke-${process.pid}`; +const origin = `http://localhost:${port}`; + +const docker = (args: string[], input?: string): string => + execFileSync("docker", args, { encoding: "utf8", ...(input ? { input } : {}) }).trim(); +const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms)); +const step = (text: string) => console.log(`✓ ${text}`); + +async function waitHealthy(): Promise { + for (let i = 0; i < 90; i++) { + const status = docker(["inspect", "--format", "{{.State.Health.Status}}", name]); + if (status === "healthy") return; + if (docker(["inspect", "--format", "{{.State.Running}}", name]) !== "true") + throw new Error("the container stopped"); + await sleep(2000); + } + throw new Error("the container did not become healthy within 180 s"); +} + +async function api( + method: string, + path: string, + options: { body?: unknown; cookie?: string } = {}, +): Promise<{ status: number; body: unknown; res: Response }> { + const res = await fetch(`${origin}${path}`, { + method, + headers: { + origin, + "content-type": "application/json", + ...(options.cookie ? { cookie: options.cookie } : {}), + }, + ...(options.body !== undefined ? { body: JSON.stringify(options.body) } : {}), + }); + const text = await res.text(); + let body: unknown = text; + try { + body = JSON.parse(text); + } catch { + // not JSON + } + return { status: res.status, body, res }; +} + +function expect(ok: boolean, what: string, detail?: unknown): void { + if (!ok) throw new Error(`${what}${detail === undefined ? "" : `: ${JSON.stringify(detail)}`}`); +} + +docker([ + "run", + "-d", + "--name", + name, + "-p", + `127.0.0.1:${port}:8787`, + "-e", + `CLOUDHAL_BASE_URL=${origin}`, + "-e", + "CLOUDHAL_SITE_NAME=Smoke Site", + image, +]); +try { + await waitHealthy(); + step("the container is healthy"); + const health = await api("GET", "/api/health"); + expect(health.status === 200, "GET /api/health", health.body); + expect((health.body as { ok?: boolean }).ok === true, "health says ok", health.body); + step("/api/health answers { ok: true }"); + + const signUp = await api("POST", "/api/auth/sign-up/email", { + body: { name: "Smoke Owner", email: "owner@example.com", password: "smoke-test-password" }, + }); + expect(signUp.status === 200, "sign-up of the first owner", signUp.body); + const cookie = signUp.res.headers + .getSetCookie() + .map((c) => c.split(";")[0] as string) + .find((c) => c.includes("better-auth.session_token=")); + expect(cookie !== undefined, "sign-up set a session cookie"); + const me = await api("GET", "/api/me", { cookie }); + expect( + (me.body as { role?: string }).role === "owner", + "the first account is the Owner", + me.body, + ); + step("the first owner signed up through the API"); + + const sites = await api("GET", "/api/sites", { cookie }); + const site = (sites.body as { id: string; name: string }[])[0]; + expect(site?.name === "Smoke Site", "the scaffolded site is listed", sites.body); + const publish = await api("POST", `/api/sites/${site.id}/snapshots`, { + cookie, + body: { publish: true, label: "smoke" }, + }); + expect(publish.status === 200 || publish.status === 201, "publish", publish.body); + step(`site ${site.id} published`); + + spawnSync("docker", ["exec", name, "site-build"], { stdio: "inherit" }); + const html = docker(["exec", name, "cat", "/data/dist/index.html"]); + expect(/]*>Smoke Site<\/h1>/.test(html), "the built home page shows the site name"); + step("site-build wrote the public site to /data/dist"); + console.log("\nDocker smoke test passed."); +} catch (e) { + console.error(`\n✗ ${e instanceof Error ? e.message : String(e)}\n--- container logs ---`); + spawnSync("docker", ["logs", "--tail", "200", name], { stdio: "inherit" }); + process.exitCode = 1; +} finally { + if (keep) console.log(`kept container ${name}`); + else spawnSync("docker", ["rm", "-f", "-v", name], { stdio: "ignore" }); +} diff --git a/scripts/pack-packages.ts b/scripts/pack-packages.ts new file mode 100644 index 00000000..2ea60c45 --- /dev/null +++ b/scripts/pack-packages.ts @@ -0,0 +1,52 @@ +/** + * Builds every publishable package and packs it into a folder, for the `edge` Docker image + * (.github/workflows/docker.yml): the same build and `pnpm pack` as scripts/smoke-pack.ts, with an + * `index.json` (package name → tarball file) that deploy/docker/install.mjs installs from. + * + * node scripts/pack-packages.ts [--no-build] + */ +import { execFileSync } from "node:child_process"; +import { mkdir, readdir, readFile, writeFile } from "node:fs/promises"; +import path from "node:path"; +import { fileURLToPath } from "node:url"; +import { PACKAGES } from "./build-packages.ts"; + +const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), ".."); + +/** Packs the built packages into `dir` and writes its index; returns name → file. */ +export async function packPackages( + dir: string, + options: { build?: boolean } = {}, +): Promise> { + const out = path.resolve(dir); + if (options.build !== false) + execFileSync(process.execPath, ["scripts/build-packages.ts"], { cwd: ROOT, stdio: "inherit" }); + await mkdir(out, { recursive: true }); + for (const name of PACKAGES) + execFileSync("pnpm", ["pack", "--pack-destination", out], { + cwd: path.join(ROOT, "packages", name), + stdio: "inherit", + }); + const files = await readdir(out); + const index: Record = {}; + for (const name of PACKAGES) { + const pkg = JSON.parse( + await readFile(path.join(ROOT, "packages", name, "package.json"), "utf8"), + ) as { name: string; version: string }; + const tgz = files.find( + (f) => f === `${pkg.name.replace("@", "").replace("/", "-")}-${pkg.version}.tgz`, + ); + if (!tgz) throw new Error(`no tarball for ${pkg.name} in ${files.join(", ")}`); + index[pkg.name] = tgz; + } + await writeFile(path.join(out, "index.json"), `${JSON.stringify(index, null, 2)}\n`); + return index; +} + +if (import.meta.url === `file://${process.argv[1]}`) { + const args = process.argv.slice(2); + const dir = args.find((a) => !a.startsWith("--")); + if (!dir) throw new Error("usage: node scripts/pack-packages.ts [--no-build]"); + const index = await packPackages(dir, { build: !args.includes("--no-build") }); + console.log(`packed ${Object.keys(index).length} packages into ${path.resolve(dir)}`); +} From a0f503e317a7079a9a542bbac569e061ec51d09c Mon Sep 17 00:00:00 2001 From: Madraka <8898640+Madraka@users.noreply.github.com> Date: Sun, 8 Nov 2026 01:41:57 +0300 Subject: [PATCH 2/3] style(scripts): narrow the smoke test's cookie and site before use Co-Authored-By: Claude Fable 5.1 Signed-off-by: Madraka <8898640+Madraka@users.noreply.github.com> --- scripts/docker-smoke.ts | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/scripts/docker-smoke.ts b/scripts/docker-smoke.ts index 93a14850..d437bde9 100644 --- a/scripts/docker-smoke.ts +++ b/scripts/docker-smoke.ts @@ -91,7 +91,7 @@ try { .getSetCookie() .map((c) => c.split(";")[0] as string) .find((c) => c.includes("better-auth.session_token=")); - expect(cookie !== undefined, "sign-up set a session cookie"); + if (cookie === undefined) throw new Error("sign-up set no session cookie"); const me = await api("GET", "/api/me", { cookie }); expect( (me.body as { role?: string }).role === "owner", @@ -102,7 +102,8 @@ try { const sites = await api("GET", "/api/sites", { cookie }); const site = (sites.body as { id: string; name: string }[])[0]; - expect(site?.name === "Smoke Site", "the scaffolded site is listed", sites.body); + if (site?.name !== "Smoke Site") expect(false, "the scaffolded site is listed", sites.body); + if (!site) throw new Error("no site"); const publish = await api("POST", `/api/sites/${site.id}/snapshots`, { cookie, body: { publish: true, label: "smoke" }, From b347d4a83df6e8552966aa2b9a86f192160dd8e0 Mon Sep 17 00:00:00 2001 From: Madraka <8898640+Madraka@users.noreply.github.com> Date: Sun, 8 Nov 2026 01:50:57 +0300 Subject: [PATCH 3/3] docs(changeset): release note for the Docker image (#143) Co-Authored-By: Claude Fable 5.1 Signed-off-by: Madraka <8898640+Madraka@users.noreply.github.com> --- .changeset/docker-image.md | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 .changeset/docker-image.md diff --git a/.changeset/docker-image.md b/.changeset/docker-image.md new file mode 100644 index 00000000..2e89bea3 --- /dev/null +++ b/.changeset/docker-image.md @@ -0,0 +1,5 @@ +--- +"@cloudhal/cli": patch +--- + +Self-hosting (#143): the official Docker image `ghcr.io/cloudhal-dev/cloudhal`, built from this release for linux/amd64 and linux/arm64 (tags `X.Y.Z`, `X.Y`, `latest`; `edge` nightly from `main`). One container runs `cloudhal studio` — Studio, the API and the MCP endpoint — with the project, its SQLite database and media on a `/data` volume; the first start on an empty volume scaffolds the project. `site-build` inside the container writes the public site as static HTML, which the compose file's optional Caddy serves with automatic TLS next to Studio. Guide: docs/guides/self-host.md.