fix(admin): point the attention card at what is actually wrong

.ddev/addon-metadata/redis/manifest.yaml

@@ -0,0 +1,38 @@
+name: redis
+repository: ddev/ddev-redis
+version: v2.2.0
+install_date: "2026-07-04T11:24:16-04:00"
+project_files:
+    - docker-compose.redis.yaml
+    - redis/scripts/settings.ddev.redis.php
+    - redis/scripts/setup-drupal-settings.sh
+    - redis/scripts/setup-redis-optimized-config.sh
+    - redis/redis.conf
+    - redis/advanced.conf
+    - redis/append.conf
+    - redis/general.conf
+    - redis/io.conf
+    - redis/memory.conf
+    - redis/network.conf
+    - redis/security.conf
+    - redis/snapshots.conf
+    - commands/host/redis-backend
+    - commands/redis/redis-cli
+    - commands/redis/redis-flush
+global_files: []
+removal_actions:
+    - |
+      #ddev-description:Remove redis settings if applicable
+      files=(
+        "${DDEV_APPROOT}/${DDEV_DOCROOT}/sites/default/settings.ddev.redis.php"
+        "${DDEV_APPROOT}/.ddev/docker-compose.redis_extra.yaml"
+      )
+      for file in "${files[@]}"; do
+        if [ -f "$file" ]; then
+          if grep -q '#ddev-generated' "$file"; then
+            rm -f "$file"
+          else
+            echo "Unwilling to remove '$file' because it does not have #ddev-generated in it; you can manually delete it if it is safe to delete."
+          fi
+        fi
+      done

.ddev/commands/host/redis-backend

@@ -0,0 +1,124 @@
+#!/usr/bin/env bash
+#ddev-generated
+
+## Description: Use a different key-value store for Redis
+## Usage: redis-backend <image> [optimize]
+## Example: ddev redis-backend redis-alpine optimize
+
+REDIS_DOCKER_IMAGE=${1:-}
+REDIS_CONFIG=${2:-}
+NAME=$REDIS_DOCKER_IMAGE
+
+function show_help() {
+  cat <<EOF
+Usage: ddev redis-backend <image|alias> [optimize]
+
+Choose from predefined aliases, or provide any Redis-compatible Docker image.
+Note that not every Docker image can work right away, and you may need to override
+the "command:" in the docker-compose.redis_extra.yaml file
+
+Available aliases:
+  redis            redis:7
+  redis-alpine     redis:7-alpine
+  valkey           valkey/valkey:8
+  valkey-alpine    valkey/valkey:8-alpine
+
+Custom backend:
+  You can specify any Docker image, e.g.:
+    ddev redis-backend redis:6
+
+Optional:
+  optimize         Apply additional Redis configuration with resource limits
+  optimized        Same as optimize
+
+Examples:
+  ddev redis-backend redis-alpine optimize
+  ddev redis-backend valkey
+  ddev redis-backend redis:7.2-alpine
+EOF
+  exit 0
+}
+
+function optimize_config() {
+  [[ "$REDIS_CONFIG" != "optimized" && "$REDIS_CONFIG" != "optimize" ]] && return
+  ddev dotenv set .ddev/.env.redis --redis-optimized=true
+}
+
+function change_hostname() {
+  [[ "${REDIS_HOSTNAME:-}" == "" ]] && return
+  ddev dotenv set .ddev/.env.redis --redis-hostname="$REDIS_HOSTNAME"
+}
+
+function cleanup() {
+  rm -f "$DDEV_APPROOT/.ddev/.env.redis"
+  rm -rf "$DDEV_APPROOT/.ddev/redis/"
+  rm -f "$DDEV_APPROOT/.ddev/docker-compose.redis.yaml" "$DDEV_APPROOT/.ddev/docker-compose.redis_extra.yaml"
+
+  redis_volume="ddev-$(ddev status -j | docker run -i --rm ddev/ddev-utilities jq -r '.raw.name')_redis"
+  if docker volume ls -q | grep -qw "$redis_volume"; then
+    ddev stop
+    docker volume rm "$redis_volume"
+  fi
+}
+
+function check_docker_image() {
+  echo "Pulling ${REDIS_DOCKER_IMAGE}..."
+  if ! docker pull "$REDIS_DOCKER_IMAGE"; then
+    echo >&2 "❌ Unable to pull ${REDIS_DOCKER_IMAGE}"
+    exit 2
+  fi
+}
+
+function use_docker_image() {
+  [[ "$REDIS_DOCKER_IMAGE" != "redis:7" ]] && ddev dotenv set .ddev/.env.redis --redis-docker-image="$REDIS_DOCKER_IMAGE"
+  REPO=$(ddev add-on list --installed -j 2>/dev/null | docker run -i --rm ddev/ddev-utilities jq -r '.raw[] | select(.Name=="redis") | .Repository // empty' 2>/dev/null)
+  ddev add-on get "${REPO:-ddev/ddev-redis}"
+}
+
+case "$REDIS_DOCKER_IMAGE" in
+  redis)
+    NAME="Redis 7"
+    REDIS_DOCKER_IMAGE="redis:7"
+    ;;
+  redis-alpine)
+    NAME="Redis 7 Alpine"
+    REDIS_DOCKER_IMAGE="redis:7-alpine"
+    ;;
+  valkey)
+    NAME="Valkey 8"
+    REDIS_DOCKER_IMAGE="valkey/valkey:8"
+    REDIS_HOSTNAME="valkey"
+    ;;
+  valkey-alpine)
+    NAME="Valkey 8 Alpine"
+    REDIS_DOCKER_IMAGE="valkey/valkey:8-alpine"
+    REDIS_HOSTNAME="valkey"
+    ;;
+  ""|--help|-h)
+    show_help
+    ;;
+  *)
+    NAME="$REDIS_DOCKER_IMAGE"
+    # Allow unknown image, nothing to override
+    ;;
+esac
+
+check_docker_image
+cleanup
+optimize_config
+change_hostname
+use_docker_image
+
+echo
+echo "✅ Redis backend: $REDIS_DOCKER_IMAGE"
+if [[ "$REDIS_CONFIG" == "optimized" || "$REDIS_CONFIG" == "optimize" ]]; then
+  echo "⚙️ Redis config: optimized"
+else
+  echo "⚙️ Redis config: default"
+fi
+
+echo
+echo "📝 Commit the '.ddev' directory to version control"
+
+echo
+echo "🔄 Redis config available after 'ddev restart'"

