Custom Share Providers¶

You can customize the built-in providers or create your own share providers in .ddev/share-providers/.

Customizing Built-in Providers¶

Take Ownership of a Built-in Provider¶

1. Edit the provider script (e.g., .ddev/share-providers/ngrok.sh)
2. Remove the #ddev-generated line at the top
3. Make your changes
4. DDEV will never overwrite this file again

Create a Custom Variant¶

# Copy built-in provider
cp .ddev/share-providers/ngrok.sh .ddev/share-providers/my-ngrok.sh

# Edit my-ngrok.sh:
# - Remove '#ddev-generated' line
# - Customize as needed

# Use your variant
ddev share --provider=my-ngrok

Creating a New Provider¶

Create a new executable script in .ddev/share-providers/:

#!/usr/bin/env bash
set -euo pipefail

# Start your tunnel tool
mytunnel http "$DDEV_LOCAL_URL" &
TUNNEL_PID=$!

trap "kill $TUNNEL_PID 2>/dev/null || true" EXIT

# Capture public URL (however your tool exposes it)
URL=$(get-tunnel-url)

# Output URL to stdout (CRITICAL: first line only)
echo "$URL"

# Wait for tunnel to exit
wait $TUNNEL_PID

Provider Script Contract¶

Every share provider must follow this contract:

Input (Environment Variables)¶

All standard DDEV environment variables are also available.

Output¶

• stdout: Public URL (first line only - captured by DDEV)
• stderr: Logs, status messages (passed through to user)

Lifecycle¶

1. Validate tool is installed
2. Validate required environment variables
3. Start tunnel process in background
4. Capture public URL (via API, stdout, file, etc.)
5. Output URL to stdout
6. Wait for tunnel process to exit

Signal Handling¶

Providers must handle SIGINT (Ctrl+C) and SIGTERM gracefully. Use trap to cleanup background processes:

cleanup() {
    if kill -0 $PID 2>/dev/null; then
        kill $PID 2>/dev/null || true
    fi
}
trap cleanup EXIT

Hooks Integration¶

After the tunnel URL is captured, DDEV sets the DDEV_SHARE_URL environment variable and runs pre-share hooks. This allows you to alter projects as needed (like WordPress ddev wp search-replace, for example).

Example .ddev/config.share.yaml:

hooks:
  pre-share:
    - exec: |
        echo "Tunnel URL: ${DDEV_SHARE_URL}"
        wp search-replace ${DDEV_PRIMARY_URL} ${DDEV_SHARE_URL}

Troubleshooting Custom Providers¶

Provider not found:

Error: share provider 'foo' not found

Check that .ddev/share-providers/foo.sh exists and is executable:

ls -la .ddev/share-providers/
chmod +x .ddev/share-providers/foo.sh

Provider outputs no URL:

Error: provider 'ngrok' did not output a URL

Common causes: tool not installed, authentication required, no internet. Debug by running the provider directly:

export DDEV_LOCAL_URL=http://127.0.0.1:8080
.ddev/share-providers/ngrok.sh