Skip to content
Open Data Capture

Playground Deployment

The instrument playground is the in-browser editor hosted at playground.opendatacapture.org. You can also host your own copy, for example to keep instrument development on your institution’s network. This guide deploys the playground’s Docker image behind a reverse proxy. It assumes the same prerequisites as the deployment guide: a Linux server, a domain name whose DNS records you control, Docker, and an HTTP server such as Caddy.

The playground is a static website with no database and no backend, so it can run on its own or alongside an existing Open Data Capture instance.

Why the Playground Needs Two Hostnames

The playground runs the instrument you are editing in a preview panel. That instrument is code, and it may come from someone else, for example through a share link. The playground also stores your work and, once you log in to upload an instrument, your access token in the browser. To keep the two apart, the preview is served from a different origin than the editor, so code running in the preview cannot read anything the editor has stored.

In practice, this means you need two hostnames that both point at the same playground container. For example:

  • playground.myplatform.com serves the editor.
  • playground-preview.myplatform.com serves the preview.

You tell the playground which hostname serves the preview with the PLAYGROUND_PREVIEW_ORIGIN environment variable. The container reads it when it starts, so the published image works for any domain without a rebuild. If the variable is not set, or names the editor’s own address, the playground refuses to run previews and shows Preview Unavailable instead.

Steps

Step 1: Configure the DNS Records

Add an A record for each of the two hostnames, both pointing to your server’s IP address:

TypeNameValueTTL
Aplayground192.168.1.1Auto
Aplayground-preview192.168.1.1Auto

Step 2: Launch the Container

The image is published to the GitHub Container Registry as ghcr.io/douglasneuroinformatics/open-data-capture-playground. The latest tag is the current stable release, and each release is also tagged with its version number (for example, 2.5.0). Inside the container, the playground listens on port 80.

If you have already deployed Open Data Capture by following the deployment guide, the playground is part of the same Docker Compose stack. From the directory where you cloned the repository, add the preview address to .env:

Terminal window
PLAYGROUND_PREVIEW_ORIGIN=https://playground-preview.myplatform.com

Then start the playground service. It publishes the playground on port 3750 of the host:

Terminal window
docker compose up -d playground

Otherwise, you can run the image on its own, without cloning the repository:

Terminal window
docker run -d \
  --name open-data-capture-playground \
  --restart unless-stopped \
  -p 3750:80 \
  -e PLAYGROUND_PREVIEW_ORIGIN=https://playground-preview.myplatform.com \
  ghcr.io/douglasneuroinformatics/open-data-capture-playground:latest

In either case, PLAYGROUND_PREVIEW_ORIGIN must be a full address, including https://, with no path. If you change it later, restart the container for the change to take effect.

Step 3: Configure the Web Server

Route both hostnames to the container. If you are using Caddy, add the following to /etc/caddy/Caddyfile:

Terminal window
playground.myplatform.com, playground-preview.myplatform.com {
  reverse_proxy localhost:3750
}

Then reload Caddy:

Terminal window
systemctl reload caddy

Caddy obtains an HTTPS certificate for each hostname automatically.

Step 4: Verify the Deployment

First, check that the container picked up the preview address:

Terminal window
curl https://playground.myplatform.com/config.json

The response should name your preview hostname:

{ "previewOrigin": "https://playground-preview.myplatform.com" }

Then open playground.myplatform.com in your browser. After the editor loads, the default instrument should render in the right panel.

Troubleshooting

“No preview origin is configured for this host.” PLAYGROUND_PREVIEW_ORIGIN did not reach the container, and /config.json returns an empty previewOrigin. Check that the variable is set in .env (or passed with -e), then recreate the container with docker compose up -d playground.

“The preview origin is the same as this page.” PLAYGROUND_PREVIEW_ORIGIN names the address you opened the editor on. Set it to the second hostname, and open the editor on the first.

The preview panel shows a connection error or stays empty. The browser cannot load the preview hostname. Check that its DNS record has propagated and that your web server routes it to the container, by opening playground-preview.myplatform.com directly. It should show the playground’s editor.

The page shows an error instead of the editor. The playground could not read /config.json. This happens when the built files are served by a web server other than the playground’s own container. In that case, serve a config.json file next to index.html with the content shown in Step 4.