Add config for running web-forms via containers

contrib/containers/Containerfile

@@ -0,0 +1,30 @@
+FROM emscripten/emsdk:4.0.4 AS emsdk
+
+
+# We can't use node bundled in emsdk img as v20.18.0 is incompatible with pinned engines
+FROM docker.io/node:22-slim AS build
+WORKDIR /app
+COPY --from=emsdk /emsdk /emsdk
+ENV PATH=$PATH:/emsdk:/emsdk/upstream/emscripten
+RUN apt-get update --quiet \
+    && DEBIAN_FRONTEND=noninteractive \
+    apt-get install -y --quiet --no-install-recommends \
+        "ca-certificates" \
+        "git" \
+        "python3" \
+    && rm -rf /var/lib/apt/lists/* \
+    && update-ca-certificates
+COPY . .
+RUN corepack enable && corepack install
+RUN yarn install
+# Build packages as a sanity check + make available in tests stage
+RUN yarn workspace @getodk/tree-sitter-xpath build
+RUN yarn workspace @getodk/xpath build
+RUN yarn workspace @getodk/xforms-engine build
+
+
+FROM build AS test
+RUN yarn playwright install chromium --with-deps \
+    && yarn playwright install firefox --with-deps \
+    && yarn playwright install webkit --with-deps \
+    && rm -rf /var/lib/apt/lists/*

contrib/containers/README.md

@@ -0,0 +1,37 @@
+# Running Web Forms Via Docker
+
+Running web-forms locally requires two things:
+- As of 05/03/2025, web-forms requires the compiled WASM bundle for the `tree-sitter` package.
+  - Building this requires emscripten or docker installed on your machine, see [issue #41](https://github.com/getodk/web-forms/issues/41).
+- The xlsform-online service running on a local port.
+
+A simple alternative to building and configuring these manually is to run web-forms via docker.
+
+## Building The Images
+
+```bash
+docker compose -f contrib/containers/compose.yaml build
+```
+
+## Running Web Forms
+
+```bash
+docker compose -f contrib/containers/compose.yaml up -d
+```
+
+Access web forms preview on: http://localhost:5173
+
+## Testing Web Forms
+
+Run all tests:
+
+```bash
+docker compose -f contrib/containers/compose.yaml run --rm tests
+```
+
+Run a specific test:
+
+```bash
+TEST_CMD='yarn workspace @getodk/web-forms run test:e2e:chromium' \
+  docker compose -f contrib/containers/compose.yaml run --rm tests
+```

contrib/containers/compose.yaml

@@ -0,0 +1,48 @@
+services:
+  web-forms:
+    image: ghcr.io/getodk/web-forms:main
+    build:
+      context: ../..
+      dockerfile: contrib/containers/Containerfile
+      target: build
+    volumes:
+      - ../../packages/common:/app/packages/common
+      - ../../packages/web-forms:/app/packages/web-forms
+      # Mount each package individually to avoid overwriting generated dist
+      - ../../packages/xpath/src:/app/packages/xpath/src
+      - ../../packages/xforms-engine/src:/app/packages/xforms-engine/src
+    ports:
+      - "${WEB_FORMS_PORT:-5173}:5173"
+    command: yarn workspace @getodk/web-forms dev
+
+  xlsform-online:
+    image: ghcr.io/getodk/xlsform-online:master
+    build: 
+      context: https://github.com/getodk/xlsform-online.git#master
+    environment:
+      DJANGO_SECRET_KEY: xxxxxxxxxxxxxxxxxxx
+      DJANGO_TMP_HOME: /tmp_home
+      DJANGO_PERSISTENT_HOME: /persistent_home
+      DJANGO_CORS_ALLOWED_ORIGIN: http://localhost:${WEB_FORMS_PORT:-5173}
+    ports:
+      - "${XLSFORM_ONLINE_PORT:-8558}:8000"
+
+  tests:
+    profiles: [test]
+    image: ghcr.io/getodk/web-forms:test
+    build:
+      context: ../..
+      dockerfile: contrib/containers/Containerfile
+      target: test
+    environment:
+      DISPLAY: :0
+    volumes:
+      - ../../packages/common:/app/packages/common
+      - ../../packages/web-forms:/app/packages/web-forms
+      # Mount each package individually to avoid overwriting generated dist
+      - ../../packages/xpath/src:/app/packages/xpath/src
+      - ../../packages/xforms-engine/src:/app/packages/xforms-engine/src
+      - ../../packages/xpath/test:/app/packages/xpath/test
+      - ../../packages/xforms-engine/test:/app/packages/xforms-engine/test
+      - /tmp/.X11-unix:/tmp/.X11-unix
+    command: ${TEST_CMD:-yarn run test}

packages/web-forms/README.md

@@ -67,6 +67,12 @@ Individual test environments, and their corresponding watch modes, also have sep
 
 Upload XLSForm and XForm functionality in [`demo`](./src/demo/) app and in dev mode depends on [XLSForm-online](https://github.com/getodk/xlsform-online). Run the xlsform-online locally. By default it runs on port 8000, if you are running it on another port then you should update the [`config`](./src/demo/config.json) file.
 
+### Running via containers
+
+In some cases, it may be simpler to run the web-forms preview via containers.
+
+See https://github.com/getodk/web-forms/tree/main/contrib/containers for details.
+
 ### Material Design
 
 This package uses the Material Design system for the UI, though not strictly. The idea is to closely match the design to that of [ODK Collect](https://docs.getodk.org/collect-intro/).

packages/web-forms/src/demo/config.json

@@ -1,3 +1,3 @@
 {
-  "xlsform-online-url": "http://localhost:8000"
+  "xlsform-online-url": "http://localhost:8558"
 }

packages/web-forms/vite.config.ts

@@ -114,6 +114,10 @@ export default defineConfig(({ mode }) => {
 				'/fonts': resolve('./src/assets/fonts'),
 			},
 		},
+		server: {
+			host: true,
+			port: 5173,
+		},
 		build: {
 			target: 'esnext',
 			/**