> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vulpy.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Environment variables reference for Vulpy Commerce

> A catalog of the environment variables that configure Vulpy Commerce: install, Fox, data directories, storefront, analytics, and build-time flags.

Vulpy Commerce is configured through environment variables stored in `.env` at the project root for local development, and in `environments/<name>/.env` for each deployed environment. Some variables are evaluated at build time and baked into images, while others are read at runtime.

This page catalogs the variables Vulpy Commerce recognizes. Medusa and Payload also read their own upstream variables. For the full upstream lists, see the [Medusa configuration docs](https://docs.medusajs.com/) and the [Payload configuration docs](https://payloadcms.com/docs).

<Tip>
  **Ask Fox to set env vars in dev.** These tables are the map; Fox knows which vars are bake-time and can add or change them in your `.env` for you.

  Try prompts like:

  * "Which env vars are bake-time?"
  * "Add `NEXT_PUBLIC_GTM_ID=GTM-XXX` to my dev env."
  * "Diff my dev `.env` against `.env.example`."
</Tip>

## Install and lifecycle

| Variable               | Purpose                                                                    | Notes                                                                                                                               |
| ---------------------- | -------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `VULPY_IMDS_LOCK`      | Blocks EC2/Lightsail IMDS access from the host and containers.             | Default is enabled. Set to `0` to opt out so Fox can use the VM IAM role for Bedrock. Check status with `pnpm vulpy hermes doctor`. |
| `COMPOSE_PROJECT_NAME` | Docker Compose project name used to isolate environments.                  | Changing this lets you run dev, staging, and live as separate Compose projects.                                                     |
| `SEED_ON_START`        | Whether to seed sample data when Medusa starts.                            | Useful for fresh installs and CI.                                                                                                   |
| `SYNC_PUBLISHABLE_KEY` | Whether to synchronize the Medusa publishable API key across environments. | Helps keep storefront keys consistent during deploys.                                                                               |

## Data directories

| Variable             | Purpose                                | Notes                              |
| -------------------- | -------------------------------------- | ---------------------------------- |
| `POSTGRES_DATA_DIR`  | Host path for Postgres data.           | Defaults under `.data/postgres/`.  |
| `REDIS_DATA_DIR`     | Host path for Redis data.              | Defaults under `.data/redis/`.     |
| `MATOMO_DATA_DIR`    | Host path for Matomo application data. | Defaults under `.data/matomo/`.    |
| `MATOMO_DB_DATA_DIR` | Host path for the Matomo database.     | Defaults under `.data/matomo-db/`. |

<Warning>
  Do not place data directories on NTFS or exFAT volumes when running on Linux. Postgres and Redis require POSIX file semantics, and NTFS/exFAT can cause permission and locking errors.
</Warning>

## Storefront and CMS

| Variable                   | Purpose                                                           | Notes                                                                                |
| -------------------------- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| `PAYLOAD_SECRET`           | Secret key used by Payload CMS for authentication and encryption. | Must be set before starting the CMS.                                                 |
| `CMS_STRICT`               | Enables strict validation in Payload CMS.                         | Set to enforce stricter schema and field checks.                                     |
| `NEXT_PUBLIC_GTM_ID`       | Google Tag Manager container ID for the storefront.               | Injected into the Next.js build.                                                     |
| `REQUIRE_LOGIN_FOR_PRICES` | Requires customer authentication before showing product prices.   | **Bake-time variable.** Changing it requires rebuilding the storefront Docker image. |

<Warning>
  `REQUIRE_LOGIN_FOR_PRICES` is baked into the storefront image at build time. If you change this value, rebuild and redeploy the storefront container for the change to take effect.
</Warning>

## Domains

These labels are used during install and can be overridden per environment.

| Variable         | Purpose                                     | Default              |
| ---------------- | ------------------------------------------- | -------------------- |
| `SHOP_DOMAIN`    | Public domain for the storefront.           | Set during install.  |
| `PREVIEW_DOMAIN` | Domain for preview deployments.             | Set during install.  |
| `API_DOMAIN`     | Domain for the Medusa API.                  | Set during install.  |
| `MATOMO_DOMAIN`  | Domain for the self-hosted Matomo instance. | `analytics.<domain>` |

## Fox and WebUI

| Variable              | Purpose                                                 | Notes                                       |
| --------------------- | ------------------------------------------------------- | ------------------------------------------- |
| `VULPY_WEBUI_IFRAMES` | Controls whether the Fox WebUI allows iframe embedding. | Adjust based on your security requirements. |

## Next steps

<CardGroup cols={2}>
  <Card title="Production deploy checklist" icon="server" href="/deploy/production">
    Review the steps to take an environment live, including domain and env var verification.
  </Card>

  <Card title="CLI reference" icon="terminal" href="/reference/cli">
    See the full list of pnpm vulpy commands for managing environments, Fox, and edge nodes.
  </Card>
</CardGroup>