Skip to main content

Deploy Headless Turbo Theme

The Headless Turbo theme is independently hosted. Your team is responsible for the production environment, application credentials, domain, TLS, monitoring, and rollback.

This page includes deployment guidance for:

  • Boltic using the included Dockerfile and boltic.yaml
  • AWS EC2 using Docker or the Fastify Node.js server
  • Cloudflare Workers using static assets and an edge-side API proxy

All options serve the same React production build. The Node.js and container options run Fastify for static assets, runtime credential injection, API proxying, and SPA fallback. Cloudflare Workers must implement equivalent behavior at the edge.

Review Prerequisites​

  • Node.js 20 or later
  • Git
  • A Fynd application ID and public-scope application token
  • Docker for Boltic or container-based EC2 deployment
  • A hosting account and provider CLI where required
warning

APPLICATION_TOKEN is injected into the storefront HTML and can be read by visitors and allowed scripts. Use only a public-scope token. Never deploy a partner-level, private, or privileged token.

Build for Production​

Create an optimized build using your preferred package manager. The following commands are equivalent examples:

# npm
npm ci
npm run build

# pnpm
pnpm install --frozen-lockfile
pnpm build

Webpack writes the generated assets to dist/. Verify the build locally:

# npm
npm start

# pnpm
pnpm start

Use one package manager consistently and commit its lockfile. If a pnpm lockfile is not available yet, run pnpm install once to generate it before using --frozen-lockfile in CI.

Open http://localhost:8080 and test the critical commerce flows before deployment.

Configure the Runtime​

Configure these values through the hosting platform:

VariableRequiredDefaultPurpose
PROXY_TARGETNo (recommended)https://api.fynd.comFynd API origin used by the proxy
DOMAINNoapi.fynd.comFallback API domain
APPLICATION_IDYes—Sales channel application ID
APPLICATION_TOKENYes—Public-scope sales channel token
PORTNo8080Fastify listening port
BUILD_IDNoturbo-fastify-v1Identifier returned by /__version
USE_PROXY*NofalseUses same-origin API proxying

PROXY_TARGET falls back to https://api.fynd.com when unset, so it is not strictly required, but setting it explicitly is still recommended for clarity and for non-default environments.

* USE_PROXY is read at build time (via Webpack's DefinePlugin) and baked into the client bundle — it is not a Fastify runtime variable. Set it before running the build command, not on the runtime host. It has no effect if you deploy a prebuilt dist/ and only set it at runtime.

Keep credentials in the provider's environment or secret store. Do not commit production credentials in .env, boltic.yaml, wrangler.toml, Docker images, or CI logs.

Deploy on Boltic​

Boltic builds the included multi-stage Dockerfile using boltic.yaml.

  1. Update the application name and non-secret runtime values in boltic.yaml:

    app: "your-store-name"
    region: "asia-south1"

    build:
      dockerfile: Dockerfile
      ignorefile: .gitignore

    env:
      PROXY_TARGET: "https://api.fynd.com"
      DOMAIN: "api.fynd.com"
      BUILD_ID: "your-build-id"
      USE_PROXY: "true"
      PORT: "8080"

  2. Configure APPLICATION_ID and APPLICATION_TOKEN through the Boltic environment or secret configuration.

  3. Push the repository to trigger the build.

  4. Monitor the deployment in the Boltic dashboard.

  5. Configure the custom domain and point its DNS record to the Boltic URL.

Verify the deployment:

curl https://your-app.boltic.app/__health
curl https://your-app.boltic.app/__version

Deploy on AWS EC2​

Docker is the recommended EC2 approach because it uses the repository's tested runtime image.

  1. Provision an EC2 instance with inbound HTTPS and restricted SSH access.

  2. Install Docker and Git.

  3. Clone and build the image:

    git clone https://github.com/gofynd/HeadlessTurbo.git
    cd HeadlessTurbo
    docker build -t headless-turbo .

  4. Run the container:

    docker run -d \
      --name headless-turbo \
      --restart unless-stopped \
      -p 8080:8080 \
      -e PROXY_TARGET="https://api.fynd.com" \
      -e DOMAIN="api.fynd.com" \
      -e APPLICATION_ID="your_application_id" \
      -e APPLICATION_TOKEN="your_public_application_token" \
      -e BUILD_ID="headless-turbo-ec2-v1" \
      -e USE_PROXY="true" \
      -e PORT="8080" \
      headless-turbo

  5. Put a load balancer or Nginx in front of port 8080 to terminate HTTPS.

  6. Configure the custom domain and certificate.

For direct Node.js deployment, install dependencies and create a production build with your selected package manager. Run server.js with a process manager such as PM2 and place it behind an HTTPS reverse proxy.

Deploy on Cloudflare Workers​

Cloudflare Workers does not run the Fastify server directly. The Worker must reproduce its production responsibilities:

  • Serve assets from dist/
  • Proxy /service, /ext, and /graphql to PROXY_TARGET
  • Return index.html for client-side routes
  • Inject application credentials safely at request time
  • Harden proxied cookies and preserve security controls
  • Expose health and version endpoints

  1. Install Wrangler using your preferred package manager, and then authenticate:

    # npm
    npm install --global wrangler

    # pnpm
    pnpm add --global wrangler

    # Run after either installation command
    wrangler login

  2. Configure the Worker and bind dist/ as its static asset directory.

  3. Add the complete edge proxy implementation from the repository Deployment Guide.

  4. Store credentials as encrypted secrets:

    wrangler secret put APPLICATION_ID
    wrangler secret put APPLICATION_TOKEN

  5. Build and deploy:

    # npm
    npm run build

    # pnpm
    pnpm build

    # Run after either build command
    wrangler deploy

  6. Add a custom domain in Cloudflare Workers settings.

Do not deploy only the static dist/ files. That omits API proxying, runtime credential injection, SPA fallback, and server-side security controls.

Verify the Production Deployment​

Verify the Runtime​

  • GET /__health returns {"status":"ok"}.
  • GET /__version returns the deployed build identifier.
  • Direct navigation to client-side routes does not return 404.
  • The deployment environment can reach PROXY_TARGET.

Verify Commerce Flows​

  • Home, PLP, PDP, search, cart, login, checkout, account, and order flows work.
  • Data comes from the intended sales channel.
  • Cookies persist correctly through the same-origin proxy.

Verify Operations and Security​

  • HTTPS and the custom domain are active.
  • The configured token has public scope only.
  • Application logs, uptime monitoring, and alerts are enabled.
  • A previous deployment is available for rollback.
  • Third-party scripts are minimized and use version pinning and Subresource Integrity where supported.