From 46589f9ade250b3d9042910e06263ec1e36e25d0 Mon Sep 17 00:00:00 2001 From: Levi van Noort <73097785+levivannoort@users.noreply.github.com> Date: Wed, 14 Oct 2026 13:21:17 +0200 Subject: [PATCH 1/2] feat: browser on by default Sites are on by default since 2.0.0, and Appwrite takes a screenshot of every site deployment through the browser service, which was off by default: each site deployment then logged "Screenshot capturing failed" (the screenshots worker can't resolve appwrite-browser) and the console showed no preview. Appwrite's Docker install runs the browser by default too. The optional-components guide says so, troubleshooting covers the failed screenshot (browser off, or its egress policy), and every CI install now also runs hack/smoke.sh's screenshot check. --- CHANGELOG.md | 10 ++++++++++ charts/appwrite/README.md | 2 +- charts/appwrite/tests/optional_test.yaml | 9 +++++++-- charts/appwrite/values.schema.json | 2 +- charts/appwrite/values.yaml | 6 ++++-- docs/optional-components.md | 13 +++++++++---- docs/troubleshooting.md | 19 +++++++++++++++++++ 7 files changed, 51 insertions(+), 10 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index d11ead0..06573cf 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,16 @@ annotation in `charts/appwrite/Chart.yaml`. ## [Unreleased] +### Changed + +- The browser is on by default (`browser.enabled`), since Sites are: it + renders their preview screenshots. Without it, every site deployment logs + "Screenshot capturing failed" and the console shows no preview. + +### Added + +- Troubleshooting for site deployments whose screenshot fails. + ## [2.0.0] - 2026-10-14 Appwrite 2.5.0, with Functions and Sites on by default. Upgrading from 1.0.0: diff --git a/charts/appwrite/README.md b/charts/appwrite/README.md index 9580b7b..0604d96 100644 --- a/charts/appwrite/README.md +++ b/charts/appwrite/README.md @@ -965,7 +965,7 @@ The build orchestrator and the executor. | autogravity.tolerations | list | `[]` | Tolerations. Empty inherits `defaults.tolerations`. | | browser.affinity | object | `{}` | Affinity. Empty inherits `defaults.affinity`. | | browser.containerSecurityContext | object | `{"allowPrivilegeEscalation":false,"capabilities":{"drop":["ALL"]},"privileged":false,"readOnlyRootFilesystem":true}` | Container security context. | -| browser.enabled | bool | `false` | Deploy the browser service. | +| browser.enabled | bool | `true` | Deploy the browser service. Sites need it for their preview screenshots: without it, every site deployment logs that capturing the screenshot failed, and the console shows no preview. | | browser.extraContainers | list | `[]` | Extra sidecar containers. | | browser.extraEnv | list | `[]` | Extra environment variables, as a list of EnvVar objects. | | browser.extraInitContainers | list | `[]` | Extra init containers. | diff --git a/charts/appwrite/tests/optional_test.yaml b/charts/appwrite/tests/optional_test.yaml index 675759a..1c0323c 100644 --- a/charts/appwrite/tests/optional_test.yaml +++ b/charts/appwrite/tests/optional_test.yaml @@ -13,9 +13,14 @@ release: values: - values/required.yaml tests: - - it: deploys none of them by default + - it: deploys the browser by default, as Sites need it for previews + template: templates/browser/deployment.yaml + asserts: + - hasDocuments: + count: 1 + + - it: deploys none of the others by default templates: - - templates/browser/deployment.yaml - templates/autogravity/deployment.yaml - templates/embedding/deployment.yaml - templates/mqtt/deployment.yaml diff --git a/charts/appwrite/values.schema.json b/charts/appwrite/values.schema.json index f653ba1..7b0f4d1 100644 --- a/charts/appwrite/values.schema.json +++ b/charts/appwrite/values.schema.json @@ -713,7 +713,7 @@ "description": "Container security context." }, "enabled": { - "description": "Deploy the browser service.", + "description": "Deploy the browser service. Sites need it for their preview screenshots: without it, every site deployment logs that capturing the screenshot failed, and the console shows no preview.", "type": "boolean" }, "extraContainers": { diff --git a/charts/appwrite/values.yaml b/charts/appwrite/values.yaml index 49f3101..ea2d9b1 100644 --- a/charts/appwrite/values.yaml +++ b/charts/appwrite/values.yaml @@ -1887,8 +1887,10 @@ geo: # screenshot API. With NetworkPolicies enabled, it may only reach the # Appwrite API and public addresses. See docs/optional-components.md#browser. browser: - # -- Deploy the browser service. - enabled: false + # -- Deploy the browser service. Sites need it for their preview + # screenshots: without it, every site deployment logs that capturing the + # screenshot failed, and the console shows no preview. + enabled: true image: # -- Image registry. registry: docker.io diff --git a/docs/optional-components.md b/docs/optional-components.md index 2007f64..18d3bac 100644 --- a/docs/optional-components.md +++ b/docs/optional-components.md @@ -1,12 +1,13 @@ # Optional components Appwrite's Docker install ships a few supporting services. The chart can run -each of them. Geo is on by default; the others are off until you enable them. +each of them. Geo and the browser are on by default; the others are off until +you enable them. | Component | Value | Default | What it gives you | | --- | --- | --- | --- | | [Geo](#geo) | `geo.enabled` | on | Country and location for sessions and logs. | -| [Browser](#browser) | `browser.enabled` | off | Site screenshots and `/v1/avatars/screenshots`. | +| [Browser](#browser) | `browser.enabled` | on | Site screenshots and `/v1/avatars/screenshots`. | | [Autogravity](#autogravity) | `autogravity.enabled` | off | Image previews cropped around the subject (`gravity=auto`). | | [Embedding](#embedding) | `embedding.enabled` | off | The embeddings API, which turns text into vectors. | | [MQTT](#mqtt) | `mqtt.enabled` | off | Push notifications over MQTT, through Messaging's Appwrite provider. | @@ -32,13 +33,17 @@ pod lowers `net.ipv4.ip_unprivileged_port_start` instead of running as root. ## Browser A headless Chromium that renders screenshots: of each site deployment, shown -in the console, and of any URL through the avatars API. +in the console, and of any URL through the avatars API. It's on by default, +because Sites are. To turn it off: ```yaml browser: - enabled: true + enabled: false ``` +Without it, every site deployment logs "Screenshot capturing failed" and the +console shows no preview; the site itself deploys and serves normally. + Users choose the URLs it loads, so treat it as a way into your network. With `networkPolicy.enabled`, the `-browser-egress` policy limits it to DNS, the Appwrite API and public IPv4 addresses. Private, loopback, diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 52db768..00f00aa 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -320,6 +320,25 @@ Deployments that stay `waiting`, builds that fail, executor pods that don't start, executions that time out: see [executor.md](executor.md#troubleshooting). +### Site deployments log "Screenshot capturing failed" + +The site deploys and serves, but its deployment log ends with "Screenshot +capturing failed" and the console shows no preview. The screenshots worker +logs the cause: + +```console +kubectl -n appwrite logs deploy/appwrite-worker | grep -i screenshots | tail -1 +``` + +- `Could not resolve host: appwrite-browser`: the browser is off + (`browser.enabled: false`). Turn it on and redeploy the site; screenshots + are only taken during a deployment + ([optional-components.md](optional-components.md#browser)). +- A timeout, or a refused connection to the API: with `networkPolicy.enabled`, + the browser may only reach DNS, the API and public addresses + ([security.md](security.md#network-policies)); check that its egress + policy matches your DNS ([networking.md](networking.md#networkpolicies-and-dns)). + ### Deployments fail with an internal error Every deployment fails with "An internal error occurred while building", and From 65fef58723c17b767afcb6c84729d87793277d55 Mon Sep 17 00:00:00 2001 From: Levi van Noort <73097785+levivannoort@users.noreply.github.com> Date: Wed, 14 Oct 2026 13:23:54 +0200 Subject: [PATCH 2/2] docs: find the screenshots worker's log in every worker mode deploy/appwrite-worker only exists with workers.mode combined; select the worker pods by their appwrite/role label instead, with enough --tail for a selector (which defaults to 10 lines per pod). --- docs/troubleshooting.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/troubleshooting.md b/docs/troubleshooting.md index 00f00aa..9e63c76 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.md @@ -323,11 +323,12 @@ start, executions that time out: see ### Site deployments log "Screenshot capturing failed" The site deploys and serves, but its deployment log ends with "Screenshot -capturing failed" and the console shows no preview. The screenshots worker -logs the cause: +capturing failed" and the console shows no preview. The worker that +consumes the screenshots queue logs the cause; this finds it with any +`workers.mode`: ```console -kubectl -n appwrite logs deploy/appwrite-worker | grep -i screenshots | tail -1 +kubectl -n appwrite logs -l appwrite/role=worker --prefix --tail=2000 | grep -i screenshots | tail -1 ``` - `Could not resolve host: appwrite-browser`: the browser is off