.ddev/commands/redis/redis-cli

@@ -0,0 +1,13 @@
+#!/usr/bin/env sh
+
+#ddev-generated
+## Description: Run redis-cli inside the Redis container
+## Usage: redis-cli [flags] [args]
+## Example: "ddev redis-cli KEYS *" or "ddev redis-cli INFO" or "ddev redis-cli --version"
+## Aliases: redis
+
+if [ -f /etc/redis/conf/security.conf ]; then
+  redis-cli -p 6379 -h "${REDIS_HOSTNAME:-redis}" -a redis --no-auth-warning $@
+else
+  redis-cli -p 6379 -h "${REDIS_HOSTNAME:-redis}" $@
+fi

.ddev/commands/redis/redis-flush

@@ -0,0 +1,12 @@
+#!/usr/bin/env sh
+
+#ddev-generated
+## Description: Flush all cache inside the Redis container
+## Usage: redis-flush
+## Example: "ddev redis-flush"
+
+if [ -f /etc/redis/conf/security.conf ]; then
+  redis-cli -p 6379 -h "${REDIS_HOSTNAME:-redis}" -a redis --no-auth-warning FLUSHALL ASYNC
+else
+  redis-cli -p 6379 -h "${REDIS_HOSTNAME:-redis}" FLUSHALL ASYNC
+fi

.ddev/config.yaml

@@ -0,0 +1,75 @@
+name: convoy
+type: laravel
+docroot: public
+php_version: "8.4"
+webserver_type: nginx-fpm
+
+database:
+  type: postgres
+  version: "17"
+
+# Without this DDEV assigns a random ephemeral host port on every start, which
+# breaks saved connections in GUI clients (TablePlus, DataGrip, psql aliases).
+host_db_port: "5432"
+
+nodejs_version: "22"
+corepack_enable: false
+
+# ext-gmp is required by composer.json (prod Dockerfile installs it too).
+webimage_extra_packages:
+  - php8.4-gmp
+
+# Postgres + redis + mail overrides. These are real container env vars, so they
+# take precedence over .env (Laravel's Dotenv does not overwrite existing env).
+web_environment:
+  - APP_URL=https://convoy.ddev.site
+  - DB_CONNECTION=pgsql
+  - DB_HOST=db
+  - DB_PORT=5432
+  - DB_DATABASE=db
+  - DB_TEST_DATABASE=db_test
+  - DB_USERNAME=db
+  - DB_PASSWORD=db
+  - REDIS_HOST=redis
+  - REDIS_PORT=6379
+  - REDIS_PASSWORD=
+  - CACHE_STORE=redis
+  - QUEUE_CONNECTION=redis
+  - SESSION_DRIVER=redis
+  - MAIL_MAILER=smtp
+  - MAIL_HOST=localhost
+  - MAIL_PORT=1025
+
+# The test suite (RefreshDatabase) runs against a separate `db_test` database so
+# its migrate:fresh / sequence churn never touches dev data. Postgres has no
+# CREATE DATABASE IF NOT EXISTS, so createdb is guarded to stay idempotent.
+hooks:
+  post-start:
+    # Pin `db` in /etc/hosts to the real db container. Some Docker-sandbox setups
+    # give the web container a resolver with a search domain + ndots:0, so a bare
+    # `db` lookup can fall through to the sandbox host's wildcard DNS (which answers
+    # `db.<sandbox>.docker.internal` with an unrelated host-network Postgres) — and
+    # then PHP-FPM and `ddev exec` end up on DIFFERENT databases with the same
+    # DB_HOST (see docs/v5-next-handoff.md). This fix is sandbox-agnostic: `getent
+    # hosts db` gets the real container IP from docker's embedded DNS (authoritative
+    # for the service name), and pinning it in /etc/hosts makes nsswitch `files`
+    # win over DNS, closing the hole. A no-op where there's no collision. Re-run
+    # every start so it survives the container IP drifting.
+    - exec: "sudo bash -c 'H=$(getent hosts db | head -n1 | sed \"s/[[:space:]].*//\"); grep -qw db /etc/hosts || echo \"$H db\" >> /etc/hosts'"
+    - exec: "PGPASSWORD=db createdb -h db -U db db_test 2>/dev/null || true"
+
+# Replaces the compose `horizon` and `scheduler` services.
+web_extra_daemons:
+  - name: horizon
+    command: "php artisan horizon"
+    directory: /var/www/html
+  - name: scheduler
+    command: "php artisan schedule:work"
+    directory: /var/www/html
+
+# Expose the Vite dev server.
+web_extra_exposed_ports:
+  - name: vite
+    container_port: 3000
+    http_port: 3011
+    https_port: 3000

