Install Vulpy Commerce on your machine

Set up Vulpy Commerce locally with pnpm bootstrap, understand the .data layout, and configure data directory overrides for NTFS or exFAT hosts.

Installing Vulpy Commerce locally means bootstrapping the storefront, Medusa, Postgres, and the seed data, then optionally starting Fox on top. This page covers the full local flow and the data directory options you may need on non-ext4 hosts.

The fastest path is to ask Fox. Once the bootstrap is done and Fox is up, the WebUI walks you through the rest and can fix drift for you.

Try prompts like:

• “Set up my .env for local dev.”
• “Move Postgres data to /mnt/data.”
• “Run pnpm bootstrap and tell me if anything failed.”

Prerequisites

• Node.js 20 or newer
• pnpm 9 or newer
• Docker with the Compose plugin

Bootstrap

pnpm bootstrap is the full first-time setup. It writes env files, installs dependencies, starts Postgres and Redis, runs Medusa migrations, seeds the catalog, creates an admin user, and syncs the publishable key.

Full bootstrap

pnpm bootstrap

Use pnpm bootstrap:env when you only need env files and want to skip Docker.

Day-to-day commands

Start storefront and Medusa

pnpm dev

pnpm db:reseed wipes .data/postgres and recreates the databases. Do not run it against a shop that has real data you care about.

Data layout

All Docker persistence lives under .data/ in the project folder. .data/ is gitignored.

.data/
├── postgres/       # PostgreSQL (dev + prod)
├── redis/
├── medusa-static/  # production uploads
├── payload-media/  # production CMS media
├── matomo/         # production Matomo app files
├── matomo-db/      # production Matomo MariaDB
└── ...

On NTFS or exFAT hosts (for example, a /mnt/data external drive), Postgres, Redis, and Matomo (app plus MariaDB) auto-fall back to ~/.local/share/<project>/…. Override with POSTGRES_DATA_DIR, REDIS_DATA_DIR, MATOMO_DATA_DIR, and MATOMO_DB_DATA_DIR in .env.

Multiple shops on one host

COMPOSE_PROJECT_NAME defaults to the project folder name, so you can clone Vulpy Commerce into two folders on the same machine and run them side by side without container name collisions. Set it explicitly in .env if you rename a checkout.

Quickstart

A compact version of this flow that gets you to the WebUI fast.

Architecture

See how the storefront, Medusa, Fox, and Matomo fit together.