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 serves the production build with vite preview, as the theme’s npm run start script does (vite preview --port 3456 on Hydrogen 2026.10). The oxygen() Vite plugin from @shopify/mini-oxygen runs the built worker in a local workerd runtime behind Vite’s preview server. 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. Pass Vite’s --host 0.0.0.0 so the container can 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.18.0 || ^24.11.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.18.0 || ^24.11.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 . .

RUN npm run build

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

ENV NODE_ENV=production
ENV PORT=3000

# Copy the built project. `vite preview` loads `vite.config.ts`, whose
# React Router plugin reads `react-router.config.ts` and `app/`, so the
# source tree is needed next to `dist/`. No .env, no credentials:
# `.dockerignore` keeps them out of the build context, and configuration
# is injected at run time.
COPY --from=build /myapp /myapp

EXPOSE 3000
# Bind to 0.0.0.0 so the container is reachable
CMD ["npx", "vite", "preview", "--host", "0.0.0.0", "--port", "3000"]

vite and @shopify/mini-oxygen are dev dependencies, and vite preview runs the same Vite config as the build, including the React Router plugin. That is why the production stage copies the whole project from the build stage (full node_modules, app/, react-router.config.ts and any local files the config imports) rather than only dist/ with npm ci --omit=dev. Copying only dist/ fails at startup with Could not find a root route module.

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. The Oxygen Vite plugin passes the process environment (plus any .env file) to the worker as bindings; before deploying, verify that your @shopify/mini-oxygen version still does:

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 Mini Oxygen 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 preview server is listening on localhost. Check that the container command passes --host 0.0.0.0, and that --port matches the port you publish (-p 3000:3000) and Fly’s internal_port. Build failures Confirm the Node version in the base image satisfies the theme’s engines.node (^22.18.0 || ^24.11.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 — vite preview with Mini Oxygen runs the worker in a local workerd. Not every Worker API or performance characteristic matches Oxygen.
Image size — the production stage ships the full project and node_modules because the preview server comes from dev dependencies (vite, @shopify/mini-oxygen) and loads the project’s Vite config.
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

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