.ddev/docker-compose.redis.yaml

@@ -0,0 +1,27 @@
+#ddev-generated
+services:
+  redis:
+    container_name: ddev-${DDEV_SITENAME}-redis
+    image: ${REDIS_DOCKER_IMAGE:-redis:7}
+    hostname: ${REDIS_HOSTNAME:-redis}
+    # These labels ensure this service is discoverable by ddev.
+    labels:
+      com.ddev.site-name: ${DDEV_SITENAME}
+      com.ddev.approot: ${DDEV_APPROOT}
+    restart: "no"
+    expose:
+      - 6379
+    volumes:
+      - ".:/mnt/ddev_config"
+      - "ddev-global-cache:/mnt/ddev-global-cache"
+      - "./redis:/etc/redis/conf"
+      - "redis:/data"
+    command: /etc/redis/conf/redis.conf
+    x-ddev:
+      describe-url-port: |
+        Backend: ${REDIS_DOCKER_IMAGE:-redis:7}
+      describe-info: |
+        Pass: <none>
+
+volumes:
+  redis:

.ddev/docker-compose.victoriametrics.yaml

@@ -0,0 +1,23 @@
+services:
+  victoriametrics:
+    container_name: ddev-${DDEV_SITENAME}-victoriametrics
+    image: victoriametrics/victoria-metrics:v1.115.0
+    hostname: victoriametrics
+    # These labels ensure this service is discoverable by ddev.
+    labels:
+      com.ddev.site-name: ${DDEV_SITENAME}
+      com.ddev.approot: ${DDEV_APPROOT}
+    restart: "no"
+    expose:
+      - 8428
+    command:
+      - "-retentionPeriod=90d"
+      - "-storageDataPath=/victoria-metrics-data"
+    volumes:
+      - "victoriametrics:/victoria-metrics-data"
+    x-ddev:
+      describe-info: |
+        VictoriaMetrics: http://victoriametrics:8428
+
+volumes:
+  victoriametrics:

.ddev/redis/redis.conf

@@ -0,0 +1,13 @@
+# Redis configuration.
+# #ddev-generated
+# Example configuration files for reference:
+# http://download.redis.io/redis-stable/redis.conf
+# http://download.redis.io/redis-stable/sentinel.conf
+
+maxmemory 2048mb
+maxmemory-policy allkeys-lfu
+
+# to disable Redis persistence, remove ddev-generated from this file,
+# and uncomment the two lines below:
+#appendonly no
+#save ""

.dockerignore

@@ -0,0 +1,62 @@
+# Build context excludes. Keep this tight: the image build copies the whole
+# tree, and docs/pve-api alone is tens of megabytes of generated API reference
+# that has no business in a runtime image.
+
+.git
+.github
+.ddev
+.idea
+.vscode
+.claude
+.sbx
+.tanstack
+.tinker
+
+# Installed fresh inside the build so the image never inherits a host-built tree.
+node_modules
+vendor
+
+# Generated during the build (and gitignored), never copied in.
+public/build
+public/hot
+public/storage
+resources/scripts/wayfinder
+resources/scripts/routeTree.gen.ts
+resources/scripts/types/generated.d.ts
+resources/scripts/types/typescript-transformer-manifest.json
+
+# Local state that must not leak into a distributed image.
+.env
+.env.backup
+.env.ci
+storage/logs/*
+storage/framework/cache/data/*
+storage/framework/sessions/*
+storage/framework/views/*
+storage/*.key
+
+# Development-only tooling and docs.
+tests
+docs
+phpunit.xml
+phpstan.neon
+pint.json
+.phpunit.cache
+.phpunit.result.cache
+.styleci.yml
+stats.html
+CODE_OF_CONDUCT.md
+CONTRIBUTOR_LICENSE_AGREEMENT
+CHANGELOG.md
+AGENTS.md
+CLAUDE.md
+
+# The deployment tooling itself is delivered next to the compose file on the
+# host, not baked into the image -- except docker/entrypoint.d, copied explicitly.
+docker/install.sh
+docker/convoyctl
+
+**/.DS_Store
+**/._.DS_Store
+*.tmp.mjs
+*.tmp.php