Deploying Weaverse Themes with Docker

Important: For production deployments, use Shopify Oxygen. Docker deployment is recommended only for development and testing.

Note: mini-oxygen in Docker simulates the Workers environment and requires environment variables to be set via .env file, not through cloud platform settings.

For a complete working example, check out our Naturelle Demo Repository which demonstrates Docker deployment configuration in a real Weaverse theme project.

For other options to deploy your Hydrogen project, including platforms like Vercel, Netlify, and Cloudflare Workers, please refer to the Shopify documentation on self-hosting Hydrogen.

Understanding Docker Deployment

Docker deployment for Weaverse themes uses mini-oxygen, a Node.js-based simulation of the Shopify Workers environment. This approach has several important characteristics:

Environment Simulation:
- Runs in Node.js instead of actual Workers runtime
- Some Worker-specific features might behave differently
- Useful for development and testing, but not ideal for production
Network Binding:
- Requires special handling for host binding (localhost → 0.0.0.0)
- Enables access from outside the container
- Essential for cloud deployment scenarios
Environment Variables:
- Must use .env file approach
- Cloud platform environment settings won't work
- Simulates Worker environment variable access

Prerequisites

Docker (latest stable version)
Node.js (LTS version)
Fly.io CLI (for Fly.io deployment)
A Weaverse theme project

Configuration Files

1. Dockerfile

Create a Dockerfile in your project root:

FROM node:lts-bookworm-slim as base
# Install essential SSL and security certificatesRUN apt-get update && \    apt-get install -y --no-install-recommends openssl ca-certificates && \    apt-get clean && \    rm -rf /var/lib/apt/lists/*
# Build stage for compiling and preparing the applicationFROM base as buildWORKDIR /myapp
# Install dependencies using package filesCOPY package*.json .npmrc ./RUN npm ci
# Copy all source filesCOPY . .
# Patch the workerd configuration for container compatibility# This is necessary because:# 1. Default localhost binding doesn't work in containers# 2. External access requires 0.0.0.0 binding# 3. Both Shopify CLI and Hydrogen files need patchingRUN set -e && \    WORKERD_FILE=$(find node_modules/@shopify/cli/dist -type f -name "workerd-*.js") && \    if [ -f "$WORKERD_FILE" ]; then \        sed -i -e 's|host: "localhost"|host: "0.0.0.0"|' "$WORKERD_FILE"; \    else \        echo "workerd file not found" && exit 1; \    fi && \    HYDROGEN_WORKERD_FILE="node_modules/@shopify/cli-hydrogen/dist/lib/mini-oxygen/workerd.js" && \    if [ -f "$HYDROGEN_WORKERD_FILE" ]; then \        sed -i -e 's|host: "localhost"|host: "0.0.0.0"|' "$HYDROGEN_WORKERD_FILE"; \    else \        echo "hydrogen workerd file not found" && exit 1; \    fi
# Build the applicationRUN npm run build
# Production stage with minimal footprintFROM base as productionWORKDIR /myapp
# Set runtime environmentENV NODE_ENV=productionENV FLY="true"ENV PORT="3000"
# Copy only necessary files from build stageCOPY --from=build /myapp/dist /myapp/distCOPY --from=build /myapp/node_modules /myapp/node_modulesCOPY --from=build /myapp/package.json /myapp/package.jsonCOPY --from=build /myapp/.env /myapp/.env
EXPOSE 3000CMD ["npm", "run", "start"]

2. .dockerignore

Create a .dockerignore to optimize build context and improve security:

# Dependencies/node_modules
# Logs and temporary files*.log.DS_Store/.cache
# Version control.git
# Build outputs/dist
# Shopify specific/.shopify

3. Environment Configuration

Create a .env file in your project root:

# Shopify ConfigurationSHOPIFY_STORE_DOMAIN=your-store.myshopify.comSHOPIFY_STOREFRONT_API_TOKEN=your-token
# Additional configurations as needed# PUBLIC_STORE_DOMAIN=your-public-domain.com# SESSION_SECRET=your-session-secret

Cloud Deployment (Fly.io)

1. Fly.io Configuration

Create fly.toml:

# Application Configurationapp = 'your-app-name'primary_region = 'sin'
# HTTP Service Configuration[http_service]  internal_port = 3000  force_https = true  auto_stop_machines = true  auto_start_machines = true  min_machines_running = 0
# Virtual Machine Configuration[[vm]]  memory = '1024mb'  cpu_kind = 'shared'  cpus = 1

2. Deployment Steps

Initialize deployment:

fly launch

Deploy the application:

fly deploy

Monitor deployment:

# Check statusfly status
# View logsfly logs

Troubleshooting Guide

Common Issues and Solutions

Build Failures:
- Verify Node.js version compatibility
- Check for missing dependencies
- Ensure Docker has enough resources
Runtime Errors:
- Check container logs: fly logs
- Verify environment variables
- Confirm port configurations
Performance Issues:
- Monitor resource usage
- Check for memory leaks
- Verify network connectivity

Limitations and Considerations

Worker Environment Simulation:
- Not all Worker features are available
- Performance characteristics differ
- Some APIs might behave differently
Environment Variables:
- Must use .env file approach
- No support for cloud platform env settings
- Careful management of sensitive data required
Production Readiness:
- Consider using Shopify Oxygen for production
- Docker deployment best for development/testing
- Monitor resource usage and performance

Deploy with Docker

Deploying Weaverse Themes with Docker