levivannoort · Oct 14, 2026 · Oct 14, 2026 · Oct 14, 2026
@@ -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:

@@ -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. |

@@ -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

@@ -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": {

@@ -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

@@ -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 `<fullname>-browser-egress` policy limits it to
 DNS, the Appwrite API and public IPv4 addresses. Private, loopback,

@@ -320,6 +320,26 @@ 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 worker that
+consumes the screenshots queue logs the cause; this finds it with any
+`workers.mode`:
+
+```console
+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
+  (`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