A minimal, dependency-free chart for Browserless Chromium: a Deployment of one
or more identical instances and a ClusterIP Service. It needs Helm 4, Linux
amd64 or arm64 nodes and a maintained Kubernetes version (see
Compatibility). The
default image is the ghcr.io/browserless/chromium release that image.tag
names in values.yaml; the chart's
appVersion always names the same release.
If the chart is not yet published or not accessible, use Install from a checkout for the install step instead. After publication, verify the package is public for anonymous installs.
Needs Helm 4, kubectl with access to a cluster, OpenSSL and curl. Create a new namespace and a Secret holding a random token:
token=$(openssl rand -hex 24) && [ -n "$token" ] &&
kubectl create namespace browserless &&
printf %s "$token" |
kubectl -n browserless create secret generic browserless-token --from-file=TOKEN=/dev/stdin
unset tokenThis stops at the first step that fails. If the namespace browserless already
exists, it creates nothing: use another namespace name in every command here
instead, so that the quick start and its removal touch only what it created.
Install the chart:
helm install browserless oci://ghcr.io/browserless/charts/browserless \
--namespace browserless --set token.existingSecret=browserless-token \
--wait --timeout 10mThis installs the newest published version; add --version to choose one. For
production, verify the chart and install it by digest (see Releases).
In one terminal, forward a local port to the Service and leave it running:
kubectl -n browserless port-forward --address 127.0.0.1 \
service/browserless-browserless 3000:3000If it stops because port 3000 is in use, do not send the request: whatever
listens there would receive the token. Use another local port instead, such as
3001:3000, in the port-forward and in the request's URL.
In a second terminal, have Chromium render a page:
kubectl -n browserless get secret browserless-token \
-o go-template='Authorization: Bearer {{.data.TOKEN | base64decode}}' |
curl -fsS -H @- -H 'Content-Type: application/json' \
-d '{"html":"<p id=answer></p><script>answer.textContent = 6 * 7</script>"}' \
http://127.0.0.1:3000/chromium/contentIt prints the page as Chromium rendered it, with <p id="answer">42</p>. The
token goes from the Secret straight to curl's standard input, so it is in no
file and not in curl's command line, which other users of the machine can
list. Without the token, Browserless answers 401 and curl reports an error.
To remove it, stop the port-forward with Ctrl-C, then:
helm uninstall browserless --namespace browserless
kubectl -n browserless delete secret browserless-tokenThe quick start created the namespace browserless; once nothing else uses it,
also run kubectl delete namespace browserless.
Keep real tokens in a secret manager or a protected file, never in Helm values
or source control; the chart only reads the Secret and creates none. The token
must be nonempty printable ASCII without whitespace; otherwise the container
exits 2 before starting, because Bearer authentication and the readiness probe
cannot carry it. A missing Secret or key keeps the container from starting.
token.key defaults to TOKEN. Rotating the token needs a pod restart. Release
names must start with a lowercase letter and contain only lowercase letters,
digits and -.
Before the first release, or to try unreleased changes, create the Secret as above and install the chart from a clone instead:
git clone https://github.com/browserless/helm-charts.git
helm install browserless ./helm-charts/charts/browserless \
--namespace browserless --set token.existingSecret=browserless-token \
--wait --timeout 10mvalues.yaml is the complete surface; other
keys are rejected, except Helm's global, so the chart also works as a
dependency.
- Image: a nonempty
image.digestreplaces the tag. Custom images must keep the upstream Node runtime, working directory and./scripts/start.sh. - Admission:
concurrent,queuedandtimeout(milliseconds) set the image'sCONCURRENT,QUEUEDandTIMEOUTand default to its own values. They must be at least 1, 0 and 1; unlimited or disabled settings are not supported. Requests beyondconcurrent+queuedget 429. - Memory: the default resources are not sized for
concurrentreal pages. An out-of-memory kill stops the container and every session, and/pressurereports memory saturation only at 99% of the limit, so sizeresources.limits.memoryfor your workload or lowerconcurrent./dev/shmis a memory-backed emptyDir (shmSizeLimit) that counts toward that budget. - Persistence:
persistence.existingClaimmounts an existing PVC atpersistence.mountPath; clients choose profile directories such as--user-data-dir=/data/<profile>. The defaultfsGroup: 999makes most block volumes writable by the browser user. Volumes that ignorefsGroup(hostPath, many NFS and some CSI drivers) must already be writable by UID 999, or the container exits 2 instead of silently losing profiles. Do not mount it over the application, home, temporary or shared-memory paths (/usr/src/app,/home/blessuser,/tmp,/dev/shm). One profile supports one browser at a time, and a browser killed abruptly leavesSingleton*lock files that a replacement pod cannot get past until they are removed. A volume needsreplicaCount: 1(see Replicas). - Cookies: in tests, cookies changed less than about 30 s before a session
ended were missing from the profile afterwards (Chromium writes them on a
timer), so keep a session open at least 30 s after changes that must
persist. The default
timeoutends sessions after 30 s; raise it or pass&timeout=<ms>when connecting. - Security: the defaults meet the restricted Pod Security Standard (UID 999,
no privilege escalation, no capabilities, runtime-default seccomp) and mount no
service-account token. The root filesystem stays writable for Chromium. The
chart sets
DEBUGwithout debug-level logs, which print launch options includingTOKEN. - Updates: the Deployment uses Recreate: an upgrade that changes the pods
stops all of them before starting new ones, so it interrupts service and can
end active sessions, and a failed upgrade (for example an unpullable image)
leaves no ready pod until a rollback. Check that a new image exists for your
nodes' architecture first. Upgrade with all your values every time, for example the same values file (
-f): an upgrade that passes any--setor-fresets every value it omits to the chart default, so one that sets only the token Secret dropspersistence.existingClaim. A values file that setsimage.digestorimage.tagkeeps that image across chart upgrades. There is no draining, autoscaling, Ingress, TLS or NetworkPolicy, and no claim of high availability or tenant isolation.
replicaCount (default 1) runs that many identical, independent instances
behind the Service. Change it with the chart version (or digest) and all the
values you installed with. Otherwise Helm takes the newest chart, which can
bring another image, and resets the values you leave out to their defaults; if
either changes the pods, every pod is replaced (see Updates above). For the
quick start's release, with 0.1.0 replaced by the VERSION that
helm get metadata browserless --namespace browserless shows:
helm upgrade browserless oci://ghcr.io/browserless/charts/browserless \
--version 0.1.0 --namespace browserless \
--set token.existingSecret=browserless-token --set replicaCount=2 \
--wait --timeout 10mIf you installed by digest as in Releases, put the same
"$CHART@$DIGEST" reference in place of the chart name and leave out
--version; if you installed from a checkout, put the same checkout's chart
directory there instead, such as ./helm-charts/charts/browserless.
- Kubernetes sends each new connection to one ready pod, without regard to its load or queue. Everything on that connection stays on that pod: a WebSocket session for its whole life, and every request on a reused keep-alive connection. Clients spread work across pods only by opening new connections.
- The pods share nothing.
concurrentandqueuedapply to each pod, and a browser or session exists only on the pod that started it, so reconnecting to an existing browser through the Service is not supported; there is no session stickiness. - Readiness takes a saturated pod out of the Service at its next check, up to 10 s later, plus the time the Service takes to update; until then the pod can still receive new connections. After that, new connections go to the other pods, while the connections it already accepted normally continue.
persistence.existingClaimmust be empty above one replica, and the chart refuses to render otherwise: every replica would mount the same volume, and a browser profile supports one browser at a time, also on a ReadWriteMany volume.- Changing only
replicaCountadds or removes pods without restarting the others; sessions on a removed pod are not moved or drained. An upgrade that changes the pods stops every replica first (see Updates above).
Readiness runs Node in the container against authenticated /pressure with
Accept: text/plain, which returns 503 when saturated (its JSON form returns 200
either way). Startup and liveness only check TCP, so load takes the pod out of
the Service instead of restarting it. While no pod is ready (with one replica,
whenever it is saturated), clients must retry.
A port-forward connects to the pod even while it is not ready; check the
Service's EndpointSlices to see whether it routes to the pod.
The chart supports the Kubernetes minor versions that the Kubernetes project
currently maintains. Kubernetes has no
long-term-support releases: it maintains the three newest minor versions, each
for about a year. kubeVersion in Chart.yaml
admits exactly those minor versions, and CI runs the runtime tests on each of
them on amd64 and arm64, with the kind node images published for the kind
release in tools/go.mod (see
kind releases). The tested
versions are the directories in tests/kind and the e2e matrix
in ci.yml; the chart tests fail unless these and
kubeVersion agree. The -0 suffixes in kubeVersion admit vendor builds such
as -gke.N, which semver reads as pre-releases.
When a new Kubernetes minor version is released and kind publishes a node image
for it, add its tests/kind/<minor> directory and matrix entry and raise the
kubeVersion ceiling; when a minor version reaches end of life, remove it and
raise the floor. Each such change is a chart release.
kind clusters do not stand in for every environment: before production use, repeat the checks below where the chart will run, including storage permissions, admission policies, image pulls and the upgrade interruption.
Needs Node.js of the major version in .nvmrc (CI uses its latest
release), Docker, jq, OpenSSL and ShellCheck:
npm ci
node scripts/install-tools.ts # Helm, kind and actionlint into .bin/
npm run typecheck && npm test # the CI static job, with the two lines below
.bin/actionlint
shellcheck scripts/*.sh tests/e2e/*.sh
tests/e2e/kind.sh # newest tests/kind version
KIND_CONFIG=tests/kind/<minor>/cluster.yaml tests/e2e/kind.sh
UPGRADE_FROM=oci://ghcr.io/browserless/charts/browserless tests/e2e/kind.shnpm test runs the chart tests (schema, defaults and overrides, entrypoint
guards, Kubernetes and runner coverage, lint, package contents and
reproducibility, use as a dependency) and the tool installer's tests. Node runs
the TypeScript directly; npm run typecheck checks it with tsc. npm packages
are third-party code, so jobs that can push, publish, sign or read an
environment's secrets install none and run only scripts that import Node
built-ins. A chart test checks the common ways this could regress; it is not a
complete security analysis of the workflows.
tests/e2e/kind.sh (the CI e2e jobs) installs the working tree on a
disposable kind cluster under the restricted Pod Security Standard and checks
real browser requests and authentication through the pod and the Service, a
profile on a PVC surviving pod replacement and rollback, saturation removing the
only endpoint without a restart and capacity restoring it, the token and volume
guards, that the token never reaches a log, a second release scaled 1 → 2 → 1
whose Service selects only its own pods and sends new connections, both
requests and WebSocket sessions, to each of its two pods, uninstall keeping the
PVC, and with UPGRADE_FROM an upgrade that never runs two browsers at once.
It deletes its cluster unless KEEP_CLUSTER=1 and writes redacted diagnostics
to tests/e2e/out/. Its sessions are idle: it shows admission behaviour, not
memory capacity.
tools/ is not a Go program. Its go.mod is the list of Helm, kind and
actionlint versions, kept there because Dependabot updates Go modules;
nothing builds it, and you do not need Go. scripts/install-tools.ts downloads
each version's official release binary for the current platform and refuses it
unless its SHA-256 matches the checksum file published with the same release.
That proves integrity, not authenticity: a release whose binary and checksum file
were both replaced would pass, and tools/go.sum, which Dependabot maintains,
does not attest the binaries.
Pull requests are squash-merged with the pull request title as the commit
subject and a blank body (squash_merge_commit_title=PR_TITLE,
squash_merge_commit_message=BLANK), and titles must be Conventional Commits
(pr-title.yml). Release Please
reads them: feat raises the minor version; fix, perf, revert and build
the patch version; chore, ci, docs, style, refactor and test release
nothing. Mark a breaking change with ! in the title (feat!: ...), which
raises the major version; footers in the body are not kept. Dependabot's image
updates are build commits, so a new Browserless image is a patch release.
Release Please keeps a draft release pull request per chart that sets
Chart.yaml version, the chart's CHANGELOG.md and
.release-please-manifest.json. Merging it creates the tag <chart>-v<version>
and its GitHub Release, which starts publish.yml. From the tag, a job without
write access repeats the chart tests and checks appVersion. The publishing
job then runs scripts/publish-chart.sh, which refuses unless the checkout is
the tag, the tag is on main, and the chart version and manifest agree. It
refuses to overwrite an existing version, packages reproducibly (times come
from the tag's commit), pushes to oci://ghcr.io/browserless/charts/browserless,
and pulls the chart back to compare bytes and digest. The job then records a
signed SLSA provenance attestation for the pushed manifest digest and verifies
it.
If publish.yml fails before its push, rerun it. If it fails during or after
the push, or a rerun finds the version already exists, treat that version as
failed: do not use, delete, overwrite or describe it as verified, note this in
its GitHub Release, and release the next patch version with a fix: pull request
that changes charts/browserless (a ci: change releases nothing).
The registry alone does not prove where a chart came from: anyone with write
access to this repository can push packages with a workflow's GITHUB_TOKEN.
Only a digest whose attestation publish.yml signed for the version's tag
identifies a published chart. Resolve the digest once, verify it, and install
that digest, not the version tag:
CHART=oci://ghcr.io/browserless/charts/browserless VERSION=<version>
DIGEST="$(helm pull "$CHART" --version "$VERSION" --destination "$(mktemp -d)" |
sed -n 's/^Digest: //p')" &&
[ -n "$DIGEST" ] &&
gh attestation verify "$CHART@$DIGEST" --repo browserless/helm-charts \
--signer-workflow browserless/helm-charts/.github/workflows/publish.yml \
--source-ref "refs/tags/browserless-v$VERSION" &&
helm upgrade --install browserless "$CHART@$DIGEST" \
--namespace browserless --set token.existingSecret=browserless-token \
--wait --timeout 10m- A
release-pleaseenvironment limited tomain, without administrator bypass, holding the release GitHub App's client ID (RELEASE_APP_CLIENT_IDvariable) and private key (RELEASE_APP_PRIVATE_KEYsecret). The App needs Contents, Pull requests and Issues write access.release-please.ymlfails without them instead of falling back toGITHUB_TOKEN, whose pull requests and releases would trigger no workflows. Code that runs in that job onmaincan read the key, so themainruleset decides who controls it. - A
chart-releaseenvironment with required reviewers, without administrator bypass, limited tobrowserless-v*tags. It is a single-person gate: the App starts the deployment, so preventing self-review does not stop whoever merged the release pull request from approving its publication. - Tag rulesets for
browserless-v*: only the release App may create these tags, and nobody may update or delete them. - A
mainruleset requiring pull requests with one approving review and approval of the most recent push, the GitHub Actions checksstaticandkind, squash merging only, and no force pushes or deletion.kindfails unless everye2ejob passed, so the required checks stay the same when the tested Kubernetes versions change. - Workflow
GITHUB_TOKENpermissions default to read, GitHub Actions cannot approve pull requests, and workflows from all outside contributors need approval.
The release App is browserless-actions-bot, which browserless/browserless
also releases with. Each token release-please.yml creates is limited to this
repository and three permissions, but the App's keys are not: any of its keys,
wherever stored, can create tokens for every repository the App is installed on
with all its permissions, including Actions, secrets and environments, and
creating browserless-v* tags here. The App cannot change rulesets, and the
chart-release reviewers still decide what is published. After the first
publish, make the GHCR package public.
Dependabot (.github/dependabot.yml) proposes updates
for the default image (helm, as build commits), workflow actions, Helm,
kind and actionlint (gomod, through tools/go.mod), the scripts' npm packages
and the kind node images (patch and digest updates only). It does not update
appVersion: dependabot-app-version.yml commits the matching appVersion to
Dependabot's image pull requests and starts CI for that commit. The PR title
check does not run again for it, which is why branch protection requires only
static and kind. @dependabot recreate drops the sync commit, and the
workflow adds it again. A node image that the pinned kind release cannot start
fails CI until kind is updated. Not covered: the Node.js patch release, and the
runner's ShellCheck, jq, OpenSSL and Docker; kubectl runs inside the kind node.