Deploying Weaverse Themes with Docker

For production storefronts, use Shopify Oxygen — it is the officially supported target for Hydrogen. Docker is a good fit for development, testing, review apps, and infrastructure you must control yourself.

For other self-hosting targets, see the Shopify documentation on self-hosting Hydrogen. For a real-world containerized theme, the Naturelle Demo Repository shows a working Docker setup.

Quick Flow

Add a Dockerfile and .dockerignore

Multi-stage build; .dockerignore must exclude .env*.

Build the image with no secrets in it

docker build -t my-storefront .

Supply configuration at run time

docker run --env-file .env -p 3000:3000 my-storefront

Deploy

fly secrets set ... then fly deploy (or the equivalent for your platform).

How it works

The container runs npm run start, which is shopify hydrogen preview — a Node-based simulation of the Oxygen Workers runtime. Two consequences matter:

Runtime differences. Worker-specific behavior, caching, and performance characteristics are simulated, not identical to Oxygen. Validate anything runtime-sensitive before relying on it.
Network binding. The preview server binds to localhost by default, which is unreachable from outside the container. It has to listen on 0.0.0.0 for the container to serve traffic.

Security rules

Never COPY a .env file into the image, and never bake credentials into a build layer. Docker image layers are readable by anyone who can pull the image — docker history and layer extraction expose them, and deleting the file in a later layer does not remove it from the earlier one. Secrets belong in the runtime environment, not the image.

Concretely:

Add .env* to .dockerignore so env files never enter the build context.
Do not use ENV or build args for tokens, API keys, or SESSION_SECRET.
Pass configuration at container start: --env-file, -e, your orchestrator’s secret store, or fly secrets.
Rotate any credential that has already been committed to an image or to Git.

Prerequisites

Docker (latest stable version)
Node.js — the Pilot theme requires >=22.12.0
Fly.io CLI if you are following the Fly example
A Weaverse theme project that builds locally (npm run build succeeds)

Configuration Files

1. `.dockerignore`

Create this first, so the build context never contains secrets or junk:

.dockerignore

# Secrets — never send these to the Docker daemon
.env
.env.*
.dev.vars

# Dependencies
node_modules

# Logs and temporary files
*.log
.DS_Store
.cache

# Version control
.git
.github

# Build outputs
dist
.react-router
.shopify

# Tests
test-results
playwright-report

.env.example is safe to keep out too — the pattern .env.* excludes it, and the image does not need it.

2. `Dockerfile`

Dockerfile

# Pilot requires Node >=22.12.0
FROM node:22-bookworm-slim AS base

