Environments: dev, staging, and live

Vulpy Commerce isolates dev, staging, and live as separate Docker Compose projects with their own data, env files, and public ports.

Vulpy Commerce treats each environment as a boundary. Every environment (dev, staging, live) is its own Docker Compose project with a dedicated env file, its own .data/<env>/ directory, and its own public ports. Fox lives only in dev; staging and live are human-only.

Ask Fox to explain and draft; you run the env commands. Fox refuses env lifecycle commands by design, but it’s the fastest way to plan and review.

Try prompts like:

• “Explain what pnpm vulpy env add staging will do.”
• “Draft the DNS records I need before I run this.”
• “What’s the current state of dev?”

The environment model

From vulpy.yaml, the supported environments today are dev, staging, and live. Each environment has:

• environments/<name>/.env, the source of truth for its configuration
• .data/<name>/, its persistent Docker state
• Its own compose project name so containers do not collide

Dev is sleeping: true (it wakes on demand). Live is sleeping: false. Staging and any additional production-like environments use the production compose overlay and must define unique HTTP and HTTPS ports if they share a host.

Lifecycle commands

Day-2 environment commands run as the deploy user (sudo -iu vulpy-commerce), never as root.

Command	What it does
pnpm vulpy env add <name>	Create a new environment (domains, build, start). For live, includes Matomo setup.
pnpm vulpy env up <name>	Start the environment’s services.
pnpm vulpy env down <name>	Stop the environment’s services.
pnpm vulpy env status <name>	Show service and health status.
pnpm vulpy env logs <name>	Tail service logs.
pnpm vulpy env set-domain <name> --domain example.com	Set or update the environment’s domain.
pnpm vulpy env sync <name>	Sync configuration into the environment.
pnpm vulpy env golive <name>	Cut over from preview to public on live. Refuses without Matomo.
pnpm vulpy env backup <name>	Create a backup archive of the environment.
pnpm vulpy env restore <name> <archive>	Restore an environment from a backup archive.

Add a staging environment

1. Create the environment

   pnpm vulpy env add staging
   

   The command scaffolds environments/staging/, wires the Compose overlay, and asks for a domain.

2. Point DNS or use a preview host

   Set pnpm vulpy env set-domain staging --domain staging.example.com, or leave the default preview host.

3. Bring it up

   pnpm vulpy env up staging
   pnpm vulpy env status staging
   

Fox cannot run environment commands. pnpm vulpy env add|up|down|golive all refuse inside the Hermes container, and live and staging directories are hidden from Fox’s workspace mount.

Deploy to a VPS

Bootstrap Ubuntu 24.04, install Fox and dev, then add live.

Go live

Add live, point DNS, and cut over from preview to apex.