Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .changeset/docker-image.md
Original file line number Diff line number Diff line change
@@ -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.
7 changes: 7 additions & 0 deletions .github/dependabot.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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 }
146 changes: 146 additions & 0 deletions .github/workflows/docker.yml
Original file line number Diff line number Diff line change
@@ -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-<short>;
# - Actions › Docker image › Run workflow with a version re-publishes or backfills it (X.Y.Z, X.Y
# and sha-<short>; `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-<short> 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
15 changes: 15 additions & 0 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,8 @@ name: Release
# npm trusted publishing (OIDC, provenance), and creates one `v<version>` 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:<version>, :<major.minor> and :latest (issue #143).
# npm's trusted-publisher entry for each package names this file and the `npm-publish`
# environment: renaming either breaks publishing.

Expand Down Expand Up @@ -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).
3 changes: 3 additions & 0 deletions .gitignore
Original file line number Diff line number Diff line change
Expand Up @@ -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/
1 change: 1 addition & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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).
Expand Down
1 change: 1 addition & 0 deletions apps/docs/src/lib/site-pages.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
8 changes: 8 additions & 0 deletions deploy/docker/.dockerignore
Original file line number Diff line number Diff line change
@@ -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
29 changes: 29 additions & 0 deletions deploy/docker/.env.example
Original file line number Diff line number Diff line change
@@ -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=
19 changes: 19 additions & 0 deletions deploy/docker/Caddyfile
Original file line number Diff line number Diff line change
@@ -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
}
}
51 changes: 51 additions & 0 deletions deploy/docker/Dockerfile
Original file line number Diff line number Diff line change
@@ -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"]
Loading
Loading