The Vulpy edge: Caddy, TLS, and sslip.io

The Vulpy edge is a Caddy reverse proxy that terminates TLS, routes hostnames to services, and falls back to sslip.io when no domain is configured.

The Vulpy edge is a Caddy container that terminates TLS and routes incoming hostnames to the correct backend service. It handles SHOP_DOMAIN, PREVIEW_DOMAIN, API_DOMAIN, and MATOMO_DOMAIN, so shoppers, admins, and analytics all reach the right container securely.

Ask Fox to explain and draft edge changes. Fox reviews the Caddy config in dev and drafts changes for you to apply on the server.

Try prompts like:

• “What is the edge serving right now on dev?”
• “Explain how Caddy chooses TLS.”
• “Draft a Caddy directive for a custom redirect.”

What the edge does

Caddy sits in front of the storefront, Medusa, Payload, and Matomo. When a request arrives, it matches the hostname and forwards traffic to the right upstream. It also requests and renews TLS certificates automatically via ACME.

Access modes and the edge

Vulpy Commerce supports four access modes. The edge behaves differently in each:

Mode	How it works
Tailscale (default)	Caddy is not exposed publicly. Fox uses the Tailscale sidecar for HTTPS. The edge still routes internally.
Own domain	Caddy terminates TLS for your domain and serves it publicly.
No domain	Caddy falls back to sslip.io hostnames automatically.
Both	Tailscale and public domain work together.

For Tailscale-only setups, see Tailscale access.

Edge CLI commands

Use these commands from the host (not inside the Fox container):

# Start the edge
pnpm vulpy edge up

# Stop the edge
pnpm vulpy edge down

# Check edge status
pnpm vulpy edge status

# Tail edge logs
pnpm vulpy edge logs

ACME and certificate issuance

When you point a domain at the VPS, Caddy requests certificates from Let’s Encrypt or ZeroSSL. Certificates are requested only after DNS resolves correctly. If DNS is wrong, Caddy will retry with exponential backoff.

For DNS setup guidance, see DNS configuration.

sslip.io fallback

If no domain is configured, the edge automatically serves <ip>.sslip.io hostnames. This lets you access the shop and admin immediately without buying or configuring a domain.

Add a preview domain

1. Set the preview domain

   Run pnpm vulpy env set-domain <name> and enter your preview domain when prompted.

2. Point DNS

   Create an A record at your DNS provider that points the preview domain to the VPS IP.

3. Start the edge

   Run pnpm vulpy edge up to apply the new hostname and request a certificate.

Custom Caddy directives

You can add custom Caddy directives by editing the deploy Caddyfile in the repo. After making changes, rebuild the edge container so the new configuration is loaded.

Repeated ACME failures enter backoff. If DNS was wrong, fix the record and give the edge time to retry, or restart the edge container to reset the backoff state.

DNS configuration

Point domains and verify DNS before going live.

Going live

Promote staging to live with the golive command.