diff --git a/.gitignore b/.gitignore
index 7b565b16..3b0c2cbc 100644
--- a/.gitignore
+++ b/.gitignore
@@ -8,4 +8,5 @@ static/api.json
 data/
 bin/
 coverage/
-.idea/
\ No newline at end of file
+.idea/
+.docker/.debug
diff --git a/README.md b/README.md
index f794d989..29e86273 100644
--- a/README.md
+++ b/README.md
@@ -69,3 +69,14 @@ curl --location --request GET 'http://localhost:5000/bucket' \
 
 To perform your tests you can run the following command: `npm test`
 
+### Running in context
+
+Sometimes it is useful to test changes in the context of the entire stack (e.g. a project running via the Supabase cli). The `replace-existing-container.sh` script builds an image and replace an existing running container with it. All settings of the existing container are preserved (volumes, network, env, etc).
+
+```bash
+# Start supabase project - in root of supabase project "PROJECT-NAME"
+supabase start
+
+# In root of storage api repo
+./scripts/replace-existing-container.sh supabase_storage_PROJECT-NAME
+```
diff --git a/scripts/replace-existing-container.sh b/scripts/replace-existing-container.sh
new file mode 100755
index 00000000..a729ee12
--- /dev/null
+++ b/scripts/replace-existing-container.sh
@@ -0,0 +1,74 @@
+#!/bin/bash
+
+##############################################################################
+#
+# Replace Existing Container
+#
+# This script builds a new docker image from the current code,
+# and replaces a running supabase storage container with it
+# it can be used to test changes in the context of other services (e.g. supabase cli)
+#
+##############################################################################
+
+set -euo pipefail
+
+if [ "$#" -ne 1 ]; then
+  echo "Usage: $0 <replace_container_name>"
+  exit 1
+fi
+
+REPLACE_CONTAINER_NAME="$1"
+NEW_IMAGE_TAG="storage-api:debug-replace-existing"
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+TARGET_DIR="$SCRIPT_DIR/../../.docker/.debug"
+DOCKER_COMPOSE_PATH="$TARGET_DIR/$REPLACE_CONTAINER_NAME.yml"
+
+# check if specified container exists / is running
+if ! docker ps --format '{{.Names}}' | grep -q "^${REPLACE_CONTAINER_NAME}$"; then
+  echo "Error: Docker container '$REPLACE_CONTAINER_NAME' is not running."
+  exit 1
+fi
+
+# ensure target docker-compose directory exists
+mkdir -p "$TARGET_DIR"
+
+# build storage api
+echo " "
+echo "[1/5] Building \"$NEW_IMAGE_TAG\" image from current storage code..."
+echo " "
+docker build -t "$NEW_IMAGE_TAG" .
+
+# create docker compose file based on the running image
+echo " "
+echo "[2/5] Generating docker-compose file from existing container..."
+echo " "
+docker pull ghcr.io/red5d/docker-autocompose:latest
+docker run --rm -v /var/run/docker.sock:/var/run/docker.sock ghcr.io/red5d/docker-autocompose "$REPLACE_CONTAINER_NAME" > "$DOCKER_COMPOSE_PATH"
+
+# update docker-compose to use newly built image
+OLD_IMAGE=$(grep 'image:' "$DOCKER_COMPOSE_PATH" | awk '{print $2}' | head -n 1)
+echo " "
+echo "[3/5] Replacing image $OLD_IMAGE with \"$NEW_IMAGE_TAG\"..."
+echo " "
+sed -i.bak "s|image: $OLD_IMAGE|image: $NEW_IMAGE_TAG|" "$DOCKER_COMPOSE_PATH"
+
+# stop and remove storage container
+echo " "
+echo "[4/5] Stopping existing \"$REPLACE_CONTAINER_NAME\" container..."
+echo " "
+docker rm -f "$REPLACE_CONTAINER_NAME"
+
+# start new container to replace existing
+echo "  "
+echo "[5/5] Starting new container..."
+echo "  "
+docker-compose -f "$DOCKER_COMPOSE_PATH" up -d
+
+echo " "
+echo "✅ New \"$REPLACE_CONTAINER_NAME\" container is running"
+echo " "
+echo "You can update the container by running this script again"
+echo " "
+echo "To watch logs run: docker logs -f $REPLACE_CONTAINER_NAME"
+echo " "