# SSL and CA certificates for outbound Shopify/Weaverse API calls
RUN apt-get update && \
    apt-get install -y --no-install-recommends openssl ca-certificates && \
    apt-get clean && \
    rm -rf /var/lib/apt/lists/*

# ---- Build stage ----
FROM base AS build
WORKDIR /myapp

COPY package*.json .npmrc ./
RUN npm ci

COPY . .

# Bind the preview server to 0.0.0.0 so the container is reachable.
# This patches CLI internals, so the file paths shift between versions —
# the step warns rather than fails if a path is gone, but re-check it
# after upgrading @shopify/cli or @shopify/mini-oxygen.
RUN set -eu; \
    patched=0; \
    for f in \
      $(find node_modules/@shopify -type f -name "workerd*.js" 2>/dev/null); do \
        if grep -q 'host: "localhost"' "$f"; then \
            sed -i -e 's|host: "localhost"|host: "0.0.0.0"|' "$f"; \
            echo "patched host binding in $f"; \
            patched=1; \
        fi; \
    done; \
    [ "$patched" = "1" ] || echo "WARNING: no workerd host binding patched — verify the container is reachable"

RUN npm run build

# ---- Production stage ----
FROM base AS production
WORKDIR /myapp

ENV NODE_ENV=production
ENV PORT=3000

# Copy build output only. No .env, no credentials — configuration is
# injected at run time.
COPY --from=build /myapp/dist /myapp/dist
COPY --from=build /myapp/node_modules /myapp/node_modules
COPY --from=build /myapp/package.json /myapp/package.json

EXPOSE 3000
CMD ["npm", "run", "start"]

npm run start runs shopify hydrogen preview, which lives in @shopify/cli — a dev dependency. That is why the production stage copies the full node_modules from the build stage rather than running npm ci --omit=dev.

3. Environment variables

Keep a local .env for development (it is already in the theme’s .gitignore), and use .env.example as the reference list of variables your theme reads:

.env

SESSION_SECRET=your-session-secret
PUBLIC_STORE_DOMAIN=your-store.myshopify.com
PUBLIC_STOREFRONT_API_TOKEN=your-storefront-api-token
PUBLIC_CUSTOMER_ACCOUNT_API_CLIENT_ID=your-customer-account-client-id
SHOP_ID=your-shop-id
WEAVERSE_PROJECT_ID=your-weaverse-project-id

Run the container with those values injected at start time. Before deploying, verify that the installed Shopify CLI version exposes the process environment as Hydrogen worker bindings:

docker build -t my-storefront .

# From a local env file (the file stays on your machine)
docker run --rm -p 3000:3000 --env-file .env my-storefront

# Or individually
docker run --rm -p 3000:3000 \
  -e SESSION_SECRET=... \
  -e PUBLIC_STORE_DOMAIN=your-store.myshopify.com \
  -e WEAVERSE_PROJECT_ID=... \
  my-storefront

Exercise a route that reads the required bindings after the container starts. If your CLI version does not forward the process environment, write a .env file at container start from the injected values via an entrypoint script — never at build time. The file then exists only in the running container’s writable layer, not in the distributable image.

Cloud Deployment (Fly.io)

1. `fly.toml`

fly.toml

app = 'your-app-name'
primary_region = 'sin'

[http_service]
  internal_port = 3000
  force_https = true
  auto_stop_machines = true
  auto_start_machines = true
  min_machines_running = 0

[[vm]]
  memory = '1024mb'
  cpu_kind = 'shared'
  cpus = 1

Do not put tokens or SESSION_SECRET in the [env] section of fly.toml — that file is committed to Git. Use fly secrets instead.

2. Set secrets

Fly secrets are encrypted at rest and injected into the machine’s environment at run time:

fly secrets set \
  SESSION_SECRET=... \
  PUBLIC_STORE_DOMAIN=your-store.myshopify.com \
  PUBLIC_STOREFRONT_API_TOKEN=... \
  PUBLIC_CUSTOMER_ACCOUNT_API_CLIENT_ID=... \
  SHOP_ID=... \
  WEAVERSE_PROJECT_ID=...

# Import a whole local env file at once
fly secrets import < .env

# Review what is set (names only, values are never shown)
fly secrets list

Setting a secret triggers a rolling restart so the new values take effect.

3. Deploy

fly launch   # first time only — generates/updates fly.toml
fly deploy

fly status
fly logs

The same pattern applies elsewhere: ECS task definition secrets, Cloud Run --set-secrets, Kubernetes Secret + envFrom, Render/Railway environment settings. All of them inject variables into the process environment, which is exactly what the container expects.

Troubleshooting

Container starts but nothing responds on the mapped port The host binding patch did not apply. Check the build log for the WARNING: no workerd host binding patched line and re-check the CLI file layout for your @shopify/cli version. Build failures Confirm the Node version in the base image satisfies the theme’s engines.node (>=22.12.0), that npm run build succeeds locally, and that Docker has enough memory allocated. Missing configuration at run time Check the values actually reached the container: docker exec <container> printenv | sort, or fly ssh console -C printenv. Variable names are case-sensitive. Weaverse Studio preview does not load Verify WEAVERSE_PROJECT_ID is set in the running environment and that the deployed URL is registered on your Weaverse project. See Preview Errors.

Limitations and Considerations

Runtime simulation — shopify hydrogen preview approximates the Workers runtime in Node. Not every Worker API or performance characteristic matches Oxygen.
Image size — the production stage ships the full node_modules because the preview server is part of the Shopify CLI.
Operational ownership — scaling, TLS, log retention, and monitoring are yours to configure. Oxygen handles these for you.

Deploy to Oxygen — the recommended production path
Deploy to Cloudflare Workers
Custom Domain and DNS
Shopify: Self-hosting Hydrogen

Environment

Building Components

Content Management

Internationalization

Security & Privacy

Pages & Routing

Advanced

Deployment

Deploy with Docker

Deploying Weaverse Themes with Docker

Quick Flow

How it works

Security rules

Prerequisites

Configuration Files

1. `.dockerignore`

2. `Dockerfile`

3. Environment variables

Cloud Deployment (Fly.io)

1. `fly.toml`

2. Set secrets

3. Deploy

Troubleshooting

Limitations and Considerations

​Deploying Weaverse Themes with Docker

​Quick Flow

​How it works

​Security rules

​Prerequisites

​Configuration Files

​1. .dockerignore

​2. Dockerfile

​3. Environment variables

​Cloud Deployment (Fly.io)

​1. fly.toml

​2. Set secrets

​3. Deploy

​Troubleshooting

​Limitations and Considerations

​Related

Deploying Weaverse Themes with Docker

Quick Flow

How it works

Security rules

Prerequisites

Configuration Files

1. `.dockerignore`

2. `Dockerfile`

3. Environment variables

Cloud Deployment (Fly.io)

1. `fly.toml`

2. Set secrets

3. Deploy

Troubleshooting

Limitations and Considerations

Related