> ## 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.

# 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.

<Tip>
  **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?"
</Tip>

## 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

<Steps>
  <Step title="Create the environment">
    ```bash theme={null}
    pnpm vulpy env add staging
    ```

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

  <Step title="Point DNS or use a preview host">
    Set `pnpm vulpy env set-domain staging --domain staging.example.com`, or leave the default preview host.
  </Step>

  <Step title="Bring it up">
    ```bash theme={null}
    pnpm vulpy env up staging
    pnpm vulpy env status staging
    ```
  </Step>
</Steps>

<Warning>
  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.
</Warning>

<CardGroup cols={2}>
  <Card title="Deploy to a VPS" icon="server" href="/deploy/production">
    Bootstrap Ubuntu 24.04, install Fox and dev, then add live.
  </Card>

  <Card title="Go live" icon="rocket" href="/deploy/going-live">
    Add live, point DNS, and cut over from preview to apex.
  </Card>
</CardGroup>