build: add config for running web-forms via containers

Author: spwoodcock

contrib/containers/Containerfile

@@ -0,0 +1,20 @@
+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
+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 \
+        "python3" \
+    && rm -rf /var/lib/apt/lists/*
+COPY . .
+RUN corepack enable && corepack install
+RUN yarn install
+# Build packages as a sanity check
+RUN yarn workspace @getodk/tree-sitter-xpath build
+RUN yarn workspace @getodk/xpath build
+RUN yarn workspace @getodk/xforms-engine build

contrib/containers/README.md

@@ -0,0 +1,22 @@
+# 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:3221

contrib/containers/compose.yaml

@@ -0,0 +1,23 @@
+services:
+  web-forms:
+    image: ghcr.io/getodk/web-forms:main
+    build:
+      context: ../..
+      dockerfile: contrib/containers/Containerfile
+    volumes:
+      - ../../packages:/app/packages
+    ports:
+      - "${WEB_FORMS_PORT:-3221}:3221"
+    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:-3221}
+    ports:
+      - "${XLSFORM_ONLINE_PORT:-8558}:8000"

packages/web-forms/README.md

@@ -39,6 +39,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: 3221,
+		},
 		build: {
 			target: 'esnext',
 			/**